Changes between Version 7 and Version 8 of SIP_Redirection


Ignore:
Timestamp:
Nov 27, 2008 12:51:50 PM (15 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • SIP_Redirection

    v7 v8  
    2525 
    2626 {{{ 
    27     void (*on_redirected)(pjsip_inv_session *inv, const pjsip_uri *target, 
    28                           pjsip_redirect_op *cmd, const pjsip_event *e); 
     27    pjsip_redirect_op (*on_redirected)(pjsip_inv_session *inv,  
     28                                       const pjsip_uri *target, 
     29                                       const pjsip_event *e); 
    2930 }}} 
    3031 
    3132Application '''MUST''' implement this callback if it wants the invite session to manage redirection. If this callback is not implemented, the invite session will be disconnected upon receipt of 3xx response. 
    3233 
    33 If this callback is implemented, the default behavior (that is when the callback contains no function body) is to follow the redirection. 
    34  
    35 This callback is called when the invite session is being redirected to a new target. If there are multiple targets, then the callback will be called multiple times, once for each target. This function is called on these events: 
     34This callback is called when the invite session is being redirected to a new target. If there are multiple targets, then the callback will be called multiple times, once for each target. This callback will be called on these events: 
    3635 - a 3xx response containing usable Contact header(s) is received 
    3736 - a 4xx or 5xx response to subsequent INVITE request is received, and the invite session has at least one more valid target to try. This happens for example when multiple Contact headers (alternate targets) are received for the original INVITE, and 4xx/5xx response is received for the second INVITE (to the first alternate target). The callback then will be called before the invite session tries to send the third INVITE to the second alternate target. 
    … …  
    4544   The current target URI to which the INVITE will be sent to. 
    4645 
    47  ''cmd'':: 
    48    Action to be performed. The default value is to accept the redirection. Application can change this to one of the following values: 
     46 ''e'':: 
     47   The event that triggers this callback to be called. This could be of type {{{PJSIP_EVENT_TSX_STATE}}} containing receipt of 3xx, 4xx, or 5xx response, or any other type depending on what is passed to {{{pjsip_inv_process_redirect()}}} below, or of type {{{PJSIP_EVENT_USER}}} if this callback is called by {{{pjsip_inv_process_redirect()}}} below and the event argument to that function is NULL, or NULL. 
     48 
     49The return value specifies the action to be performed, and it must be set to one of the following: 
    4950     - ''PJSIP_REDIRECT_ACCEPT'': immediately accept the redirection (default value upon callback entry). The session will immediately resend INVITE request to the target upon return of this callback. 
    5051     - ''PJSIP_REDIRECT_REJECT'': immediately reject this target. The session will continue retrying with next target if present (and it will call this callback again for the next target), or immediately disconnect the call if there is no more target to try (notifying the ''on_state_changed()'' callback as usual). 
    5152     - ''PJSIP_REDIRECT_STOP'': stop the whole redirection process and immediately disconnect the call, regardless on whether there is other target to try or not (notifying the ''on_state_changed()'' callback as usual). 
    5253     - ''PJSIP_REDIRECT_PENDING'': set to this value if no decision can be made immediately (for example to request user approval). Application then MUST call ''pjsip_inv_process_redirect()'' (see below) to either accept or reject the redirection upon getting user decision. 
    53  
    54  ''e'':: 
    55    The event that triggers this callback to be called. This could be of type {{{PJSIP_EVENT_TSX_STATE}}} containing receipt of 3xx, 4xx, or 5xx response, or any other type depending on what is passed to {{{pjsip_inv_process_redirect()}}} below, or of type {{{PJSIP_EVENT_USER}}} if this callback is called by {{{pjsip_inv_process_redirect()}}} below and the event argument to that function is NULL, or NULL. 
    5654 
    5755 
    … …  
    7270==== Accept Redirection to This Target ==== 
    7371 
    74 Set the ''cmd'' argument of the callback to ''PJSIP_REDIRECT_ACCEPT'' to accept the redirection to this target. And INVITE session will be sent immediately to the target. 
     72Return ''PJSIP_REDIRECT_ACCEPT'' from the callback to accept the redirection to this target. And INVITE session will be sent immediately to the target. 
    7573 
    7674==== Reject Redirection to This Target ==== 
    7775 
    78 Set the ''cmd'' argument of the callback to ''PJSIP_REDIRECT_REJECT'' to reject the redirection to this target. If there is another target to try, then the callback will be called again with this next target, otherwise the invite session will be disconnected immediately.  
     76Return ''PJSIP_REDIRECT_REJECT'' from the callback to reject the redirection to this target. If there is another target to try, then the callback will be called again with this next target, otherwise the invite session will be disconnected immediately.  
    7977 
    8078 
    8179==== Stop Redirection ==== 
    8280 
    83 Set the ''cmd'' argument of the callback to ''PJSIP_REDIRECT_STOP'' to stop the redirection process and disconnect the call immediately, regardless of whether there are more targets to try. 
     81Return ''PJSIP_REDIRECT_STOP'' from the callback to stop the redirection process and disconnect the call immediately, regardless of whether there are more targets to try. 
    8482 
    8583==== Defer the Decision ==== 
    8684 
    87 Set the ''cmd'' argument of the callback to ''PJSIP_REDIRECT_PENDING'' to tell the invite session that a decision cannot be made that this time (for example to ask for user approval), and the application will notify the invite session about the decision later. 
     85Return ''PJSIP_REDIRECT_PENDING'' from the callback to tell the invite session that a decision cannot be made that this time (for example to ask for user approval), and the application will notify the invite session about the decision later. 
    8886 
    89 Once the application decides what to do with the redirection, it '''MUST''' call {{{pjsip_inv_process_redirect()}}} function to notify the session about this. It may accept or reject the target, or stop the redirection altogether by setting the appropriate value to the ''cmd'' argument. It must not set ''PJSIP_REDIRECT_PENDING'' to this argument. 
     87Once the application gets the user approval (or disapproval), it '''MUST''' call {{{pjsip_inv_process_redirect()}}} function to notify the session about the decision. It may accept or reject the target, or stop the redirection altogether by setting the appropriate value to the ''cmd'' argument. It must not set ''PJSIP_REDIRECT_PENDING'' to this argument. 
    9088 
    9189Failure to call {{{pjsip_inv_process_redirect()}}} will cause the invite session to be kept alive indefinitely until the library is shutdown. 
    … …  
    10098 
    10199 {{{ 
    102 void (*on_call_redirected)(pjsua_call_id call_id, const pjsip_uri *target, 
    103                            pjsip_redirect_op *cmd, const pjsip_event *e); 
     100pjsip_redirect_op (*on_call_redirected)(pjsua_call_id call_id,  
     101                                        const pjsip_uri *target, 
     102                                        const pjsip_event *e); 
    104103 
    105104PJ_DECL(pj_status_t) pjsua_call_process_redirect(pjsua_call_id call_id,