![(please configure the [header_logo] section in trac.ini)](/repos/chrome/site/pj.jpg)
Changeset 140 for pjproject/trunk/pjmedia/include/pjmedia/sdp_neg.h
- Timestamp:
- Feb 7, 2006 12:34:58 PM (18 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
pjproject/trunk/pjmedia/include/pjmedia/sdp_neg.h
r129 r140 40 40 41 41 /** 42 * This enumeration describes SDP negotiation state. 42 * This enumeration describes SDP negotiation state. The negotiator state 43 * is illustrated in the following diagram. 44 * 45 * <pre> 46 * reinit_local_offer() 47 * modify_local_offer() 48 * create_w_local_offer() +-------------+ send_local_offer() 49 * ----------------------->| LOCAL_OFFER |<----------------------- 50 * | +-------------+ | 51 * | | | 52 * | set_remote_answer() | | 53 * | V | 54 * +--+---+ +-----------+ negotiate() +------+ 55 * | NULL | | WAIT_NEGO |-------------------->| DONE | 56 * +------+ +-----------+ +------+ 57 * | A | 58 * | set_local_answer() | | 59 * | | | 60 * | +--------------+ set_remote_offer() | 61 * ----------------------->| REMOTE_OFFER |<---------------------- 62 * create_w_remote_offer() +--------------+ 63 * 64 * </pre> 43 65 */ 44 66 enum pjmedia_sdp_neg_state … … 51 73 /** 52 74 * This state occurs when SDP negotiator has sent our offer to remote and 53 * it is waiting for answer. 75 * it is waiting for answer. 54 76 */ 55 77 PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, 78 79 /** 80 * This state occurs when SDP negotiator has received offer from remote 81 * and currently waiting for local answer. 82 */ 83 PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER, 56 84 57 85 /** 58 86 * This state occurs when an offer (either local or remote) has been 59 87 * provided with answer. The SDP negotiator is ready to negotiate both 60 * session descriptors. 88 * session descriptors. Application can call #pjmedia_sdp_neg_negotiate() 89 * immediately to begin negotiation process. 61 90 */ 62 91 PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, … … 69 98 }; 70 99 71 /* Negotiator state:72 *73 * reinit_local_offer()74 * modify_local_offer()75 * create_w_local_offer() +-------------+ tx_local_offer()76 * /------------------------->| LOCAL_OFFER |<----------------------\77 * | +-------------+ |78 * | | |79 * | rx_remote_answer() | |80 * | V |81 * +--+---+ +-----------+ negotiate() +------+82 * + NULL |------------------------>| WAIT_NEGO |-------------------->| DONE |83 * +------+ create_w_remote_offer() +-----------+ +------+84 * A |85 * | rx_remote_offer() |86 * \-----------------------------/87 */88 89 100 /** 90 101 * Create the SDP negotiator with local offer. The SDP negotiator then 91 102 * will move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER state, where it waits 92 103 * until it receives answer from remote. When SDP answer from remote is 93 * received, application should call #pjmedia_sdp_neg_ rx_remote_answer().104 * received, application should call #pjmedia_sdp_neg_set_remote_answer(). 94 105 * 95 106 * After calling this function, application should send the local SDP offer 96 * to remote party and wait for SDP answer. 107 * to remote party using higher layer signaling protocol (e.g. SIP) and 108 * wait for SDP answer. 109 * 110 * @param pool Pool to allocate memory. The pool's lifetime needs 111 * to be valid for the duration of the negotiator. 112 * @param local The initial local capability. 113 * @param p_neg Pointer to receive the negotiator instance. 114 * 115 * @return PJ_SUCCESS on success, or the appropriate error 116 * code. 97 117 */ 98 118 PJ_DECL(pj_status_t) … … 102 122 103 123 /** 104 * Initialize the SDP negotiator with both local and remote offer. 105 * Application normally calls this function when it receives initial offer 106 * from remote. Application must also provide initial local offer when 107 * calling this function. After this function is called, the SDP negotiator 108 * state will move to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and the negotiation 109 * function can be called. 124 * Initialize the SDP negotiator with remote offer, and optionally 125 * specify the initial local capability, if known. Application normally 126 * calls this function when it receives initial offer 127 * from remote. 128 * 129 * If local media capability is specified, this capability will be set as 130 * initial local capability of the negotiator, and after this function is 131 * called, the SDP negotiator state will move to state 132 * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and the negotiation function can be 133 * called. 134 * 135 * If local SDP is not specified, the negotiator will not have initial local 136 * capability, and after this function is called the negotiator state will 137 * move to PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER state. Application MUST supply 138 * local answer later with #pjmedia_sdp_neg_set_local_answer(), before 139 * calling the negotiation function. 140 * 141 * @param pool Pool to allocate memory. The pool's lifetime needs 142 * to be valid for the duration of the negotiator. 143 * @param initial Optional initial local capability. 144 * @param remote The remote offer. 145 * @param p_neg Pointer to receive the negotiator instance. 146 * 147 * @return PJ_SUCCESS on success, or the appropriate error 148 * code. 110 149 */ 111 150 PJ_DECL(pj_status_t) 112 151 pjmedia_sdp_neg_create_w_remote_offer(pj_pool_t *pool, 113 const pjmedia_sdp_session * local,152 const pjmedia_sdp_session *initial, 114 153 const pjmedia_sdp_session *remote, 115 154 pjmedia_sdp_neg **p_neg); … … 117 156 /** 118 157 * Get SDP negotiator state. 158 * 159 * @param neg The SDP negotiator instance. 160 * 161 * @return The negotiator state. 119 162 */ 120 163 PJ_DECL(pjmedia_sdp_neg_state) … … 126 169 * active SDPs. Calling this function will not change the state of the 127 170 * negotiator. 128 */ 129 PJ_DECL(pj_status_t) 130 pjmedia_sdp_neg_get_local( pjmedia_sdp_neg *neg, 131 const pjmedia_sdp_session **local); 171 * 172 * @param neg The SDP negotiator instance. 173 * @param local Pointer to receive the local active SDP. 174 * 175 * @return PJ_SUCCESS if local active SDP is present. 176 */ 177 PJ_DECL(pj_status_t) 178 pjmedia_sdp_neg_get_active_local( pjmedia_sdp_neg *neg, 179 const pjmedia_sdp_session **local); 132 180 133 181 /** … … 136 184 * active SDPs. Calling this function will not change the state of the 137 185 * negotiator. 138 */ 139 PJ_DECL(pj_status_t) 140 pjmedia_sdp_neg_get_remote( pjmedia_sdp_neg *neg, 141 const pjmedia_sdp_session **remote); 142 186 * 187 * @param neg The SDP negotiator instance. 188 * @param remote Pointer to receive the remote active SDP. 189 * 190 * @return PJ_SUCCESS if remote active SDP is present. 191 */ 192 PJ_DECL(pj_status_t) 193 pjmedia_sdp_neg_get_active_remote( pjmedia_sdp_neg *neg, 194 const pjmedia_sdp_session **remote); 195 196 /** 197 * Get the current remote SDP offer or answer. Application can only 198 * call this function in state PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER or 199 * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, or otherwise there won't be remote 200 * SDP offer/answer. Calling this function will not change the state 201 * of the negotiator. 202 * 203 * @param neg The SDP negotiator instance. 204 * @param remote Pointer to receive the current remote offer or 205 * answer. 206 * 207 * @return PJ_SUCCESS if the negotiator currently has 208 * remote offer or answer. 209 */ 210 PJ_DECL(pj_status_t) 211 pjmedia_sdp_neg_get_neg_remote( pjmedia_sdp_neg *neg, 212 const pjmedia_sdp_session **remote); 213 214 215 /** 216 * Get the current local SDP offer or answer. Application can only 217 * call this function in state PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER or 218 * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, or otherwise there won't be local 219 * SDP offer/answer. Calling this function will not change the state 220 * of the negotiator. 221 * 222 * @param neg The SDP negotiator instance. 223 * @param local Pointer to receive the current local offer or 224 * answer. 225 * 226 * @return PJ_SUCCESS if the negotiator currently has 227 * local offer or answer. 228 */ 229 PJ_DECL(pj_status_t) 230 pjmedia_sdp_neg_get_neg_local( pjmedia_sdp_neg *neg, 231 const pjmedia_sdp_session **local); 143 232 144 233 /** … … 148 237 * The negotiator state will move to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, 149 238 * where it waits for SDP answer from remote. 239 * 240 * @param pool Pool to allocate memory. The pool's lifetime needs 241 * to be valid for the duration of the negotiator. 242 * @param neg The SDP negotiator instance. 243 * @param local The new local SDP. 244 * 245 * @return PJ_SUCCESS on success, or the appropriate 246 * error code. 150 247 */ 151 248 PJ_DECL(pj_status_t) … … 158 255 * SDP negotiator must be in PJMEDIA_SDP_NEG_STATE_WAIT_NEGO state. 159 256 * After calling this function, the negotiator state will move to 160 * PJMEDIA_SDP_NEG_STATE_DONE. 257 * PJMEDIA_SDP_NEG_STATE_DONE regardless whether the negotiation has 258 * been successfull or not. 259 * 260 * If the negotiation succeeds (i.e. the return value is PJ_SUCCESS), 261 * the active local and remote SDP will be replaced with the new SDP 262 * from the negotiation process. 263 * 264 * If the negotiation fails, the active local and remote SDP will not 265 * change. 266 * 267 * @param pool Pool to allocate memory. The pool's lifetime needs 268 * to be valid for the duration of the negotiator. 269 * @param neg The SDP negotiator instance. 270 * @param allow_asym Should be zero. 271 * 272 * @return PJ_SUCCESS when there is at least one media 273 * is actuve common in both offer and answer, or 274 * failure code when negotiation has failed. 161 275 */ 162 276 PJ_DECL(pj_status_t) pjmedia_sdp_neg_negotiate( pj_pool_t *pool, … … 170 284 * local SDP to be sent to remote. The negotiator state will then move 171 285 * to PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER, where it waits for SDP answer 172 * from remote. 173 */ 174 PJ_DECL(pj_status_t) 175 pjmedia_sdp_neg_tx_local_offer( pj_pool_t *pool, 176 pjmedia_sdp_neg *neg, 177 const pjmedia_sdp_session **offer); 286 * from remote. When SDP answer has been received from remote, application 287 * must call #pjmedia_sdp_neg_set_remote_answer(). 288 * 289 * @param pool Pool to allocate memory. The pool's lifetime needs 290 * to be valid for the duration of the negotiator. 291 * @param neg The SDP negotiator instance. 292 * @param offer Pointer to receive active local SDP to be 293 * offered to remote. 294 * 295 * @return PJ_SUCCESS if local offer can be created. 296 */ 297 PJ_DECL(pj_status_t) 298 pjmedia_sdp_neg_send_local_offer( pj_pool_t *pool, 299 pjmedia_sdp_neg *neg, 300 const pjmedia_sdp_session **offer); 301 302 /** 303 * This function can only be called in PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER 304 * state, i.e. after application calls #pjmedia_sdp_neg_send_local_offer() 305 * function. Application calls this function when it receives SDP answer 306 * from remote. After this function is called, the negotiator state will 307 * move to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and application can call the 308 * negotiation function #pjmedia_sdp_neg_negotiate(). 309 * 310 * @param pool Pool to allocate memory. The pool's lifetime needs 311 * to be valid for the duration of the negotiator. 312 * @param neg The SDP negotiator instance. 313 * @param remote The remote answer. 314 * 315 * @return PJ_SUCCESS on success. 316 */ 317 PJ_DECL(pj_status_t) 318 pjmedia_sdp_neg_set_remote_answer( pj_pool_t *pool, 319 pjmedia_sdp_neg *neg, 320 const pjmedia_sdp_session *remote); 321 322 178 323 179 324 /** … … 181 326 * Application calls this function when it receives SDP offer from remote. 182 327 * After this function is called, the negotiator state will move to 183 * PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and application can call the 184 * negotiation function #pjmedia_sdp_neg_negotiate(). 185 */ 186 PJ_DECL(pj_status_t) 187 pjmedia_sdp_neg_rx_remote_offer( pj_pool_t *pool, 188 pjmedia_sdp_neg *neg, 189 const pjmedia_sdp_session *remote); 190 191 192 /** 193 * This function can only be called in PJMEDIA_SDP_NEG_STATE_LOCAL_OFFER 194 * state. Application calls this function when it receives SDP answer 195 * from remote. After this function is called, the negotiator state will 328 * PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER, and application MUST call the 329 * #pjmedia_sdp_neg_set_local_answer() to set local answer before it can 330 * call the negotiation function. 331 * 332 * @param pool Pool to allocate memory. The pool's lifetime needs 333 * to be valid for the duration of the negotiator. 334 * @param neg The SDP negotiator instance. 335 * @param remote The remote offer. 336 * 337 * @return PJ_SUCCESS on success. 338 */ 339 PJ_DECL(pj_status_t) 340 pjmedia_sdp_neg_set_remote_offer( pj_pool_t *pool, 341 pjmedia_sdp_neg *neg, 342 const pjmedia_sdp_session *remote); 343 344 345 346 /** 347 * This function can only be called in PJMEDIA_SDP_NEG_STATE_REMOTE_OFFER 348 * state, i.e. after application calls #pjmedia_sdp_neg_set_remote_offer() 349 * function. After this function is called, the negotiator state will 196 350 * move to PJMEDIA_SDP_NEG_STATE_WAIT_NEGO, and application can call the 197 351 * negotiation function #pjmedia_sdp_neg_negotiate(). 198 */ 199 PJ_DECL(pj_status_t) 200 pjmedia_sdp_neg_rx_remote_answer( pj_pool_t *pool, 352 * 353 * @param pool Pool to allocate memory. The pool's lifetime needs 354 * to be valid for the duration of the negotiator. 355 * @param neg The SDP negotiator instance. 356 * @param local Optional local answer. If negotiator has initial 357 * local capability, application can specify NULL on 358 * this argument; in this case, the negotiator will 359 * create answer by by negotiating remote offer with 360 * initial local capability. If negotiator doesn't have 361 * initial local capability, application MUST specify 362 * local answer here. 363 * 364 * @return PJ_SUCCESS on success. 365 */ 366 PJ_DECL(pj_status_t) 367 pjmedia_sdp_neg_set_local_answer( pj_pool_t *pool, 201 368 pjmedia_sdp_neg *neg, 202 const pjmedia_sdp_session *remote); 369 const pjmedia_sdp_session *local); 370 203 371 204 372
Note: See TracChangeset
for help on using the changeset viewer.
