dmq: Adding KDMQ message example to documentation

modules/dmq/README

@@ -6,6 +6,10 @@ Charles Chance
 
    Sipcentric Ltd.
 
+Olle E. Johansson
+
+   Edvina AB
+
 Edited by
 
 Marius Ovidiu Bucur
@@ -14,9 +18,11 @@ Edited by
 
 Charles Chance
 
-   Copyright © 2011 Marius Bucur
+   Copyright © 2011 Marius Bucur
 
-   Copyright © 2013 Charles Chance, Sipcentric Ltd.
+   Copyright © 2013 Charles Chance, Sipcentric Ltd.
+
+   Copyright © 2015 Olle E. Johansson, Edvina AB
      __________________________________________________________________
 
    Table of Contents
@@ -58,15 +64,16 @@ Charles Chance
 
    List of Examples
 
-   1.1. Set server_address parameter
-   1.2. Set notification_address parameter
-   1.3. Set num_workers parameter
-   1.4. Set ping_interval parameter
-   1.5. dmq_handle_message usage
-   1.6. dmq_send_message usage
-   1.7. dmq_bcast_message usage
-   1.8. dmq_t_replicate usage
-   1.9. dmq_is_from_node usage
+   1.1. Example of a KDMQ message
+   1.2. Set server_address parameter
+   1.3. Set notification_address parameter
+   1.4. Set num_workers parameter
+   1.5. Set ping_interval parameter
+   1.6. dmq_handle_message usage
+   1.7. dmq_send_message usage
+   1.8. dmq_bcast_message usage
+   1.9. dmq_t_replicate usage
+   1.10. dmq_is_from_node usage
    2.1. dmq_api_t structure
    2.2. register_dmq_peer usage
    2.3. bcast_message usage
@@ -113,6 +120,29 @@ Chapter 1. Admin Guide
    grouping of peers can be compared to a topic in a typical pub/sub
    system.
 
+   DMQ sends SIP requests using the KDMQ request method, that is private
+   to Kamailio.
+
+   Example 1.1. Example of a KDMQ message
+
+   This message is for basic DMQ bus handling. Other messages are produced
+   by other modules, like the htable module.
+KDMQ sip:[email protected]:5090 SIP/2.0
+Via: SIP/2.0/UDP 192.168.40.15;branch=z9hG4bK55e5.423d95110000
+To: <sip:[email protected]:5090>
+From: <sip:[email protected]:5060>;tag=2cdb7a33a7f21abb98fd3a44968
+e3ffd-5b01
+CSeq: 10 KDMQ
+Call-ID: [email protected]
+Content-Length: 116
+User-Agent: kamailio (4.3.0 (x86_64/linneaus))
+Max-Forwards: 1
+Content-Type: text/plain
+
+sip:192.168.40.16:5060;status=active
+sip:192.168.40.15:5060;status=disabled
+sip:192.168.40.17:5060;status=active
+
 2. Dependencies
 
    2.1. Kamailio Modules
@@ -142,9 +172,9 @@ Chapter 1. Admin Guide
    The local server address. This is the interface over which the DMQ
    engine will send/receive messages.
 
-   Default value is “NULL�.
+   Default value is "NULL".
 
-   Example 1.1. Set server_address parameter
+   Example 1.2. Set server_address parameter
 ...
 modparam("dmq", "server_address", "sip:10.0.0.20:5060")
 ...
@@ -154,9 +184,9 @@ modparam("dmq", "server_address", "sip:10.0.0.20:5060")
    The address of another DMQ node from which the local node should
    retrieve initial information about all other nodes.
 
-   Default value is “NULL�.
+   Default value is "NULL".
 
-   Example 1.2. Set notification_address parameter
+   Example 1.3. Set notification_address parameter
 ...
 modparam("dmq", "notification_address", "sip:10.0.0.21:5060")
 ...
@@ -165,9 +195,9 @@ modparam("dmq", "notification_address", "sip:10.0.0.21:5060")
 
    The number of worker threads for sending/receiving messages.
 
-   Default value is “2�.
+   Default value is "2".
 
-   Example 1.3. Set num_workers parameter
+   Example 1.4. Set num_workers parameter
 ...
 modparam("dmq", "num_threads", 4)
 ...
@@ -177,9 +207,9 @@ modparam("dmq", "num_threads", 4)
    The number of seconds between node pings (for checking status of other
    nodes).
 
-   Minimum value is “60� (default).
+   Minimum value is "60" (default).
 
-   Example 1.4. Set ping_interval parameter
+   Example 1.5. Set ping_interval parameter
 ...
 modparam("dmq", "ping_interval", 90)
 ...
@@ -192,14 +222,14 @@ modparam("dmq", "ping_interval", 90)
    4.4. dmq_t_replicate([skip_loop_test])
    4.5. dmq_is_from_node()
 
-4.1.  dmq_handle_message()
+4.1. dmq_handle_message()
 
    Handles a DMQ message by passing it to the appropriate local peer
    (module). The peer is identified by the user part of the To header.
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.5. dmq_handle_message usage
+   Example 1.6. dmq_handle_message usage
 ...
         if(is_method("KDMQ"))
         {
@@ -207,7 +237,7 @@ modparam("dmq", "ping_interval", 90)
         }
 ...
 
