Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjmedia / include / pjmedia / sdp_neg.h
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  *    |                               |             \______ cancel()  |
56  *    |           set_remote_answer() |                    \______    |
57  *    |                               V                            \  |
58  * +--+---+                     +-----------+     negotiate()     +-~----+
59  * | NULL |                     | WAIT_NEGO |-------------------->| DONE |
60  * +------+                     +-----------+                     +------+
61  *    |                               A                               |
62  *    |            set_local_answer() |                               |
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  * Get the state string description of the specified state.
317  *
318  * @param state         Negotiator state.
319  *
320  * @return              String description of the state.
321  */
322 PJ_DECL(const char*) pjmedia_sdp_neg_state_str(pjmedia_sdp_neg_state state);
323
324
325 /**
326  * Create the SDP negotiator with local offer. The SDP negotiator then
327  * will move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER state, where it waits
328  * until it receives answer from remote. When SDP answer from remote is
329  * received, application must call #pjmedia_sdp_neg_set_remote_answer().
330  *
331  * After calling this function, application should send the local SDP offer
332  * to remote party using signaling protocol such as SIP and wait for SDP 
333  * answer.
334  *
335  * @param pool          Pool to allocate memory. The pool's lifetime needs
336  *                      to be valid for the duration of the negotiator.
337  * @param local         The initial local capability.
338  * @param p_neg         Pointer to receive the negotiator instance.
339  *
340  * @return              PJ_SUCCESS on success, or the appropriate error
341  *                      code.
342  */
343 PJ_DECL(pj_status_t) 
344 pjmedia_sdp_neg_create_w_local_offer( pj_pool_t *pool,
345                                       const pjmedia_sdp_session *local,
346                                       pjmedia_sdp_neg **p_neg);
347
348 /**
349  * Initialize the SDP negotiator with remote offer, and optionally
350  * specify the initial local capability, if known. Application normally 
351  * calls this function when it receives initial offer from remote. 
352  *
353  * If local media capability is specified, this capability will be set as
354  * initial local capability of the negotiator, and after this function is
355  * called, the SDP negotiator state will move to state
356  * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and the negotiation function can be 
357  * called. 
358  *
359  * If local SDP is not specified, the negotiator will not have initial local
360  * capability, and after this function is called the negotiator state will 
361  * move to PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER state. Application MUST supply
362  * local answer later with #pjmedia_sdp_neg_set_local_answer(), before
363  * calling the negotiation function.
364  *
365  * @param pool          Pool to allocate memory. The pool's lifetime needs
366  *                      to be valid for the duration of the negotiator.
367  * @param initial       Optional initial local capability.
368  * @param remote        The remote offer.
369  * @param p_neg         Pointer to receive the negotiator instance.
370  *
371  * @return              PJ_SUCCESS on success, or the appropriate error
372  *                      code.
373  */
374 PJ_DECL(pj_status_t) 
375 pjmedia_sdp_neg_create_w_remote_offer(pj_pool_t *pool,
376                                       const pjmedia_sdp_session *initial,
377                                       const pjmedia_sdp_session *remote,
378                                       pjmedia_sdp_neg **p_neg);
379
380 /**
381  * This specifies the behavior of the SDP negotiator when responding to an
382  * offer, whether it should rather use the codec preference as set by
383  * remote, or should it rather use the codec preference as specified by
384  * local endpoint.
385  *
386  * For example, suppose incoming call has codec order "8 0 3", while 
387  * local codec order is "3 0 8". If remote codec order is preferable,
388  * the selected codec will be 8, while if local codec order is preferable,
389  * the selected codec will be 3.
390  *
391  * By default, the value in PJMEDIA_SDP_NEG_PREFER_REMOTE_CODEC_ORDER will
392  * be used.
393  *
394  * @param neg           The SDP negotiator instance.
395  * @param prefer_remote If non-zero, the negotiator will use the codec
396  *                      order as specified in remote offer. If zero, it
397  *                      will prefer to use the local codec order.
398  */
399 PJ_DECL(pj_status_t)
400 pjmedia_sdp_neg_set_prefer_remote_codec_order(pjmedia_sdp_neg *neg,
401                                               pj_bool_t prefer_remote);
402
403
404 /**
405  * Get SDP negotiator state.
406  *
407  * @param neg           The SDP negotiator instance.
408  *
409  * @return              The negotiator state.
410  */
411 PJ_DECL(pjmedia_sdp_neg_state)
412 pjmedia_sdp_neg_get_state( pjmedia_sdp_neg *neg );
413
414 /**
415  * Get the currently active local SDP. Application can only call this
416  * function after negotiation has been done, or otherwise there won't be
417  * active SDPs. Calling this function will not change the state of the 
418  * negotiator.
419  *
420  * @param neg           The SDP negotiator instance.
421  * @param local         Pointer to receive the local active SDP.
422  *
423  * @return              PJ_SUCCESS if local active SDP is present.
424  */
425 PJ_DECL(pj_status_t) 
426 pjmedia_sdp_neg_get_active_local( pjmedia_sdp_neg *neg,
427                                   const pjmedia_sdp_session **local);
428
429 /**
430  * Get the currently active remote SDP. Application can only call this
431  * function after negotiation has been done, or otherwise there won't be
432  * active SDPs. Calling this function will not change the state of the 
433  * negotiator.
434  *
435  * @param neg           The SDP negotiator instance.
436  * @param remote        Pointer to receive the remote active SDP.
437  *
438  * @return              PJ_SUCCESS if remote active SDP is present.
439  */
440 PJ_DECL(pj_status_t) 
441 pjmedia_sdp_neg_get_active_remote( pjmedia_sdp_neg *neg,
442                                    const pjmedia_sdp_session **remote);
443
444
445 /**
446  * Determine whether remote sent answer (as opposed to offer) on the
447  * last negotiation. This function can only be called in state
448  * PJMEDIA_SDP_NEG_STATE_DONE.
449  *
450  * @param neg           The SDP negotiator instance.
451  *
452  * @return              Non-zero if it was remote who sent answer,
453  *                      otherwise zero if it was local who supplied
454  *                      answer.
455  */
456 PJ_DECL(pj_bool_t)
457 pjmedia_sdp_neg_was_answer_remote(pjmedia_sdp_neg *neg);
458
459
460 /**
461  * Get the current remote SDP offer or answer. Application can only 
462  * call this function in state PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER or
463  * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, or otherwise there won't be remote 
464  * SDP offer/answer. Calling this  function will not change the state 
465  * of the negotiator.
466  *
467  * @param neg           The SDP negotiator instance.
468  * @param remote        Pointer to receive the current remote offer or
469  *                      answer.
470  *
471  * @return              PJ_SUCCESS if the negotiator currently has
472  *                      remote offer or answer.
473  */
474 PJ_DECL(pj_status_t)
475 pjmedia_sdp_neg_get_neg_remote( pjmedia_sdp_neg *neg,
476                                 const pjmedia_sdp_session **remote);
477
478
479 /**
480  * Get the current local SDP offer or answer. Application can only 
481  * call this function in state PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER or
482  * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, or otherwise there won't be local 
483  * SDP offer/answer. Calling this function will not change the state 
484  * of the negotiator.
485  *
486  * @param neg           The SDP negotiator instance.
487  * @param local         Pointer to receive the current local offer or
488  *                      answer.
489  *
490  * @return              PJ_SUCCESS if the negotiator currently has
491  *                      local offer or answer.
492  */
493 PJ_DECL(pj_status_t) 
494 pjmedia_sdp_neg_get_neg_local( pjmedia_sdp_neg *neg,
495                                const pjmedia_sdp_session **local);
496
497 /**
498  * Modify local session with a new SDP and treat this as a new offer. 
499  * This function can only be called in state PJMEDIA_SDP_NEG_STATE_DONE.
500  * After calling this function, application can send the SDP as offer 
501  * to remote party, using signaling protocol such as SIP.
502  * The negotiator state will move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER,
503  * where it waits for SDP answer from remote.
504  *
505  * @param pool          Pool to allocate memory. The pool's lifetime needs
506  *                      to be valid for the duration of the negotiator.
507  * @param neg           The SDP negotiator instance.
508  * @param local         The new local SDP.
509  *
510  * @return              PJ_SUCCESS on success, or the appropriate
511  *                      error code.
512  */
513 PJ_DECL(pj_status_t) 
514 pjmedia_sdp_neg_modify_local_offer( pj_pool_t *pool,
515                                     pjmedia_sdp_neg *neg,
516                                     const pjmedia_sdp_session *local);
517
518 /**
519  * This function can only be called in PJMEDIA_SDP_NEG_STATE_DONE state.
520  * Application calls this function to retrieve currently active
521  * local SDP, and then send the SDP to remote as an offer. The negotiator
522  * state will then move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, where it waits
523  * for SDP answer from remote. 
524  *
525  * When SDP answer has been received from remote, application must call 
526  * #pjmedia_sdp_neg_set_remote_answer().
527  *
528  * @param pool          Pool to allocate memory. The pool's lifetime needs
529  *                      to be valid for the duration of the negotiator.
530  * @param neg           The SDP negotiator instance.
531  * @param offer         Pointer to receive active local SDP to be
532  *                      offered to remote.
533  *
534  * @return              PJ_SUCCESS if local offer can be created.
535  */
536 PJ_DECL(pj_status_t) 
537 pjmedia_sdp_neg_send_local_offer( pj_pool_t *pool,
538                                   pjmedia_sdp_neg *neg,
539                                   const pjmedia_sdp_session **offer);
540
541 /**
542  * This function can only be called in PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER
543  * state, i.e. after application calls #pjmedia_sdp_neg_send_local_offer()
544  * function. Application calls this function when it receives SDP answer
545  * from remote. After this function is called, the negotiator state will
546  * move to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and application can call the
547  * negotiation function #pjmedia_sdp_neg_negotiate().
548  *
549  * @param pool          Pool to allocate memory. The pool's lifetime needs
550  *                      to be valid for the duration of the negotiator.
551  * @param neg           The SDP negotiator instance.
552  * @param remote        The remote answer.
553  *
554  * @return              PJ_SUCCESS on success.
555  */
556 PJ_DECL(pj_status_t) 
557 pjmedia_sdp_neg_set_remote_answer( pj_pool_t *pool,
558                                    pjmedia_sdp_neg *neg,
559                                    const pjmedia_sdp_session *remote);
560
561
562
563 /**
564  * This function can only be called in PJMEDIA_SDP_NEG_STATE_DONE state. 
565  * Application calls this function when it receives SDP offer from remote.
566  * After this function is called, the negotiator state will move to 
567  * PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER, and application MUST call the
568  * #pjmedia_sdp_neg_set_local_answer() to set local answer before it can
569  * call the negotiation function.
570  *
571  * @param pool          Pool to allocate memory. The pool's lifetime needs
572  *                      to be valid for the duration of the negotiator.
573  * @param neg           The SDP negotiator instance.
574  * @param remote        The remote offer.
575  *
576  * @return              PJ_SUCCESS on success.
577  */
578 PJ_DECL(pj_status_t) 
579 pjmedia_sdp_neg_set_remote_offer( pj_pool_t *pool,
580                                   pjmedia_sdp_neg *neg,
581                                   const pjmedia_sdp_session *remote);
582
583
584
585 /**
586  * This function can only be called in PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER
587  * state, i.e. after application calls #pjmedia_sdp_neg_set_remote_offer()
588  * function. After this function is called, the negotiator state will
589  * move to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and application can call the
590  * negotiation function #pjmedia_sdp_neg_negotiate().
591  *
592  * @param pool          Pool to allocate memory. The pool's lifetime needs
593  *                      to be valid for the duration of the negotiator.
594  * @param neg           The SDP negotiator instance.
595  * @param local         Optional local answer. If negotiator has initial
596  *                      local capability, application can specify NULL on
597  *                      this argument; in this case, the negotiator will
598  *                      create answer by by negotiating remote offer with
599  *                      initial local capability. If negotiator doesn't have
600  *                      initial local capability, application MUST specify
601  *                      local answer here.
602  *
603  * @return              PJ_SUCCESS on success.
604  */
605 PJ_DECL(pj_status_t) 
606 pjmedia_sdp_neg_set_local_answer( pj_pool_t *pool,
607                                   pjmedia_sdp_neg *neg,
608                                   const pjmedia_sdp_session *local);
609
610
611 /**
612  * Call this function when the negotiator is in PJMEDIA_SDP_NEG_STATE_WAIT_NEGO
613  * state to see if it was local who is answering the offer (instead of
614  * remote).
615  *
616  * @param neg           The negotiator.
617  *
618  * @return              PJ_TRUE if it is local is answering an offer, PJ_FALSE
619  *                      if remote has answered local offer.
620  */
621 PJ_DECL(pj_bool_t) pjmedia_sdp_neg_has_local_answer(pjmedia_sdp_neg *neg);
622
623
624 /**
625  * Cancel any pending offer, whether the offer is initiated by local or
626  * remote, and move negotiator state back to previous stable state
627  * (PJMEDIA_SDP_NEG_STATE_DONE). The negotiator must be in
628  * PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER or PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER
629  * state.
630  *
631  * @param neg           The negotiator.
632  *
633  * @return              PJ_SUCCESS or the appropriate error code.
634  */
635 PJ_DECL(pj_status_t) pjmedia_sdp_neg_cancel_offer(pjmedia_sdp_neg *neg);
636
637
638 /**
639  * Negotiate local and remote answer. Before calling this function, the
640  * SDP negotiator must be in PJMEDIA_SDP_NEG_STATE_WAIT_NEGO state.
641  * After calling this function, the negotiator state will move to
642  * PJMEDIA_SDP_NEG_STATE_DONE regardless whether the negotiation has
643  * been successfull or not.
644  *
645  * If the negotiation succeeds (i.e. the return value is PJ_SUCCESS),
646  * the active local and remote SDP will be replaced with the new SDP
647  * from the negotiation process.
648  *
649  * If the negotiation fails, the active local and remote SDP will not
650  * change.
651  *
652  * @param pool          Pool to allocate memory. The pool's lifetime needs
653  *                      to be valid for the duration of the negotiator.
654  * @param neg           The SDP negotiator instance.
655  * @param allow_asym    Should be zero.
656  *
657  * @return              PJ_SUCCESS when there is at least one media
658  *                      is actuve common in both offer and answer, or 
659  *                      failure code when negotiation has failed.
660  */
661 PJ_DECL(pj_status_t) pjmedia_sdp_neg_negotiate( pj_pool_t *pool,
662                                                 pjmedia_sdp_neg *neg,
663                                                 pj_bool_t allow_asym);
664
665
666 /**
667  * Enumeration of customized SDP format matching option flags. See
668  * #pjmedia_sdp_neg_register_fmt_match_cb() for more info.
669  */
670 typedef enum pjmedia_sdp_neg_fmt_match_flag
671 {
672     /**
673      * In generating answer, the SDP fmtp in the answer candidate may need
674      * to be modified by the customized SDP format matching callback to
675      * achieve flexible SDP negotiation, e.g: AMR fmtp 'octet-align' field
676      * can be adjusted with the offer when the codec implementation support
677      * both packetization modes octet-aligned and bandwidth-efficient.
678      */
679     PJMEDIA_SDP_NEG_FMT_MATCH_ALLOW_MODIFY_ANSWER = 1,
680
681 } pjmedia_sdp_neg_fmt_match_flag;
682
683
684 /**
685  * The declaration of customized SDP format matching callback. See
686  * #pjmedia_sdp_neg_register_fmt_match_cb() for more info.
687  *
688  * @param pool          The memory pool.
689  * @param offer         The SDP media offer.
690  * @param o_fmt_idx     Index of the format in the SDP media offer.
691  * @param answer        The SDP media answer.
692  * @param a_fmt_idx     Index of the format in the SDP media answer.
693  * @param option        The format matching option, see
694  *                      #pjmedia_sdp_neg_fmt_match_flag.
695  *
696  * @return              PJ_SUCCESS when the formats in offer and answer match.
697  */
698 typedef pj_status_t (*pjmedia_sdp_neg_fmt_match_cb)(pj_pool_t *pool,
699                                                     pjmedia_sdp_media *offer,
700                                                     unsigned o_fmt_idx,
701                                                     pjmedia_sdp_media *answer,
702                                                     unsigned a_fmt_idx,
703                                                     unsigned option);
704
705
706 /**
707  * Register customized SDP format matching callback function for the specified
708  * format. The customized SDP format matching is needed when the format
709  * identification in a media stream session cannot be simply determined by
710  * encoding name and clock rate, but also involves one or more format specific
711  * parameters, which are specified in SDP fmtp attribute. For example,
712  * an H.264 video stream is also identified by profile, level, and
713  * packetization-mode parameters. As those parameters are format specifics,
714  * the negotiation must be done by the format or codec implementation.
715  *
716  * To unregister the callback of specific format, just call this function with
717  * parameter #cb set to NULL.
718  *
719  * @param fmt_name      The format name, e.g: "H.264", "AMR", "G7221". Note
720  *                      that the string buffer must remain valid until the
721  *                      callback is unregistered.
722  * @param cb            The customized SDP format negotiation callback or
723  *                      NULL to unregister the specified format callback.
724  *
725  * @return              PJ_SUCCESS on success.
726  */
727 PJ_DECL(pj_status_t) pjmedia_sdp_neg_register_fmt_match_cb(
728                                         const pj_str_t *fmt_name,
729                                         pjmedia_sdp_neg_fmt_match_cb cb);
730
731
732 /**
733  * Match format in the SDP media offer and answer. The matching mechanism
734  * will be done by comparing the encoding name and clock rate, and if the
735  * custom format matching callback for the specified format is registered,
736  * see #pjmedia_sdp_neg_register_fmt_match_cb(), it will be called for more
737  * detail verification, e.g: format parameters specified in SDP fmtp.
738  *
739  * @param pool          The memory pool.
740  * @param offer         The SDP media offer.
741  * @param o_fmt_idx     Index of the format in the SDP media offer.
742  * @param answer        The SDP media answer.
743  * @param a_fmt_idx     Index of the format in the SDP media answer.
744  * @param option        The format matching option, see
745  *                      #pjmedia_sdp_neg_fmt_match_flag.
746  *
747  * @return              PJ_SUCCESS when the formats in offer and answer match.
748  */
749 PJ_DECL(pj_status_t) pjmedia_sdp_neg_fmt_match( pj_pool_t *pool,
750                                                 pjmedia_sdp_media *offer,
751                                                 unsigned o_fmt_idx,
752                                                 pjmedia_sdp_media *answer,
753                                                 unsigned a_fmt_idx,
754                                                 unsigned option);
755
756
757 PJ_END_DECL
758
759 /**
760  * @}
761  */
762
763
764 #endif  /* __PJMEDIA_SDP_NEG_H__ */
765