diff options
Diffstat (limited to 'pjsip/include/pjsip-simple/messaging.h')
-rw-r--r-- | pjsip/include/pjsip-simple/messaging.h | 268 |
1 files changed, 0 insertions, 268 deletions
diff --git a/pjsip/include/pjsip-simple/messaging.h b/pjsip/include/pjsip-simple/messaging.h deleted file mode 100644 index 742d739c..00000000 --- a/pjsip/include/pjsip-simple/messaging.h +++ /dev/null @@ -1,268 +0,0 @@ -/* $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 |