-4.2.  dmq_send_message(peer, node, body, content_type)
+4.2. dmq_send_message(peer, node, body, content_type)
 
    Sends a DMQ message directly from config file to a single node.
 
@@ -219,13 +249,13 @@ modparam("dmq", "ping_interval", 90)
 
    This function can be used from any route.
 
-   Example 1.6. dmq_send_message usage
+   Example 1.7. dmq_send_message usage
 ...
         dmq_send_message("peer_name", "sip:10.0.0.21:5060", "Message body...", "
 text/plain");
 ...
 
-4.3.  dmq_bcast_message(peer, body, content_type)
+4.3. dmq_bcast_message(peer, body, content_type)
 
    Broadcasts a DMQ message from config file to all active nodes (except
    self).
@@ -237,12 +267,12 @@ text/plain");
 
    This function can be used from any route.
 
-   Example 1.7. dmq_bcast_message usage
+   Example 1.8. dmq_bcast_message usage
 ...
         dmq_bcast_message("peer_name", "Message body...", "text/plain");
 ...
 
-4.4.  dmq_t_replicate([skip_loop_test])
+4.4. dmq_t_replicate([skip_loop_test])
 
    Replicates the current SIP message to all active nodes (except self).
    Useful for replicating REGISTER, PUBLISH etc. in a clustered
@@ -259,19 +289,19 @@ text/plain");
 
    This function can be used from REQUEST_ROUTE only.
 
-   Example 1.8. dmq_t_replicate usage
+   Example 1.9. dmq_t_replicate usage
 ...
         dmq_t_replicate();
 ...
 
-4.5.  dmq_is_from_node()
+4.5. dmq_is_from_node()
 
    Checks whether the current message has been sent by another DMQ node in
    the cluster.
 
    This function can be used from REQUEST_ROUTE only.
 
-   Example 1.9. dmq_is_from_node usage
+   Example 1.10. dmq_is_from_node usage
 ...
         # Example REGISTER block
         if (dmq_is_from_node()) {
@@ -301,7 +331,7 @@ Chapter 2. Developer Guide
    The module provides the following functions that can be used in other
    Kamailio modules.
 
-1.  dmq_load_api(dmq_api_t* api)
+1. dmq_load_api(dmq_api_t* api)
 
    This function binds the DMQ module and fills the structure with the
    exported functions below.
@@ -315,7 +345,7 @@ typedef struct dmq_api {
 } dmq_api_t;
 ...
 
-2.  register_dmq_peer(dmq_peer_t* peer)
+2. register_dmq_peer(dmq_peer_t* peer)
 
    Registers an entity as a DMQ peer which permits receiving/sending
    messages between nodes which support the same peer.
@@ -325,7 +355,7 @@ typedef struct dmq_api {
         Example to follow.
 ...
 
-3.  bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except,
+3. bcast_message(dmq_peer_t* peer, str* body, dmq_node_t* except,
 dmq_resp_cback_t* resp_cback, int max_forwards, str* content_type)
 
    Broadcast a DMQ message to all nodes in the DMQ bus excluding self,
@@ -336,7 +366,7 @@ dmq_resp_cback_t* resp_cback, int max_forwards, str* content_type)
         Example to follow.
 ...
 
-4.  send_message(dmq_peer_t* peer, str* body, dmq_node_t* node,
+4. send_message(dmq_peer_t* peer, str* body, dmq_node_t* node,
 dmq_resp_cback_t* resp_cback, int max_forwards, str* content_type)
 
    Send a DMQ message to a single node.

modules/dmq/doc/dmq_admin.xml

@@ -26,6 +26,36 @@
 	Peers are grouped by name in order to ensure the correct messages are passed to the relevant peers. 
 	This grouping of peers can be compared to a topic in a typical pub/sub system.
 	</para>
+	<para>
+	DMQ sends SIP requests using the <emphasis>KDMQ</emphasis> request method, that is private 
+	to Kamailio.
+	</para>
+<example>
+                <title>Example of a KDMQ message</title>
+		<para>
+		This message is for basic DMQ bus handling. Other messages are produced
+		by other modules, like the <emphasis>htable</emphasis> module.
+		</para>
+                <programlisting format="linespecific">
+
+
+KDMQ sip:[email protected]:5090 SIP/2.0
+Via: SIP/2.0/UDP 192.168.40.15;branch=z9hG4bK55e5.423d95110000
+To: &lt;sip:[email protected]:5090&gt;
+From: &lt;sip:[email protected]:5060&gt;;tag=2cdb7a33a7f21abb98fd3a44968e3ffd-5b01
+CSeq: 10 KDMQ
+Call-ID: [email protected]
+Content-Length: 116
+User-Agent: kamailio (4.3.0 (x86_64/linneaus))
+Max-Forwards: 1
+Content-Type: text/plain
+
+sip:192.168.40.16:5060;status=active
+sip:192.168.40.15:5060;status=disabled
+sip:192.168.40.17:5060;status=active
+
+</programlisting>
+                </example>
 	
 	</section>