ndb_mongodb: documented mongodb_find_one(...) cfg command

modules/ndb_mongodb/README

@@ -10,7 +10,7 @@ Daniel-Constantin Mierla
 
    <[email protected]>
 
-   Copyright © 2014 asipto.com
+   Copyright © 2014 asipto.com
      __________________________________________________________________
 
    Table of Contents
@@ -34,8 +34,11 @@ Daniel-Constantin Mierla
                       replyid)
 
               4.3. mongodb_find(srvname, dbname, cname, command, replyid)
-              4.4. mongodb_next(replyid)
-              4.5. mongodb_free(replyid)
+              4.4. mongodb_find_one(srvname, dbname, cname, command,
+                      replyid)
+
+              4.5. mongodb_next(replyid)
+              4.6. mongodb_free(replyid)
 
    List of Examples
 
@@ -43,8 +46,9 @@ Daniel-Constantin Mierla
    1.2. mongodb_cmd usage
    1.3. mongodb_cmd_simple usage
    1.4. mongodb_find usage
-   1.5. mongodb_next usage
-   1.6. mongodb_free usage
+   1.5. mongodb_find_one usage
+   1.6. mongodb_next usage
+   1.7. mongodb_free usage
 
 Chapter 1. Admin Guide
 
@@ -65,8 +69,9 @@ Chapter 1. Admin Guide
         4.1. mongodb_cmd(srvname, dbname, cname, command, replyid)
         4.2. mongodb_cmd_simple(srvname, dbname, cname, command, replyid)
         4.3. mongodb_find(srvname, dbname, cname, command, replyid)
-        4.4. mongodb_next(replyid)
-        4.5. mongodb_free(replyid)
+        4.4. mongodb_find_one(srvname, dbname, cname, command, replyid)
+        4.5. mongodb_next(replyid)
+        4.6. mongodb_free(replyid)
 
 1. Overview
 
@@ -124,10 +129,11 @@ modparam("ndb_mongodb", "server", "name=mgs2;uri='mongodb://127.0.0.2/kamailio'"
    4.1. mongodb_cmd(srvname, dbname, cname, command, replyid)
    4.2. mongodb_cmd_simple(srvname, dbname, cname, command, replyid)
    4.3. mongodb_find(srvname, dbname, cname, command, replyid)
-   4.4. mongodb_next(replyid)
-   4.5. mongodb_free(replyid)
+   4.4. mongodb_find_one(srvname, dbname, cname, command, replyid)
+   4.5. mongodb_next(replyid)
+   4.6. mongodb_free(replyid)
 
-4.1. mongodb_cmd(srvname, dbname, cname, command, replyid)
+4.1.  mongodb_cmd(srvname, dbname, cname, command, replyid)
 
    Send a valid command to MongoDB server identified by srvname. The reply
    will be stored in a local container identified by replyid. All the
@@ -159,7 +165,7 @@ if(mongodb_cmd("mgs1", "kamailio", "acc", "{ \"collStats\": \"acc\" }", "mgr1"))
 }
 ...
 
-4.2. mongodb_cmd_simple(srvname, dbname, cname, command, replyid)
+4.2.  mongodb_cmd_simple(srvname, dbname, cname, command, replyid)
 
    Send a valid command to MongoDB server identified by srvname. The reply
    will be stored in a local container identified by replyid. All the
@@ -185,7 +191,7 @@ mgr1")) {
 }
 ...
 
-4.3. mongodb_find(srvname, dbname, cname, command, replyid)
+4.3.  mongodb_find(srvname, dbname, cname, command, replyid)
 
    Send a find command to MongoDB server identified by srvname. The reply
    will be stored in a local container identified by replyid. All the
@@ -214,14 +220,31 @@ if(mongodb_find("mgs1", "kamailio", "acc", "{ \"src_user\" : \"111\" }", "mgr1")
 }
 ...
 
-4.4. mongodb_next(replyid)
+4.4.  mongodb_find_one(srvname, dbname, cname, command, replyid)
+
+   Similar to mongodb_find(...), but it stops searching after first match,
+   returning the result with one object - faster when expecting to have a
+   single match. Parameters and behaviour are the same as for
+   mongodb_find(...).
+
+   The function can be used from ANY_ROUTE.
+
+   Example 1.5. mongodb_find_one usage
+...
+if(mongodb_find_one("mgs1", "kamailio", "subscriber", "{ \"username\" : \"111\"
+}", "mgr1")) {
+        xlog("response from mongodb is [[$mongodb(mgr1=>value)]]\n");
+}
+...
+
+4.5.  mongodb_next(replyid)
 
    Moves to next document in a MongoDB reply. This function can be used
    after a succesful mongodb_cmd() or mongodb_find(). It returns true if
    there is a shift to document. The current document becomes available
    via $mongodb(key) variable.
 
-   Example 1.5. mongodb_next usage
+   Example 1.6. mongodb_next usage
 ...
 if(mongodb_find("mgs1", "kamailio", "acc", "{ \"src_user\" : \"111\" }", "mgr1")
 ) {
@@ -233,7 +256,7 @@ if(mongodb_find("mgs1", "kamailio", "acc", "{ \"src_user\" : \"111\" }", "mgr1")
 mongodb_free("mgr1");
 ...
 
-4.5. mongodb_free(replyid)
+4.6.  mongodb_free(replyid)
 
    Frees data in a previous reply from memory. After this function call,
    accessing to a freed replyid returns null value.
@@ -243,7 +266,7 @@ mongodb_free("mgr1");
    execution, but for freeing used resources (e.g., memory), it is
    recommended to do it.
 
-   Example 1.6. mongodb_free usage
+   Example 1.7. mongodb_free usage
 ...
 if(mongodb_cmd_simple("mgs1", "kamailio", "acc", "{ \"collStats\": \"acc\" }", "
 mgr1")) {

modules/ndb_mongodb/doc/ndb_mongodb_admin.xml

@@ -230,6 +230,30 @@ if(mongodb_find("mgs1", "kamailio", "acc", "{ \"src_user\" : \"111\" }", "mgr1")
 	xlog("response from mongodb is [[$mongodb(mgr1=>value)]]\n");
 }
 ...
+</programlisting>
+	    </example>
+	</section>
+	<section id="ndb_mongodb.f.mongodb_find_one">
+	    <title>
+		<function moreinfo="none">mongodb_find_one(srvname, dbname, cname, command, replyid)</function>
+	    </title>
+	    <para>
+			Similar to mongodb_find(...), but it stops searching after first
+			match, returning the result with one object - faster when expecting
+			to have a single match. Parameters and behaviour are the same
+			as for mongodb_find(...).
+		</para>
+		<para>
+			The function can be used from ANY_ROUTE.
+		</para>
+		<example>
+		<title><function>mongodb_find_one</function> usage</title>
+		<programlisting format="linespecific">
+...
+if(mongodb_find_one("mgs1", "kamailio", "subscriber", "{ \"username\" : \"111\" }", "mgr1")) {
+	xlog("response from mongodb is [[$mongodb(mgr1=>value)]]\n");
+}
+...
 </programlisting>
 	    </example>
 	</section>