/usr/include/pjmedia/sdp_neg.h is in libpjproject-dev 2.1.0.0.ast20130823-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 | /* $Id: sdp_neg.h 3664 2011-07-19 03:42:28Z nanang $ */
/*
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
* Copyright (C) 2003-2008 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 __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 |<-----------------------
* | +-------------+______ |
* | | \______ cancel() |
* | 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_cancel_offer Cancelling an Offer
*
* In other case, after an offer is generated (negotiator state is in
* PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER), the answer may not be received, and
* application wants the negotiator to reset itself to its previous state.
* Consider this example:
*
* - media has been established, and negotiator state is
* PJMEDIA_SDP_NEG_STATE_DONE.
* - application generates a new offer for re-INVITE, so in this case
* it would either call #pjmedia_sdp_neg_send_local_offer() or
* #pjmedia_sdp_neg_modify_local_offer()
* - the negotiator state moves to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER
* - the re-INVITE was rejected with an error
*
* Since an answer is not received, it is necessary to reset the negotiator
* state back to PJMEDIA_SDP_NEG_STATE_DONE so that the negotiator can
* create or receive new offer.
*
* This can be accomplished by calling #pjmedia_sdp_neg_cancel_offer(),
* to reset the negotiator state back to PJMEDIA_SDP_NEG_STATE_DONE. In
* this case, both active local and active remote will not be modified.
*
* \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;
/**
* Flags to be given to pjmedia_sdp_neg_modify_local_offer2().
*/
typedef enum pjmedia_mod_offer_flag
{
/**
* Allow media type in the SDP to be changed.
* When generating a new offer, in the case that a media line doesn't match
* the active SDP, the new media line will be considered to replace the
* existing media at the same position.
*/
PJMEDIA_SDP_NEG_ALLOW_MEDIA_CHANGE = 1
} pjmedia_mod_offer_flag;
/**
* 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,
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);
/**
* This specifies the behavior of the SDP negotiator when responding to an
* offer, whether it should answer with multiple formats or not.
*
* By default, the value in PJMEDIA_SDP_NEG_ANSWER_MULTIPLE_CODECS will
* be used.
*
* @param neg The SDP negotiator instance.
* @param answer_multiple If non-zero, the negotiator will respond with
* multiple formats. If zero only a single format will be returned.
*/
PJ_DECL(pj_status_t)
pjmedia_sdp_neg_set_answer_multiple_codecs(pjmedia_sdp_neg *neg,
pj_bool_t answer_multiple);
/**
* 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. See also
* #pjmedia_sdp_neg_modify_local_offer2()
*
* @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);
/**
* 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 flags Bitmask from pjmedia_mod_offer_flag.
* @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_offer2( pj_pool_t *pool,
pjmedia_sdp_neg *neg,
unsigned flags,
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);
/**
* Cancel any pending offer, whether the offer is initiated by local or
* remote, and move negotiator state back to previous stable state
* (PJMEDIA_SDP_NEG_STATE_DONE). The negotiator must be in
* PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER or PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER
* state.
*
* @param neg The negotiator.
*
* @return PJ_SUCCESS or the appropriate error code.
*/
PJ_DECL(pj_status_t) pjmedia_sdp_neg_cancel_offer(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);
/**
* Enumeration of customized SDP format matching option flags. See
* #pjmedia_sdp_neg_register_fmt_match_cb() for more info.
*/
typedef enum pjmedia_sdp_neg_fmt_match_flag
{
/**
* In generating answer, the SDP fmtp in the answer candidate may need
* to be modified by the customized SDP format matching callback to
* achieve flexible SDP negotiation, e.g: AMR fmtp 'octet-align' field
* can be adjusted with the offer when the codec implementation support
* both packetization modes octet-aligned and bandwidth-efficient.
*/
PJMEDIA_SDP_NEG_FMT_MATCH_ALLOW_MODIFY_ANSWER = 1,
} pjmedia_sdp_neg_fmt_match_flag;
/**
* The declaration of customized SDP format matching callback. See
* #pjmedia_sdp_neg_register_fmt_match_cb() for more info.
*
* @param pool The memory pool.
* @param offer The SDP media offer.
* @param o_fmt_idx Index of the format in the SDP media offer.
* @param answer The SDP media answer.
* @param a_fmt_idx Index of the format in the SDP media answer.
* @param option The format matching option, see
* #pjmedia_sdp_neg_fmt_match_flag.
*
* @return PJ_SUCCESS when the formats in offer and answer match.
*/
typedef pj_status_t (*pjmedia_sdp_neg_fmt_match_cb)(pj_pool_t *pool,
pjmedia_sdp_media *offer,
unsigned o_fmt_idx,
pjmedia_sdp_media *answer,
unsigned a_fmt_idx,
unsigned option);
/**
* Register customized SDP format matching callback function for the specified
* format. The customized SDP format matching is needed when the format
* identification in a media stream session cannot be simply determined by
* encoding name and clock rate, but also involves one or more format specific
* parameters, which are specified in SDP fmtp attribute. For example,
* an H.264 video stream is also identified by profile, level, and
* packetization-mode parameters. As those parameters are format specifics,
* the negotiation must be done by the format or codec implementation.
*
* To unregister the callback of specific format, just call this function with
* parameter #cb set to NULL.
*
* @param fmt_name The format name, e.g: "H.264", "AMR", "G7221". Note
* that the string buffer must remain valid until the
* callback is unregistered.
* @param cb The customized SDP format negotiation callback or
* NULL to unregister the specified format callback.
*
* @return PJ_SUCCESS on success.
*/
PJ_DECL(pj_status_t) pjmedia_sdp_neg_register_fmt_match_cb(
const pj_str_t *fmt_name,
pjmedia_sdp_neg_fmt_match_cb cb);
/**
* Match format in the SDP media offer and answer. The matching mechanism
* will be done by comparing the encoding name and clock rate, and if the
* custom format matching callback for the specified format is registered,
* see #pjmedia_sdp_neg_register_fmt_match_cb(), it will be called for more
* detail verification, e.g: format parameters specified in SDP fmtp.
*
* @param pool The memory pool.
* @param offer The SDP media offer.
* @param o_fmt_idx Index of the format in the SDP media offer.
* @param answer The SDP media answer.
* @param a_fmt_idx Index of the format in the SDP media answer.
* @param option The format matching option, see
* #pjmedia_sdp_neg_fmt_match_flag.
*
* @return PJ_SUCCESS when the formats in offer and answer match.
*/
PJ_DECL(pj_status_t) pjmedia_sdp_neg_fmt_match( pj_pool_t *pool,
pjmedia_sdp_media *offer,
unsigned o_fmt_idx,
pjmedia_sdp_media *answer,
unsigned a_fmt_idx,
unsigned option);
PJ_END_DECL
/**
* @}
*/
#endif /* __PJMEDIA_SDP_NEG_H__ */
|