sdp_neg.h

一个开源的sip源代码

				      const pjmedia_sdp_session *local,
				      pjmedia_sdp_neg **p_neg);

/**
 * Initialize the SDP negotiator with remote offer, and optionally
 * specify the initial local capability, if known. Application normally 
 * calls this function when it receives initial offer from remote. 
 *
 * If local media capability is specified, this capability will be set as
 * initial local capability of the negotiator, and after this function is
 * called, the SDP negotiator state will move to state
 * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and the negotiation function can be 
 * called. 
 *
 * If local SDP is not specified, the negotiator will not have initial local
 * capability, and after this function is called the negotiator state will 
 * move to PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER state. Application MUST supply
 * local answer later with #pjmedia_sdp_neg_set_local_answer(), before
 * calling the negotiation function.
 *
 * @param pool		Pool to allocate memory. The pool's lifetime needs
 *			to be valid for the duration of the negotiator.
 * @param initial	Optional initial local capability.
 * @param remote	The remote offer.
 * @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_remote_offer(pj_pool_t *pool,
				      const pjmedia_sdp_session *initial,
				      const pjmedia_sdp_session *remote,
				      pjmedia_sdp_neg **p_neg);

/**
 * This specifies the behavior of the SDP negotiator when responding to an
 * offer, whether it should rather use the codec preference as set by
 * remote, or should it rather use the codec preference as specified by
 * local endpoint.
 *
 * For example, suppose incoming call has codec order "8 0 3", while 
 * local codec order is "3 0 8". If remote codec order is preferable,
 * the selected codec will be 8, while if local codec order is preferable,
 * the selected codec will be 3.
 *
 * By default, the value in PJMEDIA_SDP_NEG_PREFER_REMOTE_CODEC_ORDER will
 * be used.
 *
 * @param neg		The SDP negotiator instance.
 * @param prefer_remote	If non-zero, the negotiator will use the codec
 *			order as specified in remote offer. If zero, it
 *			will prefer to use the local codec order.
 */
PJ_DECL(pj_status_t)
pjmedia_sdp_neg_set_prefer_remote_codec_order(pjmedia_sdp_neg *neg,
					      pj_bool_t prefer_remote);


/**
 * Get SDP negotiator state.
 *
 * @param neg		The SDP negotiator instance.
 *
 * @return		The negotiator state.
 */
PJ_DECL(pjmedia_sdp_neg_state)
pjmedia_sdp_neg_get_state( pjmedia_sdp_neg *neg );

/**
 * Get the currently active local SDP. Application can only call this
 * function after negotiation has been done, or otherwise there won't be
 * active SDPs. Calling this function will not change the state of the 
 * negotiator.
 *
 * @param neg		The SDP negotiator instance.
 * @param local		Pointer to receive the local active SDP.
 *
 * @return		PJ_SUCCESS if local active SDP is present.
 */
PJ_DECL(pj_status_t) 
pjmedia_sdp_neg_get_active_local( pjmedia_sdp_neg *neg,
				  const pjmedia_sdp_session **local);

/**
 * Get the currently active remote SDP. Application can only call this
 * function after negotiation has been done, or otherwise there won't be
 * active SDPs. Calling this function will not change the state of the 
 * negotiator.
 *
 * @param neg		The SDP negotiator instance.
 * @param remote	Pointer to receive the remote active SDP.
 *
 * @return		PJ_SUCCESS if remote active SDP is present.
 */
PJ_DECL(pj_status_t) 
pjmedia_sdp_neg_get_active_remote( pjmedia_sdp_neg *neg,
				   const pjmedia_sdp_session **remote);


/**
 * Determine whether remote sent answer (as opposed to offer) on the
 * last negotiation. This function can only be called in state
 * PJMEDIA_SDP_NEG_STATE_DONE.
 *
 * @param neg		The SDP negotiator instance.
 *
 * @return		Non-zero if it was remote who sent answer,
 *			otherwise zero if it was local who supplied
 *			answer.
 */
PJ_DECL(pj_bool_t)
pjmedia_sdp_neg_was_answer_remote(pjmedia_sdp_neg *neg);


/**
 * Get the current remote SDP offer or answer. Application can only 
 * call this function in state PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER or
 * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, or otherwise there won't be remote 
 * SDP offer/answer. Calling this  function will not change the state 
 * of the negotiator.
 *
 * @param neg		The SDP negotiator instance.
 * @param remote	Pointer to receive the current remote offer or
 *			answer.
 *
 * @return		PJ_SUCCESS if the negotiator currently has
 *			remote offer or answer.
 */
PJ_DECL(pj_status_t)
pjmedia_sdp_neg_get_neg_remote( pjmedia_sdp_neg *neg,
				const pjmedia_sdp_session **remote);


/**
 * Get the current local SDP offer or answer. Application can only 
 * call this function in state PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER or
 * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, or otherwise there won't be local 
 * SDP offer/answer. Calling this function will not change the state 
 * of the negotiator.
 *
 * @param neg		The SDP negotiator instance.
 * @param local		Pointer to receive the current local offer or
 *			answer.
 *
 * @return		PJ_SUCCESS if the negotiator currently has
 *			local offer or answer.
 */
PJ_DECL(pj_status_t) 
pjmedia_sdp_neg_get_neg_local( pjmedia_sdp_neg *neg,
			       const pjmedia_sdp_session **local);

