sdp_neg.h

一个开源SIP协议栈

/* $Id: sdp_neg.h 1071 2007-03-15 21:56:33Z bennylp $ */
/* 
 * Copyright (C) 2003-2007 Benny Prijono <[e-mail]>
 *
 * 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 __PJMEDIA_SDP_NEG_H__
#define __PJMEDIA_SDP_NEG_H__


/**
 * @file sdp_neg.h
 * @brief SDP negotiator header file.
 */
/**
 * @defgroup PJMEDIA_SDP_NEG SDP Negotiation State Machine (Offer/Answer Model, RFC 3264)
 * @ingroup PJMEDIA_SESSION
 * @brief SDP Negotiation State Machine (Offer/Answer Model, RFC 3264)
 * @{
 *
 * The header file <b><pjmedia/sdp_neg.h></b> contains the declaration
 * of SDP offer and answer negotiator. SDP offer and answer model is described
 * in RFC 3264 <b>"An Offer/Answer Model with Session Description Protocol 
 * (SDP)"</b>.
 *
 * The SDP negotiator is represented with opaque type \a pjmedia_sdp_neg.
 * This structure contains negotiation state and several SDP session 
 * descriptors currently being used in the negotiation.
 *
 *
 * \section sdpneg_state_dia SDP Negotiator State Diagram
 *
 * The following diagram describes the state transition diagram of the
 * SDP negotiator.
 * 
 * <pre>
 *                                              
 *                                              modify_local_offer()
 *     create_w_local_offer()  +-------------+  send_local_offer()
 *     ----------------------->| LOCAL_OFFER |<-----------------------
 *    |                        +-------------+                        |
 *    |                               |                               |
 *    |           set_remote_answer() |                               |
 *    |                               V                               |
 * +--+---+                     +-----------+     negotiate()     +------+
 * | NULL |                     | WAIT_NEGO |-------------------->| DONE |
 * +------+                     +-----------+                     +------+
 *    |                               A                               |
 *    |            set_local_answer() |                               |
 *    |                               |                               |
 *    |                        +--------------+   set_remote_offer()  |
 *     ----------------------->| REMOTE_OFFER |<----------------------
 *     create_w_remote_offer() +--------------+
 *
 * </pre>
 *
 *
 *
 * \section sdpneg_offer_answer SDP Offer/Answer Model with Negotiator
 *
 * \subsection sdpneg_create_offer Creating Initial Offer
 *
 * Application creates an offer by manualy building the SDP session descriptor
 * (pjmedia_sdp_session), or request PJMEDIA endpoint (pjmedia_endpt) to 
 * create SDP session descriptor based on capabilities that present in the
 * endpoint by calling #pjmedia_endpt_create_sdp().
 *
 * Application then creates SDP negotiator instance by calling
 * #pjmedia_sdp_neg_create_w_local_offer(), passing the SDP offer in the
 * function arguments. The SDP negotiator keeps a copy of current local offer,
 * and update its state to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER.
 *
 * Application can then send the initial SDP offer that it creates to
 * remote peer using signaling protocol such as SIP.
 *
 *
 * \subsection sdpneg_subseq_offer Generating Subsequent Offer
 *
 * The negotiator can only create subsequent offer after it has finished
 * the negotiation process of previous offer/answer session (i.e. the
 * negotiator state is PJMEDIA_SDP_NEG_STATE_DONE).
 *
 * If any previous negotiation process was successfull (i.e. the return 
 * value of #pjmedia_sdp_neg_negotiate() was PJ_SUCCESS), the negotiator
 * keeps both active local and active remote SDP.
 *
 * If application does not want send modified offer, it can just send
 * the active local SDP as the offer. In this case, application calls
 * #pjmedia_sdp_neg_send_local_offer() to get the active local SDP.
 * 
 * If application wants to modify it's local offer, it MUST inform 
 * the negotiator about the modified SDP by calling 
 * #pjmedia_sdp_neg_modify_local_offer().
 *
 * In both cases, the negotiator will internally create a copy of the offer,
 * and move it's state to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, where it
 * waits until application passes the remote answer.
 *
 *
 * \subsection sdpneg_receive_offer Receiving Initial Offer
 *
 * Application receives an offer in the incoming request from remote to
 * establish multimedia session, such as incoming INVITE message with SDP
 * body. 
 *
 * Initially, when the initial offer is received, application creates the 
 * SDP negotiator by calling #pjmedia_sdp_neg_create_w_remote_offer(),
 * specifying the remote SDP offer in one of the argument. 
 *
 * At this stage, application may or may not ready to create an answer.
 * For example, a SIP B2BUA needs to make outgoing call and receive SDP
 * from the outgoing call leg in order to create a SDP answer to the
 * incoming call leg.
 *
 * If application is not ready to create an answer, it passes NULL as
 * the local SDP when it calls #pjmedia_sdp_neg_create_w_remote_offer().
 *
 * The section @ref sdpneg_create_answer describes the case when 
 * application is ready to create a SDP answer.
 *
 *
 * \subsection sdpneg_subseq_offer Receiving Subsequent Offer
 *
 * Application passes subsequent SDP offer received from remote by
 * calling #pjmedia_sdp_neg_set_remote_offer().
 *
 * The negotiator can only receive subsequent offer after it has finished
 * the negotiation process of previous offer/answer session (i.e. the
 * negotiator state is PJMEDIA_SDP_NEG_STATE_DONE).
 *
 *
 * \subsection sdpneg_recv_answer Receiving SDP Answer
 *
 * When application receives SDP answer from remote, it informs the
 * negotiator by calling #pjmedia_sdp_neg_set_remote_answer(). The
 * negotiator validates the answer (#pjmedia_sdp_validate()), and if
 * succeeds, it moves it's state to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO.
 *
 * Application then instruct the negotiator to negotiate the remote
 * answer by calling #pjmedia_sdp_neg_negotiate(). The purpose of
 * this negotiation is to verify remote answer, and update the initial
 * offer according to the answer. For example, the initial offer may
 * specify that a stream is \a sendrecv, while the answer specifies
 * that remote stream is \a inactive. In this case, the negotiator
 * will update the stream in the local active media as \a inactive
 * too.
 *
 * If #pjmedia_sdp_neg_negotiate() returns PJ_SUCCESS, the negotiator will
 * keep the updated local answer and remote answer internally. These two 
 * SDPs are called active local SDP and active remote SDP, as it describes 
 * currently active session.
 *
 * Application can retrieve the active local SDP by calling
 * #pjmedia_sdp_neg_get_active_local(), and active remote SDP by calling
 * #pjmedia_sdp_neg_get_active_remote().
 *
 * If #pjmedia_sdp_neg_negotiate() returns failure (i.e. not PJ_SUCCESS),
 * it WILL NOT update its active local and active remote SDP.
 *
 * Regardless of the return status of the #pjmedia_sdp_neg_negotiate(), 
 * the negotiator state will move to PJMEDIA_SDP_NEG_STATE_DONE.
 * 
 *
 * \subsection sdpneg_create_answer Generating SDP Answer
 *
 * After remote offer has been set in the negotiator, application can 
 * request the SDP negotiator to generate appropriate answer based on local 
 * capability.
 *
 * To do this, first the application MUST have an SDP describing its local
 * capabilities. This SDP can be built manually, or application can generate
 * SDP to describe local media endpoint capability by calling 
 * #pjmedia_endpt_create_sdp(). When the application is a SIP B2BUA, 
 * application can treat the SDP received from the outgoing call leg as if
 * it was it's local capability.
 * 
 * The local SDP session descriptor DOES NOT have to match the SDP offer.
 * For example, it can have more or less media lines than the offer, or
 * their order may be different than the offer. The negotiator is capable
 * to match and reorder local SDP according to remote offer, and create
 * an answer that is suitable for the offer.
 *
 * After local SDP capability has been acquired, application can create
 * a SDP answer.
 *
 * If application does not already have the negotiator instance, it creates
 * one by calling #pjmedia_sdp_neg_create_w_remote_offer(), specifying 
 * both remote SDP offer and local SDP as the arguments. The SDP negotiator
 * validates both remote and local SDP by calling #pjmedia_sdp_validate(),
 * and if both SDPs are valid, the negotiator state will move to
 * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO where it is ready to negotiate the
 * offer and answer.
 *
 * If application already has the negotiator instance, it sets the local
 * SDP in the negotiator by calling #pjmedia_sdp_neg_set_local_answer().
 * The SDP negotiator then validates local SDP (#pjmedia_sdp_validate() ),
 * and if it is  valid, the negotiator state will move to
 * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO where it is ready to negotiate the
 * offer and answer.
 *
 * After the SDP negotiator state has moved to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO,
 * application calls #pjmedia_sdp_neg_negotiate() to instruct the SDP
 * negotiator to negotiate both offer and answer. This function returns
 * PJ_SUCCESS if an answer can be generated AND at least one media stream
 * is active in the session.
 *
 * If #pjmedia_sdp_neg_negotiate() returns PJ_SUCCESS, the negotiator will
 * keep the remote offer and local answer internally. These two SDPs are
 * called active local SDP and active remote SDP, as it describes currently
 * active session.
 *
 * Application can retrieve the active local SDP by calling
 * #pjmedia_sdp_neg_get_active_local(), and send this SDP to remote as the
 * SDP answer.
 *
 * If #pjmedia_sdp_neg_negotiate() returns failure (i.e. not PJ_SUCCESS),
 * it WILL NOT update its active local and active remote SDP.
 *
 * Regardless of the return status of the #pjmedia_sdp_neg_negotiate(), 
 * the negotiator state will move to PJMEDIA_SDP_NEG_STATE_DONE.
 *
 *
 */

