← Back to branch summary

~ubuntu-branches/ubuntu/vivid/sflphone/vivid

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/sdp_neg.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2013-06-30 11:40:56 UTC
  • mfrom: (4.1.18 saucy-proposed)
  • Revision ID: package-import@ubuntu.com-20130630114056-0np50jkyqo6vnmii
Tags: 1.2.3-2
* changeset_r92d62cfc54732bbbcfff2b1d36c096b120b981a5.diff 
  - fixes automatic endian detection 
* Update Vcs: fixes vcs-field-not-canonical

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/sdp_neg.h
 
1
/* $Id: sdp_neg.h 3664 2011-07-19 03:42:28Z nanang $ */
 
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__ */