Alexandre Lision | 8af73cb | 2013-12-10 14:11:20 -0500 | [diff] [blame] | 1 | /* $Id$ */ |
| 2 | /* |
| 3 | * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) |
| 4 | * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> |
| 5 | * |
| 6 | * This program is free software; you can redistribute it and/or modify |
| 7 | * it under the terms of the GNU General Public License as published by |
| 8 | * the Free Software Foundation; either version 2 of the License, or |
| 9 | * (at your option) any later version. |
| 10 | * |
| 11 | * This program is distributed in the hope that it will be useful, |
| 12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 14 | * GNU General Public License for more details. |
| 15 | * |
| 16 | * You should have received a copy of the GNU General Public License |
| 17 | * along with this program; if not, write to the Free Software |
| 18 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 19 | */ |
| 20 | #ifndef __PJMEDIA_SDP_NEG_H__ |
| 21 | #define __PJMEDIA_SDP_NEG_H__ |
| 22 | |
| 23 | |
| 24 | /** |
| 25 | * @file sdp_neg.h |
| 26 | * @brief SDP negotiator header file. |
| 27 | */ |
| 28 | /** |
| 29 | * @defgroup PJMEDIA_SDP_NEG SDP Negotiation State Machine (Offer/Answer Model, RFC 3264) |
| 30 | * @ingroup PJMEDIA_SESSION |
| 31 | * @brief SDP Negotiation State Machine (Offer/Answer Model, RFC 3264) |
| 32 | * @{ |
| 33 | * |
| 34 | * The header file <b><pjmedia/sdp_neg.h></b> contains the declaration |
| 35 | * of SDP offer and answer negotiator. SDP offer and answer model is described |
| 36 | * in RFC 3264 <b>"An Offer/Answer Model with Session Description Protocol |
| 37 | * (SDP)"</b>. |
| 38 | * |
| 39 | * The SDP negotiator is represented with opaque type \a pjmedia_sdp_neg. |
| 40 | * This structure contains negotiation state and several SDP session |
| 41 | * descriptors currently being used in the negotiation. |
| 42 | * |
| 43 | * |
| 44 | * \section sdpneg_state_dia SDP Negotiator State Diagram |
| 45 | * |
| 46 | * The following diagram describes the state transition diagram of the |
| 47 | * SDP negotiator. |
| 48 | * |
| 49 | * <pre> |
| 50 | * |
| 51 | * modify_local_offer() |
| 52 | * create_w_local_offer() +-------------+ send_local_offer() |
| 53 | * ----------------------->| LOCAL_OFFER |<----------------------- |
| 54 | * | +-------------+______ | |
| 55 | * | | \_____________ | |
| 56 | * | set_remote_answer() | cancel_offer() \ | |
| 57 | * | V v | |
| 58 | * +--+---+ +-----------+ negotiate() +-~----+ |
| 59 | * | NULL | | WAIT_NEGO |-------------------->| DONE | |
| 60 | * +------+ +-----------+ +------+ |
| 61 | * | A ______________________^ | |
| 62 | * | set_local_answer() | / cancel_offer() | |
| 63 | * | | / | |
| 64 | * | +--------------+ set_remote_offer() | |
| 65 | * ----------------------->| REMOTE_OFFER |<---------------------- |
| 66 | * create_w_remote_offer() +--------------+ |
| 67 | * |
| 68 | * </pre> |
| 69 | * |
| 70 | * |
| 71 | * |
| 72 | * \section sdpneg_offer_answer SDP Offer/Answer Model with Negotiator |
| 73 | * |
| 74 | * \subsection sdpneg_create_offer Creating Initial Offer |
| 75 | * |
| 76 | * Application creates an offer by manualy building the SDP session descriptor |
| 77 | * (pjmedia_sdp_session), or request PJMEDIA endpoint (pjmedia_endpt) to |
| 78 | * create SDP session descriptor based on capabilities that present in the |
| 79 | * endpoint by calling #pjmedia_endpt_create_sdp(). |
| 80 | * |
| 81 | * Application then creates SDP negotiator instance by calling |
| 82 | * #pjmedia_sdp_neg_create_w_local_offer(), passing the SDP offer in the |
| 83 | * function arguments. The SDP negotiator keeps a copy of current local offer, |
| 84 | * and update its state to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER. |
| 85 | * |
| 86 | * Application can then send the initial SDP offer that it creates to |
| 87 | * remote peer using signaling protocol such as SIP. |
| 88 | * |
| 89 | * |
| 90 | * \subsection sdpneg_subseq_offer Generating Subsequent Offer |
| 91 | * |
| 92 | * The negotiator can only create subsequent offer after it has finished |
| 93 | * the negotiation process of previous offer/answer session (i.e. the |
| 94 | * negotiator state is PJMEDIA_SDP_NEG_STATE_DONE). |
| 95 | * |
| 96 | * If any previous negotiation process was successfull (i.e. the return |
| 97 | * value of #pjmedia_sdp_neg_negotiate() was PJ_SUCCESS), the negotiator |
| 98 | * keeps both active local and active remote SDP. |
| 99 | * |
| 100 | * If application does not want send modified offer, it can just send |
| 101 | * the active local SDP as the offer. In this case, application calls |
| 102 | * #pjmedia_sdp_neg_send_local_offer() to get the active local SDP. |
| 103 | * |
| 104 | * If application wants to modify it's local offer, it MUST inform |
| 105 | * the negotiator about the modified SDP by calling |
| 106 | * #pjmedia_sdp_neg_modify_local_offer(). |
| 107 | * |
| 108 | * In both cases, the negotiator will internally create a copy of the offer, |
| 109 | * and move it's state to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, where it |
| 110 | * waits until application passes the remote answer. |
| 111 | * |
| 112 | * |
| 113 | * \subsection sdpneg_receive_offer Receiving Initial Offer |
| 114 | * |
| 115 | * Application receives an offer in the incoming request from remote to |
| 116 | * establish multimedia session, such as incoming INVITE message with SDP |
| 117 | * body. |
| 118 | * |
| 119 | * Initially, when the initial offer is received, application creates the |
| 120 | * SDP negotiator by calling #pjmedia_sdp_neg_create_w_remote_offer(), |
| 121 | * specifying the remote SDP offer in one of the argument. |
| 122 | * |
| 123 | * At this stage, application may or may not ready to create an answer. |
| 124 | * For example, a SIP B2BUA needs to make outgoing call and receive SDP |
| 125 | * from the outgoing call leg in order to create a SDP answer to the |
| 126 | * incoming call leg. |
| 127 | * |
| 128 | * If application is not ready to create an answer, it passes NULL as |
| 129 | * the local SDP when it calls #pjmedia_sdp_neg_create_w_remote_offer(). |
| 130 | * |
| 131 | * The section @ref sdpneg_create_answer describes the case when |
| 132 | * application is ready to create a SDP answer. |
| 133 | * |
| 134 | * |
| 135 | * \subsection sdpneg_subseq_offer Receiving Subsequent Offer |
| 136 | * |
| 137 | * Application passes subsequent SDP offer received from remote by |
| 138 | * calling #pjmedia_sdp_neg_set_remote_offer(). |
| 139 | * |
| 140 | * The negotiator can only receive subsequent offer after it has finished |
| 141 | * the negotiation process of previous offer/answer session (i.e. the |
| 142 | * negotiator state is PJMEDIA_SDP_NEG_STATE_DONE). |
| 143 | * |
| 144 | * |
| 145 | * \subsection sdpneg_recv_answer Receiving SDP Answer |
| 146 | * |
| 147 | * When application receives SDP answer from remote, it informs the |
| 148 | * negotiator by calling #pjmedia_sdp_neg_set_remote_answer(). The |
| 149 | * negotiator validates the answer (#pjmedia_sdp_validate()), and if |
| 150 | * succeeds, it moves it's state to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO. |
| 151 | * |
| 152 | * Application then instruct the negotiator to negotiate the remote |
| 153 | * answer by calling #pjmedia_sdp_neg_negotiate(). The purpose of |
| 154 | * this negotiation is to verify remote answer, and update the initial |
| 155 | * offer according to the answer. For example, the initial offer may |
| 156 | * specify that a stream is \a sendrecv, while the answer specifies |
| 157 | * that remote stream is \a inactive. In this case, the negotiator |
| 158 | * will update the stream in the local active media as \a inactive |
| 159 | * too. |
| 160 | * |
| 161 | * If #pjmedia_sdp_neg_negotiate() returns PJ_SUCCESS, the negotiator will |
| 162 | * keep the updated local answer and remote answer internally. These two |
| 163 | * SDPs are called active local SDP and active remote SDP, as it describes |
| 164 | * currently active session. |
| 165 | * |
| 166 | * Application can retrieve the active local SDP by calling |
| 167 | * #pjmedia_sdp_neg_get_active_local(), and active remote SDP by calling |
| 168 | * #pjmedia_sdp_neg_get_active_remote(). |
| 169 | * |
| 170 | * If #pjmedia_sdp_neg_negotiate() returns failure (i.e. not PJ_SUCCESS), |
| 171 | * it WILL NOT update its active local and active remote SDP. |
| 172 | * |
| 173 | * Regardless of the return status of the #pjmedia_sdp_neg_negotiate(), |
| 174 | * the negotiator state will move to PJMEDIA_SDP_NEG_STATE_DONE. |
| 175 | * |
| 176 | * |
| 177 | * \subsection sdpneg_cancel_offer Cancelling an Offer |
| 178 | * |
| 179 | * In other case, after an offer is generated (negotiator state is in |
| 180 | * PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER), the answer may not be received, and |
| 181 | * application wants the negotiator to reset itself to its previous state. |
| 182 | * Consider this example: |
| 183 | * |
| 184 | * - media has been established, and negotiator state is |
| 185 | * PJMEDIA_SDP_NEG_STATE_DONE. |
| 186 | * - application generates a new offer for re-INVITE, so in this case |
| 187 | * it would either call #pjmedia_sdp_neg_send_local_offer() or |
| 188 | * #pjmedia_sdp_neg_modify_local_offer() |
| 189 | * - the negotiator state moves to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER |
| 190 | * - the re-INVITE was rejected with an error |
| 191 | * |
| 192 | * Since an answer is not received, it is necessary to reset the negotiator |
| 193 | * state back to PJMEDIA_SDP_NEG_STATE_DONE so that the negotiator can |
| 194 | * create or receive new offer. |
| 195 | * |
| 196 | * This can be accomplished by calling #pjmedia_sdp_neg_cancel_offer(), |
| 197 | * to reset the negotiator state back to PJMEDIA_SDP_NEG_STATE_DONE. In |
| 198 | * this case, both active local and active remote will not be modified. |
| 199 | * |
| 200 | * \subsection sdpneg_create_answer Generating SDP Answer |
| 201 | * |
| 202 | * After remote offer has been set in the negotiator, application can |
| 203 | * request the SDP negotiator to generate appropriate answer based on local |
| 204 | * capability. |
| 205 | * |
| 206 | * To do this, first the application MUST have an SDP describing its local |
| 207 | * capabilities. This SDP can be built manually, or application can generate |
| 208 | * SDP to describe local media endpoint capability by calling |
| 209 | * #pjmedia_endpt_create_sdp(). When the application is a SIP B2BUA, |
| 210 | * application can treat the SDP received from the outgoing call leg as if |
| 211 | * it was it's local capability. |
| 212 | * |
| 213 | * The local SDP session descriptor DOES NOT have to match the SDP offer. |
| 214 | * For example, it can have more or less media lines than the offer, or |
| 215 | * their order may be different than the offer. The negotiator is capable |
| 216 | * to match and reorder local SDP according to remote offer, and create |
| 217 | * an answer that is suitable for the offer. |
| 218 | * |
| 219 | * After local SDP capability has been acquired, application can create |
| 220 | * a SDP answer. |
| 221 | * |
| 222 | * If application does not already have the negotiator instance, it creates |
| 223 | * one by calling #pjmedia_sdp_neg_create_w_remote_offer(), specifying |
| 224 | * both remote SDP offer and local SDP as the arguments. The SDP negotiator |
| 225 | * validates both remote and local SDP by calling #pjmedia_sdp_validate(), |
| 226 | * and if both SDPs are valid, the negotiator state will move to |
| 227 | * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO where it is ready to negotiate the |
| 228 | * offer and answer. |
| 229 | * |
| 230 | * If application already has the negotiator instance, it sets the local |
| 231 | * SDP in the negotiator by calling #pjmedia_sdp_neg_set_local_answer(). |
| 232 | * The SDP negotiator then validates local SDP (#pjmedia_sdp_validate() ), |
| 233 | * and if it is valid, the negotiator state will move to |
| 234 | * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO where it is ready to negotiate the |
| 235 | * offer and answer. |
| 236 | * |
| 237 | * After the SDP negotiator state has moved to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, |
| 238 | * application calls #pjmedia_sdp_neg_negotiate() to instruct the SDP |
| 239 | * negotiator to negotiate both offer and answer. This function returns |
| 240 | * PJ_SUCCESS if an answer can be generated AND at least one media stream |
| 241 | * is active in the session. |
| 242 | * |
| 243 | * If #pjmedia_sdp_neg_negotiate() returns PJ_SUCCESS, the negotiator will |
| 244 | * keep the remote offer and local answer internally. These two SDPs are |
| 245 | * called active local SDP and active remote SDP, as it describes currently |
| 246 | * active session. |
| 247 | * |
| 248 | * Application can retrieve the active local SDP by calling |
| 249 | * #pjmedia_sdp_neg_get_active_local(), and send this SDP to remote as the |
| 250 | * SDP answer. |
| 251 | * |
| 252 | * If #pjmedia_sdp_neg_negotiate() returns failure (i.e. not PJ_SUCCESS), |
| 253 | * it WILL NOT update its active local and active remote SDP. |
| 254 | * |
| 255 | * Regardless of the return status of the #pjmedia_sdp_neg_negotiate(), |
| 256 | * the negotiator state will move to PJMEDIA_SDP_NEG_STATE_DONE. |
| 257 | * |
| 258 | * |
| 259 | */ |
| 260 | |
| 261 | #include <pjmedia/sdp.h> |
| 262 | |
| 263 | PJ_BEGIN_DECL |
| 264 | |
| 265 | /** |
| 266 | * This enumeration describes SDP negotiation state. |
| 267 | */ |
| 268 | enum pjmedia_sdp_neg_state |
| 269 | { |
| 270 | /** |
| 271 | * This is the state of SDP negoator before it is initialized. |
| 272 | */ |
| 273 | PJMEDIA_SDP_NEG_STATE_NULL, |
| 274 | |
| 275 | /** |
| 276 | * This state occurs when SDP negotiator has sent our offer to remote and |
| 277 | * it is waiting for answer. |
| 278 | */ |
| 279 | PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, |
| 280 | |
| 281 | /** |
| 282 | * This state occurs when SDP negotiator has received offer from remote |
| 283 | * and currently waiting for local answer. |
| 284 | */ |
| 285 | PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER, |
| 286 | |
| 287 | /** |
| 288 | * This state occurs when an offer (either local or remote) has been |
| 289 | * provided with answer. The SDP negotiator is ready to negotiate both |
| 290 | * session descriptors. Application can call #pjmedia_sdp_neg_negotiate() |
| 291 | * immediately to begin negotiation process. |
| 292 | */ |
| 293 | PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, |
| 294 | |
| 295 | /** |
| 296 | * This state occurs when SDP negotiation has completed, either |
| 297 | * successfully or not. |
| 298 | */ |
| 299 | PJMEDIA_SDP_NEG_STATE_DONE |
| 300 | }; |
| 301 | |
| 302 | |
| 303 | /** |
| 304 | * @see pjmedia_sdp_neg_state |
| 305 | */ |
| 306 | typedef enum pjmedia_sdp_neg_state pjmedia_sdp_neg_state; |
| 307 | |
| 308 | |
| 309 | /** |
| 310 | * Opaque declaration of SDP negotiator. |
| 311 | */ |
| 312 | typedef struct pjmedia_sdp_neg pjmedia_sdp_neg; |
| 313 | |
| 314 | |
| 315 | /** |
| 316 | * Flags to be given to pjmedia_sdp_neg_modify_local_offer2(). |
| 317 | */ |
| 318 | typedef enum pjmedia_mod_offer_flag |
| 319 | { |
| 320 | /** |
| 321 | * Allow media type in the SDP to be changed. |
| 322 | * When generating a new offer, in the case that a media line doesn't match |
| 323 | * the active SDP, the new media line will be considered to replace the |
| 324 | * existing media at the same position. |
| 325 | */ |
| 326 | PJMEDIA_SDP_NEG_ALLOW_MEDIA_CHANGE = 1 |
| 327 | |
| 328 | } pjmedia_mod_offer_flag; |
| 329 | |
| 330 | |
| 331 | /** |
| 332 | * Get the state string description of the specified state. |
| 333 | * |
| 334 | * @param state Negotiator state. |
| 335 | * |
| 336 | * @return String description of the state. |
| 337 | */ |
| 338 | PJ_DECL(const char*) pjmedia_sdp_neg_state_str(pjmedia_sdp_neg_state state); |
| 339 | |
| 340 | |
| 341 | /** |
| 342 | * Create the SDP negotiator with local offer. The SDP negotiator then |
| 343 | * will move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER state, where it waits |
| 344 | * until it receives answer from remote. When SDP answer from remote is |
| 345 | * received, application must call #pjmedia_sdp_neg_set_remote_answer(). |
| 346 | * |
| 347 | * After calling this function, application should send the local SDP offer |
| 348 | * to remote party using signaling protocol such as SIP and wait for SDP |
| 349 | * answer. |
| 350 | * |
| 351 | * @param pool Pool to allocate memory. The pool's lifetime needs |
| 352 | * to be valid for the duration of the negotiator. |
| 353 | * @param local The initial local capability. |
| 354 | * @param p_neg Pointer to receive the negotiator instance. |
| 355 | * |
| 356 | * @return PJ_SUCCESS on success, or the appropriate error |
| 357 | * code. |
| 358 | */ |
| 359 | PJ_DECL(pj_status_t) |
| 360 | pjmedia_sdp_neg_create_w_local_offer( pj_pool_t *pool, |
| 361 | const pjmedia_sdp_session *local, |
| 362 | pjmedia_sdp_neg **p_neg); |
| 363 | |
| 364 | /** |
| 365 | * Initialize the SDP negotiator with remote offer, and optionally |
| 366 | * specify the initial local capability, if known. Application normally |
| 367 | * calls this function when it receives initial offer from remote. |
| 368 | * |
| 369 | * If local media capability is specified, this capability will be set as |
| 370 | * initial local capability of the negotiator, and after this function is |
| 371 | * called, the SDP negotiator state will move to state |
| 372 | * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and the negotiation function can be |
| 373 | * called. |
| 374 | * |
| 375 | * If local SDP is not specified, the negotiator will not have initial local |
| 376 | * capability, and after this function is called the negotiator state will |
| 377 | * move to PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER state. Application MUST supply |
| 378 | * local answer later with #pjmedia_sdp_neg_set_local_answer(), before |
| 379 | * calling the negotiation function. |
| 380 | * |
| 381 | * @param pool Pool to allocate memory. The pool's lifetime needs |
| 382 | * to be valid for the duration of the negotiator. |
| 383 | * @param initial Optional initial local capability. |
| 384 | * @param remote The remote offer. |
| 385 | * @param p_neg Pointer to receive the negotiator instance. |
| 386 | * |
| 387 | * @return PJ_SUCCESS on success, or the appropriate error |
| 388 | * code. |
| 389 | */ |
| 390 | PJ_DECL(pj_status_t) |
| 391 | pjmedia_sdp_neg_create_w_remote_offer(pj_pool_t *pool, |
| 392 | const pjmedia_sdp_session *initial, |
| 393 | const pjmedia_sdp_session *remote, |
| 394 | pjmedia_sdp_neg **p_neg); |
| 395 | |
| 396 | /** |
| 397 | * This specifies the behavior of the SDP negotiator when responding to an |
| 398 | * offer, whether it should rather use the codec preference as set by |
| 399 | * remote, or should it rather use the codec preference as specified by |
| 400 | * local endpoint. |
| 401 | * |
| 402 | * For example, suppose incoming call has codec order "8 0 3", while |
| 403 | * local codec order is "3 0 8". If remote codec order is preferable, |
| 404 | * the selected codec will be 8, while if local codec order is preferable, |
| 405 | * the selected codec will be 3. |
| 406 | * |
| 407 | * By default, the value in PJMEDIA_SDP_NEG_PREFER_REMOTE_CODEC_ORDER will |
| 408 | * be used. |
| 409 | * |
| 410 | * @param neg The SDP negotiator instance. |
| 411 | * @param prefer_remote If non-zero, the negotiator will use the codec |
| 412 | * order as specified in remote offer. If zero, it |
| 413 | * will prefer to use the local codec order. |
| 414 | */ |
| 415 | PJ_DECL(pj_status_t) |
| 416 | pjmedia_sdp_neg_set_prefer_remote_codec_order(pjmedia_sdp_neg *neg, |
| 417 | pj_bool_t prefer_remote); |
| 418 | |
| 419 | /** |
| 420 | * This specifies the behavior of the SDP negotiator when responding to an |
| 421 | * offer, whether it should answer with multiple formats or not. |
| 422 | * |
| 423 | * By default, the value in PJMEDIA_SDP_NEG_ANSWER_MULTIPLE_CODECS will |
| 424 | * be used. |
| 425 | * |
| 426 | * @param neg The SDP negotiator instance. |
| 427 | * @param answer_multiple |
| 428 | * If non-zero, the negotiator will respond with |
| 429 | * multiple formats. If zero only a single format |
| 430 | * will be returned. |
| 431 | */ |
| 432 | PJ_DECL(pj_status_t) |
| 433 | pjmedia_sdp_neg_set_answer_multiple_codecs(pjmedia_sdp_neg *neg, |
| 434 | pj_bool_t answer_multiple); |
| 435 | |
| 436 | |
| 437 | /** |
| 438 | * Get SDP negotiator state. |
| 439 | * |
| 440 | * @param neg The SDP negotiator instance. |
| 441 | * |
| 442 | * @return The negotiator state. |
| 443 | */ |
| 444 | PJ_DECL(pjmedia_sdp_neg_state) |
| 445 | pjmedia_sdp_neg_get_state( pjmedia_sdp_neg *neg ); |
| 446 | |
| 447 | /** |
| 448 | * Get the currently active local SDP. Application can only call this |
| 449 | * function after negotiation has been done, or otherwise there won't be |
| 450 | * active SDPs. Calling this function will not change the state of the |
| 451 | * negotiator. |
| 452 | * |
| 453 | * @param neg The SDP negotiator instance. |
| 454 | * @param local Pointer to receive the local active SDP. |
| 455 | * |
| 456 | * @return PJ_SUCCESS if local active SDP is present. |
| 457 | */ |
| 458 | PJ_DECL(pj_status_t) |
| 459 | pjmedia_sdp_neg_get_active_local( pjmedia_sdp_neg *neg, |
| 460 | const pjmedia_sdp_session **local); |
| 461 | |
| 462 | /** |
| 463 | * Get the currently active remote SDP. Application can only call this |
| 464 | * function after negotiation has been done, or otherwise there won't be |
| 465 | * active SDPs. Calling this function will not change the state of the |
| 466 | * negotiator. |
| 467 | * |
| 468 | * @param neg The SDP negotiator instance. |
| 469 | * @param remote Pointer to receive the remote active SDP. |
| 470 | * |
| 471 | * @return PJ_SUCCESS if remote active SDP is present. |
| 472 | */ |
| 473 | PJ_DECL(pj_status_t) |
| 474 | pjmedia_sdp_neg_get_active_remote( pjmedia_sdp_neg *neg, |
| 475 | const pjmedia_sdp_session **remote); |
| 476 | |
| 477 | |
| 478 | /** |
| 479 | * Determine whether remote sent answer (as opposed to offer) on the |
| 480 | * last negotiation. This function can only be called in state |
| 481 | * PJMEDIA_SDP_NEG_STATE_DONE. |
| 482 | * |
| 483 | * @param neg The SDP negotiator instance. |
| 484 | * |
| 485 | * @return Non-zero if it was remote who sent answer, |
| 486 | * otherwise zero if it was local who supplied |
| 487 | * answer. |
| 488 | */ |
| 489 | PJ_DECL(pj_bool_t) |
| 490 | pjmedia_sdp_neg_was_answer_remote(pjmedia_sdp_neg *neg); |
| 491 | |
| 492 | |
| 493 | /** |
| 494 | * Get the current remote SDP offer or answer. Application can only |
| 495 | * call this function in state PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER or |
| 496 | * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, or otherwise there won't be remote |
| 497 | * SDP offer/answer. Calling this function will not change the state |
| 498 | * of the negotiator. |
| 499 | * |
| 500 | * @param neg The SDP negotiator instance. |
| 501 | * @param remote Pointer to receive the current remote offer or |
| 502 | * answer. |
| 503 | * |
| 504 | * @return PJ_SUCCESS if the negotiator currently has |
| 505 | * remote offer or answer. |
| 506 | */ |
| 507 | PJ_DECL(pj_status_t) |
| 508 | pjmedia_sdp_neg_get_neg_remote( pjmedia_sdp_neg *neg, |
| 509 | const pjmedia_sdp_session **remote); |
| 510 | |
| 511 | |
| 512 | /** |
| 513 | * Get the current local SDP offer or answer. Application can only |
| 514 | * call this function in state PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER or |
| 515 | * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, or otherwise there won't be local |
| 516 | * SDP offer/answer. Calling this function will not change the state |
| 517 | * of the negotiator. |
| 518 | * |
| 519 | * @param neg The SDP negotiator instance. |
| 520 | * @param local Pointer to receive the current local offer or |
| 521 | * answer. |
| 522 | * |
| 523 | * @return PJ_SUCCESS if the negotiator currently has |
| 524 | * local offer or answer. |
| 525 | */ |
| 526 | PJ_DECL(pj_status_t) |
| 527 | pjmedia_sdp_neg_get_neg_local( pjmedia_sdp_neg *neg, |
| 528 | const pjmedia_sdp_session **local); |
| 529 | |
| 530 | /** |
| 531 | * Modify local session with a new SDP and treat this as a new offer. |
| 532 | * This function can only be called in state PJMEDIA_SDP_NEG_STATE_DONE. |
| 533 | * After calling this function, application can send the SDP as offer |
| 534 | * to remote party, using signaling protocol such as SIP. |
| 535 | * The negotiator state will move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, |
| 536 | * where it waits for SDP answer from remote. See also |
| 537 | * #pjmedia_sdp_neg_modify_local_offer2() |
| 538 | * |
| 539 | * @param pool Pool to allocate memory. The pool's lifetime needs |
| 540 | * to be valid for the duration of the negotiator. |
| 541 | * @param neg The SDP negotiator instance. |
| 542 | * @param local The new local SDP. |
| 543 | * |
| 544 | * @return PJ_SUCCESS on success, or the appropriate |
| 545 | * error code. |
| 546 | */ |
| 547 | PJ_DECL(pj_status_t) |
| 548 | pjmedia_sdp_neg_modify_local_offer( pj_pool_t *pool, |
| 549 | pjmedia_sdp_neg *neg, |
| 550 | const pjmedia_sdp_session *local); |
| 551 | |
| 552 | /** |
| 553 | * Modify local session with a new SDP and treat this as a new offer. |
| 554 | * This function can only be called in state PJMEDIA_SDP_NEG_STATE_DONE. |
| 555 | * After calling this function, application can send the SDP as offer |
| 556 | * to remote party, using signaling protocol such as SIP. |
| 557 | * The negotiator state will move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, |
| 558 | * where it waits for SDP answer from remote. |
| 559 | * |
| 560 | * @param pool Pool to allocate memory. The pool's lifetime needs |
| 561 | * to be valid for the duration of the negotiator. |
| 562 | * @param neg The SDP negotiator instance. |
| 563 | * @param flags Bitmask from pjmedia_mod_offer_flag. |
| 564 | * @param local The new local SDP. |
| 565 | * |
| 566 | * @return PJ_SUCCESS on success, or the appropriate |
| 567 | * error code. |
| 568 | */ |
| 569 | PJ_DECL(pj_status_t) |
| 570 | pjmedia_sdp_neg_modify_local_offer2( pj_pool_t *pool, |
| 571 | pjmedia_sdp_neg *neg, |
| 572 | unsigned flags, |
| 573 | const pjmedia_sdp_session *local); |
| 574 | |
| 575 | /** |
| 576 | * This function can only be called in PJMEDIA_SDP_NEG_STATE_DONE state. |
| 577 | * Application calls this function to retrieve currently active |
| 578 | * local SDP, and then send the SDP to remote as an offer. The negotiator |
| 579 | * state will then move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, where it waits |
| 580 | * for SDP answer from remote. |
| 581 | * |
| 582 | * When SDP answer has been received from remote, application must call |
| 583 | * #pjmedia_sdp_neg_set_remote_answer(). |
| 584 | * |
| 585 | * @param pool Pool to allocate memory. The pool's lifetime needs |
| 586 | * to be valid for the duration of the negotiator. |
| 587 | * @param neg The SDP negotiator instance. |
| 588 | * @param offer Pointer to receive active local SDP to be |
| 589 | * offered to remote. |
| 590 | * |
| 591 | * @return PJ_SUCCESS if local offer can be created. |
| 592 | */ |
| 593 | PJ_DECL(pj_status_t) |
| 594 | pjmedia_sdp_neg_send_local_offer( pj_pool_t *pool, |
| 595 | pjmedia_sdp_neg *neg, |
| 596 | const pjmedia_sdp_session **offer); |
| 597 | |
| 598 | /** |
| 599 | * This function can only be called in PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER |
| 600 | * state, i.e. after application calls #pjmedia_sdp_neg_send_local_offer() |
| 601 | * function. Application calls this function when it receives SDP answer |
| 602 | * from remote. After this function is called, the negotiator state will |
| 603 | * move to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and application can call the |
| 604 | * negotiation function #pjmedia_sdp_neg_negotiate(). |
| 605 | * |
| 606 | * @param pool Pool to allocate memory. The pool's lifetime needs |
| 607 | * to be valid for the duration of the negotiator. |
| 608 | * @param neg The SDP negotiator instance. |
| 609 | * @param remote The remote answer. |
| 610 | * |
| 611 | * @return PJ_SUCCESS on success. |
| 612 | */ |
| 613 | PJ_DECL(pj_status_t) |
| 614 | pjmedia_sdp_neg_set_remote_answer( pj_pool_t *pool, |
| 615 | pjmedia_sdp_neg *neg, |
| 616 | const pjmedia_sdp_session *remote); |
| 617 | |
| 618 | |
| 619 | |
| 620 | /** |
| 621 | * This function can only be called in PJMEDIA_SDP_NEG_STATE_DONE state. |
| 622 | * Application calls this function when it receives SDP offer from remote. |
| 623 | * After this function is called, the negotiator state will move to |
| 624 | * PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER, and application MUST call the |
| 625 | * #pjmedia_sdp_neg_set_local_answer() to set local answer before it can |
| 626 | * call the negotiation function. |
| 627 | * |
| 628 | * @param pool Pool to allocate memory. The pool's lifetime needs |
| 629 | * to be valid for the duration of the negotiator. |
| 630 | * @param neg The SDP negotiator instance. |
| 631 | * @param remote The remote offer. |
| 632 | * |
| 633 | * @return PJ_SUCCESS on success. |
| 634 | */ |
| 635 | PJ_DECL(pj_status_t) |
| 636 | pjmedia_sdp_neg_set_remote_offer( pj_pool_t *pool, |
| 637 | pjmedia_sdp_neg *neg, |
| 638 | const pjmedia_sdp_session *remote); |
| 639 | |
| 640 | |
| 641 | |
| 642 | /** |
| 643 | * This function can only be called in PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER |
| 644 | * state, i.e. after application calls #pjmedia_sdp_neg_set_remote_offer() |
| 645 | * function. After this function is called, the negotiator state will |
| 646 | * move to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and application can call the |
| 647 | * negotiation function #pjmedia_sdp_neg_negotiate(). |
| 648 | * |
| 649 | * @param pool Pool to allocate memory. The pool's lifetime needs |
| 650 | * to be valid for the duration of the negotiator. |
| 651 | * @param neg The SDP negotiator instance. |
| 652 | * @param local Optional local answer. If negotiator has initial |
| 653 | * local capability, application can specify NULL on |
| 654 | * this argument; in this case, the negotiator will |
| 655 | * create answer by by negotiating remote offer with |
| 656 | * initial local capability. If negotiator doesn't have |
| 657 | * initial local capability, application MUST specify |
| 658 | * local answer here. |
| 659 | * |
| 660 | * @return PJ_SUCCESS on success. |
| 661 | */ |
| 662 | PJ_DECL(pj_status_t) |
| 663 | pjmedia_sdp_neg_set_local_answer( pj_pool_t *pool, |
| 664 | pjmedia_sdp_neg *neg, |
| 665 | const pjmedia_sdp_session *local); |
| 666 | |
| 667 | |
| 668 | /** |
| 669 | * Call this function when the negotiator is in PJMEDIA_SDP_NEG_STATE_WAIT_NEGO |
| 670 | * state to see if it was local who is answering the offer (instead of |
| 671 | * remote). |
| 672 | * |
| 673 | * @param neg The negotiator. |
| 674 | * |
| 675 | * @return PJ_TRUE if it is local is answering an offer, PJ_FALSE |
| 676 | * if remote has answered local offer. |
| 677 | */ |
| 678 | PJ_DECL(pj_bool_t) pjmedia_sdp_neg_has_local_answer(pjmedia_sdp_neg *neg); |
| 679 | |
| 680 | |
| 681 | /** |
| 682 | * Cancel any pending offer, whether the offer is initiated by local or |
| 683 | * remote, and move negotiator state back to previous stable state |
| 684 | * (PJMEDIA_SDP_NEG_STATE_DONE). The negotiator must be in |
| 685 | * PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER or PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER |
| 686 | * state. |
| 687 | * |
| 688 | * @param neg The negotiator. |
| 689 | * |
| 690 | * @return PJ_SUCCESS or the appropriate error code. |
| 691 | */ |
| 692 | PJ_DECL(pj_status_t) pjmedia_sdp_neg_cancel_offer(pjmedia_sdp_neg *neg); |
| 693 | |
| 694 | |
| 695 | /** |
| 696 | * Negotiate local and remote answer. Before calling this function, the |
| 697 | * SDP negotiator must be in PJMEDIA_SDP_NEG_STATE_WAIT_NEGO state. |
| 698 | * After calling this function, the negotiator state will move to |
| 699 | * PJMEDIA_SDP_NEG_STATE_DONE regardless whether the negotiation has |
| 700 | * been successfull or not. |
| 701 | * |
| 702 | * If the negotiation succeeds (i.e. the return value is PJ_SUCCESS), |
| 703 | * the active local and remote SDP will be replaced with the new SDP |
| 704 | * from the negotiation process. |
| 705 | * |
| 706 | * If the negotiation fails, the active local and remote SDP will not |
| 707 | * change. |
| 708 | * |
| 709 | * @param pool Pool to allocate memory. The pool's lifetime needs |
| 710 | * to be valid for the duration of the negotiator. |
| 711 | * @param neg The SDP negotiator instance. |
| 712 | * @param allow_asym Should be zero. |
| 713 | * |
| 714 | * @return PJ_SUCCESS when there is at least one media |
| 715 | * is actuve common in both offer and answer, or |
| 716 | * failure code when negotiation has failed. |
| 717 | */ |
| 718 | PJ_DECL(pj_status_t) pjmedia_sdp_neg_negotiate( pj_pool_t *pool, |
| 719 | pjmedia_sdp_neg *neg, |
| 720 | pj_bool_t allow_asym); |
| 721 | |
| 722 | |
| 723 | /** |
| 724 | * Enumeration of customized SDP format matching option flags. See |
| 725 | * #pjmedia_sdp_neg_register_fmt_match_cb() for more info. |
| 726 | */ |
| 727 | typedef enum pjmedia_sdp_neg_fmt_match_flag |
| 728 | { |
| 729 | /** |
| 730 | * In generating answer, the SDP fmtp in the answer candidate may need |
| 731 | * to be modified by the customized SDP format matching callback to |
| 732 | * achieve flexible SDP negotiation, e.g: AMR fmtp 'octet-align' field |
| 733 | * can be adjusted with the offer when the codec implementation support |
| 734 | * both packetization modes octet-aligned and bandwidth-efficient. |
| 735 | */ |
| 736 | PJMEDIA_SDP_NEG_FMT_MATCH_ALLOW_MODIFY_ANSWER = 1, |
| 737 | |
| 738 | } pjmedia_sdp_neg_fmt_match_flag; |
| 739 | |
| 740 | |
| 741 | /** |
| 742 | * The declaration of customized SDP format matching callback. See |
| 743 | * #pjmedia_sdp_neg_register_fmt_match_cb() for more info. |
| 744 | * |
| 745 | * @param pool The memory pool. |
| 746 | * @param offer The SDP media offer. |
| 747 | * @param o_fmt_idx Index of the format in the SDP media offer. |
| 748 | * @param answer The SDP media answer. |
| 749 | * @param a_fmt_idx Index of the format in the SDP media answer. |
| 750 | * @param option The format matching option, see |
| 751 | * #pjmedia_sdp_neg_fmt_match_flag. |
| 752 | * |
| 753 | * @return PJ_SUCCESS when the formats in offer and answer match. |
| 754 | */ |
| 755 | typedef pj_status_t (*pjmedia_sdp_neg_fmt_match_cb)(pj_pool_t *pool, |
| 756 | pjmedia_sdp_media *offer, |
| 757 | unsigned o_fmt_idx, |
| 758 | pjmedia_sdp_media *answer, |
| 759 | unsigned a_fmt_idx, |
| 760 | unsigned option); |
| 761 | |
| 762 | |
| 763 | /** |
| 764 | * Register customized SDP format matching callback function for the specified |
| 765 | * format. The customized SDP format matching is needed when the format |
| 766 | * identification in a media stream session cannot be simply determined by |
| 767 | * encoding name and clock rate, but also involves one or more format specific |
| 768 | * parameters, which are specified in SDP fmtp attribute. For example, |
| 769 | * an H.264 video stream is also identified by profile, level, and |
| 770 | * packetization-mode parameters. As those parameters are format specifics, |
| 771 | * the negotiation must be done by the format or codec implementation. |
| 772 | * |
| 773 | * To unregister the callback of specific format, just call this function with |
| 774 | * parameter #cb set to NULL. |
| 775 | * |
| 776 | * @param fmt_name The format name, e.g: "H.264", "AMR", "G7221". Note |
| 777 | * that the string buffer must remain valid until the |
| 778 | * callback is unregistered. |
| 779 | * @param cb The customized SDP format negotiation callback or |
| 780 | * NULL to unregister the specified format callback. |
| 781 | * |
| 782 | * @return PJ_SUCCESS on success. |
| 783 | */ |
| 784 | PJ_DECL(pj_status_t) pjmedia_sdp_neg_register_fmt_match_cb( |
| 785 | const pj_str_t *fmt_name, |
| 786 | pjmedia_sdp_neg_fmt_match_cb cb); |
| 787 | |
| 788 | |
| 789 | /** |
| 790 | * Match format in the SDP media offer and answer. The matching mechanism |
| 791 | * will be done by comparing the encoding name and clock rate, and if the |
| 792 | * custom format matching callback for the specified format is registered, |
| 793 | * see #pjmedia_sdp_neg_register_fmt_match_cb(), it will be called for more |
| 794 | * detail verification, e.g: format parameters specified in SDP fmtp. |
| 795 | * |
| 796 | * @param pool The memory pool. |
| 797 | * @param offer The SDP media offer. |
| 798 | * @param o_fmt_idx Index of the format in the SDP media offer. |
| 799 | * @param answer The SDP media answer. |
| 800 | * @param a_fmt_idx Index of the format in the SDP media answer. |
| 801 | * @param option The format matching option, see |
| 802 | * #pjmedia_sdp_neg_fmt_match_flag. |
| 803 | * |
| 804 | * @return PJ_SUCCESS when the formats in offer and answer match. |
| 805 | */ |
| 806 | PJ_DECL(pj_status_t) pjmedia_sdp_neg_fmt_match( pj_pool_t *pool, |
| 807 | pjmedia_sdp_media *offer, |
| 808 | unsigned o_fmt_idx, |
| 809 | pjmedia_sdp_media *answer, |
| 810 | unsigned a_fmt_idx, |
| 811 | unsigned option); |
| 812 | |
| 813 | |
| 814 | PJ_END_DECL |
| 815 | |
| 816 | /** |
| 817 | * @} |
| 818 | */ |
| 819 | |
| 820 | |
| 821 | #endif /* __PJMEDIA_SDP_NEG_H__ */ |
| 822 | |