/**
 * Modify local session with a new SDP and treat this as a new offer. 
 * This function can only be called in state PJMEDIA_SDP_NEG_STATE_DONE.
 * After calling this function, application can send the SDP as offer 
 * to remote party, using signaling protocol such as SIP.
 * The negotiator state will move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER,
 * where it waits for SDP answer from remote.
 *
 * @param pool		Pool to allocate memory. The pool's lifetime needs
 *			to be valid for the duration of the negotiator.
 * @param neg		The SDP negotiator instance.
 * @param local		The new local SDP.
 *
 * @return		PJ_SUCCESS on success, or the appropriate
 *			error code.
 */
PJ_DECL(pj_status_t) 
pjmedia_sdp_neg_modify_local_offer( pj_pool_t *pool,
				    pjmedia_sdp_neg *neg,
				    const pjmedia_sdp_session *local);

/**
 * This function can only be called in PJMEDIA_SDP_NEG_STATE_DONE state.
 * Application calls this function to retrieve currently active
 * local SDP, and then send the SDP to remote as an offer. The negotiator
 * state will then move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, where it waits
 * for SDP answer from remote. 
 *
 * When SDP answer has been received from remote, application must call 
 * #pjmedia_sdp_neg_set_remote_answer().
 *
 * @param pool		Pool to allocate memory. The pool's lifetime needs
 *			to be valid for the duration of the negotiator.
 * @param neg		The SDP negotiator instance.
 * @param offer		Pointer to receive active local SDP to be
 *			offered to remote.
 *
 * @return		PJ_SUCCESS if local offer can be created.
 */
PJ_DECL(pj_status_t) 
pjmedia_sdp_neg_send_local_offer( pj_pool_t *pool,
			          pjmedia_sdp_neg *neg,
				  const pjmedia_sdp_session **offer);

/**
 * This function can only be called in PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER
 * state, i.e. after application calls #pjmedia_sdp_neg_send_local_offer()
 * function. Application calls this function when it receives SDP answer
 * from remote. After this function is called, the negotiator state will
 * move to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and application can call the
 * negotiation function #pjmedia_sdp_neg_negotiate().
 *
 * @param pool		Pool to allocate memory. The pool's lifetime needs
 *			to be valid for the duration of the negotiator.
 * @param neg		The SDP negotiator instance.
 * @param remote	The remote answer.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_sdp_neg_set_remote_answer( pj_pool_t *pool,
				   pjmedia_sdp_neg *neg,
				   const pjmedia_sdp_session *remote);



/**
 * This function can only be called in PJMEDIA_SDP_NEG_STATE_DONE state. 
 * Application calls this function when it receives SDP offer from remote.
 * After this function is called, the negotiator state will move to 
 * PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER, and application MUST call the
 * #pjmedia_sdp_neg_set_local_answer() to set local answer before it can
 * call the negotiation function.
 *
 * @param pool		Pool to allocate memory. The pool's lifetime needs
 *			to be valid for the duration of the negotiator.
 * @param neg		The SDP negotiator instance.
 * @param remote	The remote offer.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_sdp_neg_set_remote_offer( pj_pool_t *pool,
				  pjmedia_sdp_neg *neg,
				  const pjmedia_sdp_session *remote);



/**
 * This function can only be called in PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER
 * state, i.e. after application calls #pjmedia_sdp_neg_set_remote_offer()
 * function. After this function is called, the negotiator state will
 * move to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and application can call the
 * negotiation function #pjmedia_sdp_neg_negotiate().
 *
 * @param pool		Pool to allocate memory. The pool's lifetime needs
 *			to be valid for the duration of the negotiator.
 * @param neg		The SDP negotiator instance.
 * @param local		Optional local answer. If negotiator has initial
 *			local capability, application can specify NULL on
 *			this argument; in this case, the negotiator will
 *			create answer by by negotiating remote offer with
 *			initial local capability. If negotiator doesn't have
 *			initial local capability, application MUST specify
 *			local answer here.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) 
pjmedia_sdp_neg_set_local_answer( pj_pool_t *pool,
				  pjmedia_sdp_neg *neg,
				  const pjmedia_sdp_session *local);


/**
 * Call this function when the negotiator is in PJMEDIA_SDP_NEG_STATE_WAIT_NEGO
 * state to see if it was local who is answering the offer (instead of
 * remote).
 *
 * @param neg		The negotiator.
 *
 * @return		PJ_TRUE if it is local is answering an offer, PJ_FALSE
 *			if remote has answered local offer.
 */
PJ_DECL(pj_bool_t) pjmedia_sdp_neg_has_local_answer(pjmedia_sdp_neg *neg);


/**
 * Negotiate local and remote answer. Before calling this function, the
 * SDP negotiator must be in PJMEDIA_SDP_NEG_STATE_WAIT_NEGO state.
 * After calling this function, the negotiator state will move to
 * PJMEDIA_SDP_NEG_STATE_DONE regardless whether the negotiation has
 * been successfull or not.
 *
 * If the negotiation succeeds (i.e. the return value is PJ_SUCCESS),
 * the active local and remote SDP will be replaced with the new SDP
 * from the negotiation process.
 *
 * If the negotiation fails, the active local and remote SDP will not
 * change.
 *
 * @param pool		Pool to allocate memory. The pool's lifetime needs
 *			to be valid for the duration of the negotiator.
 * @param neg		The SDP negotiator instance.
 * @param allow_asym	Should be zero.
 *
 * @return		PJ_SUCCESS when there is at least one media
 *			is actuve common in both offer and answer, or 
 *			failure code when negotiation has failed.
 */
PJ_DECL(pj_status_t) pjmedia_sdp_neg_negotiate( pj_pool_t *pool,
					        pjmedia_sdp_neg *neg,
						pj_bool_t allow_asym);




PJ_END_DECL

/**
 * @}
 */


#endif	/* __PJMEDIA_SDP_NEG_H__ */