diff options
author | Benny Prijono <bennylp@teluu.com> | 2005-11-13 19:40:44 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2005-11-13 19:40:44 +0000 |
commit | a08b589d09d5197f9a76d549a189e4686bd2ca8c (patch) | |
tree | 549904e7680dfab96b3ce579b1843c5d58107100 /pjsip/include/pjsip-simple/messaging.h | |
parent | 8df70c6d5fef443506618bf31b686d53fef3f259 (diff) |
Applying license to pjproject
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@49 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjsip/include/pjsip-simple/messaging.h')
-rw-r--r-- | pjsip/include/pjsip-simple/messaging.h | 528 |
1 files changed, 275 insertions, 253 deletions
diff --git a/pjsip/include/pjsip-simple/messaging.h b/pjsip/include/pjsip-simple/messaging.h index ef7484bf..22ef4670 100644 --- a/pjsip/include/pjsip-simple/messaging.h +++ b/pjsip/include/pjsip-simple/messaging.h @@ -1,253 +1,275 @@ -/* $Id$ - * - */ -#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$
+ *
+ */
+/*
+ * PJSIP - SIP Stack
+ * (C)2003-2005 Benny Prijono <bennylp@bulukucing.org>
+ *
+ * Author:
+ * Benny Prijono <bennylp@bulukucing.org>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library 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
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; 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
|