#include <pjmedia/sdp.h>

PJ_BEGIN_DECL

/**
 * This enumeration describes SDP negotiation state. 
 */
enum pjmedia_sdp_neg_state
{
    /** 
     * This is the state of SDP negoator before it is initialized. 
     */
    PJMEDIA_SDP_NEG_STATE_NULL,

    /** 
     * This state occurs when SDP negotiator has sent our offer to remote and
     * it is waiting for answer. 
     */
    PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER,

    /** 
     * This state occurs when SDP negotiator has received offer from remote
     * and currently waiting for local answer.
     */
    PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER,

    /**
     * This state occurs when an offer (either local or remote) has been 
     * provided with answer. The SDP negotiator is ready to negotiate both
     * session descriptors. Application can call #pjmedia_sdp_neg_negotiate()
     * immediately to begin negotiation process.
     */
    PJMEDIA_SDP_NEG_STATE_WAIT_NEGO,

    /**
     * This state occurs when SDP negotiation has completed, either 
     * successfully or not.
     */
    PJMEDIA_SDP_NEG_STATE_DONE
};


/**
 * @see pjmedia_sdp_neg_state
 */
typedef enum pjmedia_sdp_neg_state pjmedia_sdp_neg_state;


/**
 * Opaque declaration of SDP negotiator.
 */
typedef struct pjmedia_sdp_neg pjmedia_sdp_neg;


/**
 * Get the state string description of the specified state.
 *
 * @param state		Negotiator state.
 *
 * @return		String description of the state.
 */
PJ_DECL(const char*) pjmedia_sdp_neg_state_str(pjmedia_sdp_neg_state state);


/**
 * Create the SDP negotiator with local offer. The SDP negotiator then
 * will move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER state, where it waits
 * until it receives answer from remote. When SDP answer from remote is
 * received, application must call #pjmedia_sdp_neg_set_remote_answer().
 *
 * After calling this function, application should send the local SDP offer
 * to remote party using signaling protocol such as SIP and wait for SDP 
 * answer.
 *
 * @param pool		Pool to allocate memory. The pool's lifetime needs
 *			to be valid for the duration of the negotiator.
 * @param local		The initial local capability.
 * @param p_neg		Pointer to receive the negotiator instance.
 *
 * @return		PJ_SUCCESS on success, or the appropriate error
 *			code.
 */
PJ_DECL(pj_status_t) 
pjmedia_sdp_neg_create_w_local_offer( pj_pool_t *pool,