1 files changed, 268 insertions, 268 deletions
diff --git a/pjsip/include/pjsip-simple/messaging.h b/pjsip/include/pjsip-simple/messaging.h
index 25bf5dd5..742d739c 100644
--- a/pjsip/include/pjsip-simple/messaging.h
+++ b/pjsip/include/pjsip-simple/messaging.h
@@ -1,268 +1,268 @@
-/* $Id$ */
-/* 
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
- */
-#ifndef __PJSIP_SIMPLE_MESSAGING_H__
-#define __PJSIP_SIMPLE_MESSAGING_H__
-
-/**
- * @file messaging.h
- * @brief Instant Messaging Extension (RFC 3428)
- */
-
-#include <pjsip/sip_msg.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_MESSAGING SIP Instant Messaging (RFC 3428) Module
- * @ingroup PJSIP_SIMPLE
- * @{
- *
- * This module provides the implementation of SIP Extension for Instant
- * Messaging (RFC 3428). It extends PJSIP by supporting MESSAGE method.
- *
- * The RFC 3428 doesn't provide any means of dialog for the purpose of sending/
- * receiving instant messaging. IM with SIP is basicly sessionless, which means
- * that there is absolutely no correlation between IM messages sent or received
- * by a host. Any correlation between IM messages is only perceivable by
- * user, phsychologically.
- *
- * However, the RFC doesn't prohibit sending IM within a dialog (presumably
- * using the same Call-ID and CSeq namespace), although it prohibits creating
- * a dialog specificly for creating IM session.
- *
- * The implementation here is modeled to support both ways of sending IM msgs,
- * i.e. sending IM message individually and sending IM message within a dialog.
- * Although IM message can be associated with a dialog, this implementation of
- * IM module is completely independent of the User Agent library in PJSIP. Yes,
- * that's what is called modularity, and it demonstrates the clearness 
- * of PJSIP design (the last sentence is of course marketing crap :)).
- *
- * To send an IM message as part of dialog, application would first create the
- * message using #pjsip_messaging_create_msg, using dialog's Call-ID, CSeq,
- * From, and To header, then send the message using #pjsip_dlg_send_msg instead
- * of #pjsip_messaging_send_msg. 
- *
- * To send IM messages individually, application has two options. The first is
- * to create the request with #pjsip_messaging_create_msg then send it with
- * #pjsip_messaging_send_msg. But this way, application has to pre-construct
- * From and To header first, which is not too convenient.
- *
- * The second option (to send IM messages not associated with a dialog) is to
- * first create an 'IM session'. An 'IM session' here is not a SIP dialog, as
- * it doesn't have Contact header etc. An 'IM session' here is just a local
- * state to cache most of IM headers, for convenience and optimization. Appl 
- * creates an IM session with #pjsip_messaging_create_session, and destroy
- * the session with #pjsip_messaging_destroy_session. To create an outgoing
- * IM message, application would call #pjsip_messaging_session_create_msg,
- * and to send the message it would use #pjsip_messaging_send_msg.
- *
- * Message authorization is handled by application, as usual, by inserting a 
- * proper WWW-Authenticate or Proxy-Authenticate header before sending the 
- * message.
- *
- * And the last bit, to handle incoing IM messages.
- *
- * To handle incoming IM messages, application would register a global callback
- * to be called when incoming messages arrive, by registering with function
- * #pjsip_messaging_set_incoming_callback. This will be the global callback
- * for all incoming IM messages. Although the message was sent as part of
- * a dialog, it would still come here. And as long as the request has proper
- * identification (Call-ID, From/To tag), the dialog will be aware of the
- * request and update it's state (remote CSeq) accordingly.
- */
-
-
-
-/**
- * Typedef for callback to be called when outgoing message has been sent
- * and a final response has been received.
- */
-typedef void (*pjsip_messaging_cb)(void *token, int status_code);
-
-/**
- * Typedef for callback to receive incoming message.
- *
- * @param rdata	    Incoming message data.
- *
- * @return	    The status code to be returned back to original sender.
- *		    Application must return a final status code upon returning
- *		    from this function, or otherwise the stack will respond
- *		    with error.
- */
-typedef int (*pjsip_on_new_msg_cb)(pjsip_rx_data *rdata);
-
-/**
- * Opaque data type for instant messaging session.
- */
-typedef struct pjsip_messaging_session pjsip_messaging_session;
-
-/**
- * Get the messaging module.
- *
- * @return SIP module.
- */
-PJ_DECL(pjsip_module*) pjsip_messaging_get_module();
-
-/**
- * Set the global callback to be called when incoming message is received.
- *
- * @param cb	    The callback to be called when incoming message is received.
- *
- * @return	    The previous callback.
- */
-PJ_DECL(pjsip_on_new_msg_cb) 
-pjsip_messaging_set_incoming_callback(pjsip_on_new_msg_cb cb);
-
-
-/**
- * Create an instant message transmit data buffer using the specified arguments.
- * The returned transmit data buffers will have it's reference counter set
- * to 1, and when application send the buffer, the send function will decrement
- * the reference counter. When the reference counter reach zero, the buffer
- * will be deleted. As long as the function does not increment the buffer's 
- * reference counter between creating and sending the request,  the buffer 
- * will always be deleted and no memory leak will occur.
- *
- * @param endpt	    Endpoint instance.
- * @param target    Target URL.
- * @param from	    The "From" header, which content will be copied to request.
- *		    If the "From" header doesn't have a tag parameter, the
- *		    function will generate one.
- * @param to	    The "To" header, which content will be copied to request.
- * @param call_id   Optionally specify Call-ID, or put NULL to make this
- *		    function generate a unique Call-ID automatically.
- * @param cseq	    Optionally specify CSeq, or put -1 to make this function
- *		    generate a random CSeq.
- * @param text	    Optionally specify "text/plain" message body, or put NULL 
- *		    if application wants to put body other than "text/plain"
- *		    manually.
- *
- * @return	    SIP transmit data buffer, which reference count has been
- *		    set to 1.
- */
-PJ_DECL(pjsip_tx_data*) 
-pjsip_messaging_create_msg_from_hdr(pjsip_endpoint *endpt, 
-				    const pjsip_uri *target,
-				    const pjsip_from_hdr *from,
-				    const pjsip_to_hdr *to, 
-				    const pjsip_cid_hdr *call_id,
-				    int cseq, 
-				    const pj_str_t *text);
-
-/**
- * Create instant message, by specifying URL string for both From and To header.
- *
- * @param endpt	    Endpoint instance.
- * @param target    Target URL.
- * @param from	    URL of the sender.
- * @param to	    URL of the recipient.
- * @param call_id   Optionally specify Call-ID, or put NULL to make this
- *		    function generate a unique Call-ID automatically.
- * @param cseq	    Optionally specify CSeq, or put -1 to make this function
- *		    generate a random CSeq.
- * @param text	    Optionally specify "text/plain" message body, or put NULL 
- *		    if application wants to put body other than "text/plain"
- *		    manually.
- *
- * @return	    SIP transmit data buffer, which reference count has been
- *		    set to 1.
- */
-PJ_DECL(pjsip_tx_data*) pjsip_messaging_create_msg( pjsip_endpoint *endpt, 
-						    const pj_str_t *target,
-						    const pj_str_t *from,
-						    const pj_str_t *to, 
-						    const pj_str_t *call_id,
-						    int cseq, 
-						    const pj_str_t *text);
-
-/**
- * Send the instant message transmit buffer and attach a callback to be called
- * when the request has received a final response. This function will decrement
- * the transmit buffer's reference counter, and when the reference counter
- * reach zero, the buffer will be deleted. As long as the function does not
- * increment the buffer's reference counter between creating the request and
- * calling this function, the buffer will always be deleted regardless whether
- * the sending was failed or succeeded.
- *
- * @param endpt	    Endpoint instance.
- * @param tdata	    Transmit data buffer.
- * @param token	    Token to be associated with the SIP transaction which sends
- *		    this request.
- * @param cb	    The callback to be called when the SIP request has received
- *		    a final response from destination.
- *
- * @return	    Zero if the transaction was started successfully. Note that
- *		    this doesn't mean the request has been received successfully
- *		    by remote recipient.
- */
-PJ_DECL(pj_status_t) pjsip_messaging_send_msg( pjsip_endpoint *endpt, 
-					       pjsip_tx_data *tdata, 
-					       void *token, 
-					       pjsip_messaging_cb cb );
-
-/**
- * Create an instant messaging session, which can conveniently be used to send
- * multiple instant messages to the same recipient.
- *
- * @param endpt	    Endpoint instance.
- * @param from	    URI of sender. The function will add a unique tag parameter
- *		    to this URI in the From header.
- * @param to	    URI of recipient.
- *
- * @return	    Messaging session.
- */
-PJ_DECL(pjsip_messaging_session*) 
-pjsip_messaging_create_session( pjsip_endpoint *endpt, 
-			        const pj_str_t *from,
-			        const pj_str_t *to );
-
-/**
- * Create an instant message using instant messaging session, and optionally
- * attach a text message.
- *
- * @param ses	    The instant messaging session.
- * @param text	    Optional "text/plain" message to be attached as the
- *		    message body. If this parameter is NULL, then no message
- *		    body will be created, and application can attach any
- *		    type of message body before the request is sent.
- *
- * @return	    SIP transmit data buffer, which reference counter has been
- *		    set to 1.
- */
-PJ_DECL(pjsip_tx_data*)
-pjsip_messaging_session_create_msg( pjsip_messaging_session *ses, 
-				    const pj_str_t *text );
-
-/**
- * Destroy an instant messaging session.
- *
- * @param ses	    The instant messaging session.
- *
- * @return	    Zero on successfull.
- */
-PJ_DECL(pj_status_t)
-pjsip_messaging_destroy_session( pjsip_messaging_session *ses );
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif
+/* $Id$ */
+/* 
+ * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
+ */
+#ifndef __PJSIP_SIMPLE_MESSAGING_H__
+#define __PJSIP_SIMPLE_MESSAGING_H__
+
+/**
+ * @file messaging.h
+ * @brief Instant Messaging Extension (RFC 3428)
+ */
+
+#include <pjsip/sip_msg.h>
+
+PJ_BEGIN_DECL
+
+/**
+ * @defgroup PJSIP_MESSAGING SIP Instant Messaging (RFC 3428) Module
+ * @ingroup PJSIP_SIMPLE
+ * @{
+ *
+ * This module provides the implementation of SIP Extension for Instant
+ * Messaging (RFC 3428). It extends PJSIP by supporting MESSAGE method.
+ *
+ * The RFC 3428 doesn't provide any means of dialog for the purpose of sending/
+ * receiving instant messaging. IM with SIP is basicly sessionless, which means
+ * that there is absolutely no correlation between IM messages sent or received
+ * by a host. Any correlation between IM messages is only perceivable by
+ * user, phsychologically.
+ *
+ * However, the RFC doesn't prohibit sending IM within a dialog (presumably
+ * using the same Call-ID and CSeq namespace), although it prohibits creating
+ * a dialog specificly for creating IM session.
+ *
+ * The implementation here is modeled to support both ways of sending IM msgs,
+ * i.e. sending IM message individually and sending IM message within a dialog.
+ * Although IM message can be associated with a dialog, this implementation of
+ * IM module is completely independent of the User Agent library in PJSIP. Yes,
+ * that's what is called modularity, and it demonstrates the clearness 
+ * of PJSIP design (the last sentence is of course marketing crap :)).
+ *
+ * To send an IM message as part of dialog, application would first create the
+ * message using #pjsip_messaging_create_msg, using dialog's Call-ID, CSeq,
+ * From, and To header, then send the message using #pjsip_dlg_send_msg instead
+ * of #pjsip_messaging_send_msg. 
+ *
+ * To send IM messages individually, application has two options. The first is
+ * to create the request with #pjsip_messaging_create_msg then send it with
+ * #pjsip_messaging_send_msg. But this way, application has to pre-construct
+ * From and To header first, which is not too convenient.
+ *
+ * The second option (to send IM messages not associated with a dialog) is to
+ * first create an 'IM session'. An 'IM session' here is not a SIP dialog, as
+ * it doesn't have Contact header etc. An 'IM session' here is just a local
+ * state to cache most of IM headers, for convenience and optimization. Appl 
+ * creates an IM session with #pjsip_messaging_create_session, and destroy
+ * the session with #pjsip_messaging_destroy_session. To create an outgoing
+ * IM message, application would call #pjsip_messaging_session_create_msg,
+ * and to send the message it would use #pjsip_messaging_send_msg.
+ *
+ * Message authorization is handled by application, as usual, by inserting a 
+ * proper WWW-Authenticate or Proxy-Authenticate header before sending the 
+ * message.
+ *
+ * And the last bit, to handle incoing IM messages.
+ *
+ * To handle incoming IM messages, application would register a global callback
+ * to be called when incoming messages arrive, by registering with function
+ * #pjsip_messaging_set_incoming_callback. This will be the global callback
+ * for all incoming IM messages. Although the message was sent as part of
+ * a dialog, it would still come here. And as long as the request has proper
+ * identification (Call-ID, From/To tag), the dialog will be aware of the
+ * request and update it's state (remote CSeq) accordingly.
+ */
+
+
+
+/**
+ * Typedef for callback to be called when outgoing message has been sent
+ * and a final response has been received.
+ */
+typedef void (*pjsip_messaging_cb)(void *token, int status_code);
+
+/**
+ * Typedef for callback to receive incoming message.
+ *
+ * @param rdata	    Incoming message data.
+ *
+ * @return	    The status code to be returned back to original sender.
+ *		    Application must return a final status code upon returning
+ *		    from this function, or otherwise the stack will respond
+ *		    with error.
+ */
+typedef int (*pjsip_on_new_msg_cb)(pjsip_rx_data *rdata);
+
+/**
+ * Opaque data type for instant messaging session.
+ */
+typedef struct pjsip_messaging_session pjsip_messaging_session;
+
+/**
+ * Get the messaging module.
+ *
+ * @return SIP module.
+ */
+PJ_DECL(pjsip_module*) pjsip_messaging_get_module();
+
+/**
+ * Set the global callback to be called when incoming message is received.
+ *
+ * @param cb	    The callback to be called when incoming message is received.
+ *
+ * @return	    The previous callback.
+ */
+PJ_DECL(pjsip_on_new_msg_cb) 
+pjsip_messaging_set_incoming_callback(pjsip_on_new_msg_cb cb);
+
+
+/**
+ * Create an instant message transmit data buffer using the specified arguments.
+ * The returned transmit data buffers will have it's reference counter set
+ * to 1, and when application send the buffer, the send function will decrement
+ * the reference counter. When the reference counter reach zero, the buffer
+ * will be deleted. As long as the function does not increment the buffer's 
+ * reference counter between creating and sending the request,  the buffer 
+ * will always be deleted and no memory leak will occur.
+ *
+ * @param endpt	    Endpoint instance.
+ * @param target    Target URL.
+ * @param from	    The "From" header, which content will be copied to request.
+ *		    If the "From" header doesn't have a tag parameter, the
+ *		    function will generate one.
+ * @param to	    The "To" header, which content will be copied to request.
+ * @param call_id   Optionally specify Call-ID, or put NULL to make this
+ *		    function generate a unique Call-ID automatically.
+ * @param cseq	    Optionally specify CSeq, or put -1 to make this function
+ *		    generate a random CSeq.
+ * @param text	    Optionally specify "text/plain" message body, or put NULL 
+ *		    if application wants to put body other than "text/plain"
+ *		    manually.
+ *
+ * @return	    SIP transmit data buffer, which reference count has been
+ *		    set to 1.
+ */
+PJ_DECL(pjsip_tx_data*) 
+pjsip_messaging_create_msg_from_hdr(pjsip_endpoint *endpt, 
+				    const pjsip_uri *target,
+				    const pjsip_from_hdr *from,
+				    const pjsip_to_hdr *to, 
+				    const pjsip_cid_hdr *call_id,
+				    int cseq, 
+				    const pj_str_t *text);
+
+/**
+ * Create instant message, by specifying URL string for both From and To header.
+ *
+ * @param endpt	    Endpoint instance.
+ * @param target    Target URL.
+ * @param from	    URL of the sender.
+ * @param to	    URL of the recipient.
+ * @param call_id   Optionally specify Call-ID, or put NULL to make this
+ *		    function generate a unique Call-ID automatically.
+ * @param cseq	    Optionally specify CSeq, or put -1 to make this function
+ *		    generate a random CSeq.
+ * @param text	    Optionally specify "text/plain" message body, or put NULL 
+ *		    if application wants to put body other than "text/plain"
+ *		    manually.
+ *
+ * @return	    SIP transmit data buffer, which reference count has been
+ *		    set to 1.
+ */
+PJ_DECL(pjsip_tx_data*) pjsip_messaging_create_msg( pjsip_endpoint *endpt, 
+						    const pj_str_t *target,
+						    const pj_str_t *from,
+						    const pj_str_t *to, 
+						    const pj_str_t *call_id,
+						    int cseq, 
+						    const pj_str_t *text);
+
+/**
+ * Send the instant message transmit buffer and attach a callback to be called
+ * when the request has received a final response. This function will decrement
+ * the transmit buffer's reference counter, and when the reference counter
+ * reach zero, the buffer will be deleted. As long as the function does not
+ * increment the buffer's reference counter between creating the request and
+ * calling this function, the buffer will always be deleted regardless whether
+ * the sending was failed or succeeded.
+ *
+ * @param endpt	    Endpoint instance.
+ * @param tdata	    Transmit data buffer.
+ * @param token	    Token to be associated with the SIP transaction which sends
+ *		    this request.
+ * @param cb	    The callback to be called when the SIP request has received
+ *		    a final response from destination.
+ *
+ * @return	    Zero if the transaction was started successfully. Note that
+ *		    this doesn't mean the request has been received successfully
+ *		    by remote recipient.
+ */
+PJ_DECL(pj_status_t) pjsip_messaging_send_msg( pjsip_endpoint *endpt, 
+					       pjsip_tx_data *tdata, 
+					       void *token, 
+					       pjsip_messaging_cb cb );
+
+/**
+ * Create an instant messaging session, which can conveniently be used to send
+ * multiple instant messages to the same recipient.
+ *
+ * @param endpt	    Endpoint instance.
+ * @param from	    URI of sender. The function will add a unique tag parameter
+ *		    to this URI in the From header.
+ * @param to	    URI of recipient.
+ *
+ * @return	    Messaging session.
+ */
+PJ_DECL(pjsip_messaging_session*) 
+pjsip_messaging_create_session( pjsip_endpoint *endpt, 
+			        const pj_str_t *from,
+			        const pj_str_t *to );
+
+/**
+ * Create an instant message using instant messaging session, and optionally
+ * attach a text message.
+ *
+ * @param ses	    The instant messaging session.
+ * @param text	    Optional "text/plain" message to be attached as the
+ *		    message body. If this parameter is NULL, then no message
+ *		    body will be created, and application can attach any
+ *		    type of message body before the request is sent.
+ *
+ * @return	    SIP transmit data buffer, which reference counter has been
+ *		    set to 1.
+ */
+PJ_DECL(pjsip_tx_data*)
+pjsip_messaging_session_create_msg( pjsip_messaging_session *ses, 
+				    const pj_str_t *text );
+
+/**
+ * Destroy an instant messaging session.
+ *
+ * @param ses	    The instant messaging session.
+ *
+ * @return	    Zero on successfull.
+ */
+PJ_DECL(pj_status_t)
+pjsip_messaging_destroy_session( pjsip_messaging_session *ses );
+
+/**
+ * @}
+ */
+
+PJ_END_DECL
+
+#endif