pjsip/include/pjsip-simple/messaging.h

/* $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