presence: documentation for retrieve_order_by parameter

modules/presence/README

@@ -12,8 +12,6 @@ Edited by
 
 Anca-Maria Vamanu
 
-Edited by
-
 Juha Heinanen
 
    Copyright © 2006 Voice Sistem SRL
@@ -63,7 +61,8 @@ Juha Heinanen
               3.28. subs_remove_match (int)
               3.29. xavp_cfg (str)
               3.30. retrieve_order (int)
-              3.31. sip_uri_match (int)
+              3.31. retrieve_order_by (str)
+              3.32. sip_uri_match (int)
 
         4. Functions
 
@@ -147,15 +146,16 @@ Juha Heinanen
    1.28. Set subs_remove_match parameter
    1.29. Set xavp_cfg parameter
    1.30. Set retrieve_order parameter
-   1.31. Set sip_uri_match parameter
-   1.32. handle_publish usage
-   1.33. handle_subscribe usage
-   1.34. pres_auth_status usage
-   1.35. pres_refresh_watchers usage
-   1.36. pres_update_watchers usage
-   1.37. $subs(name) usage
-   1.38. $notify_reply(name) usage
+   1.31. Set retrieve_order_by parameter
+   1.32. Set sip_uri_match parameter
+   1.33. handle_publish usage
+   1.34. handle_subscribe usage
+   1.35. pres_auth_status usage
+   1.36. pres_refresh_watchers usage
+   1.37. pres_update_watchers usage
+   1.38. $subs(name) usage
    1.39. $notify_reply(name) usage
+   1.40. $notify_reply(name) usage
    2.1. presence_api_t structure
 
 Chapter 1. Admin Guide
@@ -200,7 +200,8 @@ Chapter 1. Admin Guide
         3.28. subs_remove_match (int)
         3.29. xavp_cfg (str)
         3.30. retrieve_order (int)
-        3.31. sip_uri_match (int)
+        3.31. retrieve_order_by (str)
+        3.32. sip_uri_match (int)
 
    4. Functions
 
@@ -305,7 +306,8 @@ Chapter 1. Admin Guide
    3.28. subs_remove_match (int)
    3.29. xavp_cfg (str)
    3.30. retrieve_order (int)
-   3.31. sip_uri_match (int)
+   3.31. retrieve_order_by (str)
+   3.32. sip_uri_match (int)
 
 3.1. db_url(str)
 
@@ -752,8 +754,9 @@ if(is_method("PUBLISH")) {
 
 3.30. retrieve_order (int)
 
-   If set to 0, presentity records are retrieve by received_time order. if
-   set to 1, presentity records are retrieve by priority order.
+   If set to 0, presentity records are retrieve by received_time order. If
+   set to 1, presentity records are retrieve by the value of
+   retrieve_order_by parameter.
 
    Default value is 0.
 
@@ -762,7 +765,19 @@ if(is_method("PUBLISH")) {
 modparam("presence", "retrieve_order", 1)
 ...
 
-3.31. sip_uri_match (int)
+3.31. retrieve_order_by (str)
+
+   Used to set the order-by of the db query for fetching the presence
+   records when retrieve_order is set to 1.
+
+   Default value is "priority".
+
+   Example 1.31. Set retrieve_order_by parameter
+...
+modparam("presence", "retrieve_order_by", "priority, received_time")
+...
+
+3.32. sip_uri_match (int)
 
    The mode used when comparing uris.
 
@@ -772,7 +787,7 @@ modparam("presence", "retrieve_order", 1)
 
    Default value is "0".
 
-   Example 1.31. Set sip_uri_match parameter
+   Example 1.32. Set sip_uri_match parameter
             ...
             modparam("presence", "sip_uri_match", 1)
             ...
@@ -805,7 +820,7 @@ modparam("presence", "retrieve_order", 1)
 
    The module sends an appropriate stateless reply in all cases.
 
-   Example 1.32. handle_publish usage
+   Example 1.33. handle_publish usage
 ...
         if(is_method("PUBLISH"))
         {
@@ -836,7 +851,7 @@ modparam("presence", "retrieve_order", 1)
 
    The module sends an appropriate stateless reply in all cases.
 
-   Example 1.33. handle_subscribe usage
+   Example 1.34. handle_subscribe usage
 ...
 if(method=="SUBSCRIBE")
     handle_subscribe();
@@ -853,7 +868,7 @@ if(method=="SUBSCRIBE")
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.34. pres_auth_status usage
+   Example 1.35. pres_auth_status usage
 ...
 if (method=="MESSAGE") {
     pres_auth_status("$fu", $ru");
@@ -889,7 +904,7 @@ if (method=="MESSAGE") {
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.35. pres_refresh_watchers usage
+   Example 1.36. pres_refresh_watchers usage
 ...
 pres_refresh_watchers("sip:[email protected]", "presence", 1);
 ...
@@ -907,7 +922,7 @@ pres_refresh_watchers("sip:[email protected]", "presence", 1);
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.36. pres_update_watchers usage
+   Example 1.37. pres_update_watchers usage
 ...
 pres_update_watchers("sip:[email protected]", "presence");
 ...
@@ -1013,7 +1028,7 @@ pres_update_watchers("sip:[email protected]", "presence");
      * flags
      * user_agent
 
-   Example 1.37. $subs(name) usage
+   Example 1.38. $subs(name) usage
 ...
 if(handle_subscription())
 {
@@ -1029,7 +1044,7 @@ if(handle_subscription())
 
    The "attr" can be any pseudo var that accesses attributes of msg
 
-   Example 1.38. $notify_reply(name) usage
+   Example 1.39. $notify_reply(name) usage
 ...
 event_route[presence:notify-reply]
 {
@@ -1045,7 +1060,7 @@ event_route[presence:notify-reply]
 
    Fired after notify reply is received or timeout.
 
-   Example 1.39. $notify_reply(name) usage
+   Example 1.40. $notify_reply(name) usage
 ...
 event_route[presence:notify-reply]
 {

modules/presence/doc/presence_admin.xml

@@ -780,7 +780,8 @@ if(is_method("PUBLISH")) {
 	    <title><varname>retrieve_order</varname> (int)</title>
 	    <para>
 		If set to 0, presentity records are retrieve by received_time order.
-		if set to 1, presentity records are retrieve by priority order.
+		If set to 1, presentity records are retrieve by the value of
+		retrieve_order_by parameter.
 	    </para>
 	    <para>
 		<emphasis>
@@ -797,6 +798,28 @@ modparam("presence", "retrieve_order", 1)
 	    </example>
 	</section>
 
+
+	<section id="presence.p.retrieve_order_by">
+	    <title><varname>retrieve_order_by</varname> (str)</title>
+	    <para>
+		Used to set the order-by of the db query for fetching the presence
+		records when retrieve_order is set to 1.
+	    </para>
+	    <para>
+		<emphasis>
+			Default value is <quote>priority</quote>.
+		</emphasis>
+	    </para>
+	    <example>
+		<title>Set <varname>retrieve_order_by</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("presence", "retrieve_order_by", "priority, received_time")
+...
+</programlisting>
+	    </example>
+	</section>
+
 <section id="presence.p.sip_uri_match">
     <title><varname>sip_uri_match</varname> (int)</title>
     <para>