Changes between Version 5 and Version 6 of SIP_Redirection


Ignore:
Timestamp:
Nov 27, 2008 12:20:30 PM (11 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • SIP_Redirection

    v5 v6  
    88 
    99The redirected call handling is implemented by ticket #10. The objective statements of this work are: 
    10  - must be implemented in PJSIP level rather than PJSUA-LIB level 
     10 - must be implemented in PJSIP level rather than PJSUA-LIB level, to allow the usage on non-PJSUA-LIB based applications. 
    1111 - must allow application to accept or reject the redirection request on a per-target basis (by means of callback) 
    1212 - must allow application to defer the decision to accept or reject the redirection request (for example, to ask for user confirmation to accept or reject the target) 
     
    2929If this callback is implemented, the default behavior (that is when the callback contains no function body) is to follow the redirection. 
    3030 
    31 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 for each target. This function is called on these events: 
     31This 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: 
    3232 - a 3xx response containing usable Contact header(s) is received 
    3333 - 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. 
     
    4242 
    4343 ''cmd'':: 
    44    Tells the invite session about what to do with this redirection. The default value is to accept the redirection. Application can change this to the following valid values: 
    45      - ''PJSIP_REDIRECT_ACCEPT'': immediately accept the redirection (default value). The session will immediately resend INVITE request to the target upon return of this callback. 
     44   Action to be performed. The default value is to accept the redirection. Application can change this to one of the following values: 
     45     - ''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. 
    4646     - ''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). 
    47      - ''PJSIP_REDIRECT_STOP'': stop the whole redirection process and immediately disconnect the call, regardless on whether there is other target to try or not.  
    48      - ''PJSIP_REDIRECT_PENDING'': set to this value if no decision can be made immediately (for example to request confirmation from user). Application then MUST call ''pjsip_inv_process_redirect()'' (see below) to either accept or reject the redirection upon getting user decision. 
     47     - ''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). 
     48     - ''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. 
    4949 
    5050 ''e'':: 
     
    7272==== Reject Redirection to This Target ==== 
    7373 
    74 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. 
     74Set 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.  
     75 
    7576 
    7677==== Stop Redirection ==== 
     
    8687Failure to call {{{pjsip_inv_process_redirect()}}} will cause the invite session to be kept alive indefinitely until the library is shutdown. 
    8788 
     89When the {{{pjsip_inv_process_redirect()}}} function is called for the next target in the context of this function (that is when this function is called with reject command and next target is selected, hence the callback is called), the event (''e'') argument passed to this function will be passed down to the callback. And similarly when the disconnect callback is called. If NULL is given to the event argument of this function, this function will create a {{{PJSIP_EVENT_USER}}} event with NULL values, to be passed to the callbacks. 
     90 
     91Because of this, application MUST be prepared to handle these type of events in both the {{{on_redirected()}}} and {{{on_state_changed()}}} callbacks. Traditionally only {{{PJSIP_EVENT_TSX_STATE}}} event is passed to {{{on_state_changed()}}} callback. 
    8892 
    8993=== PJSUA-LIB ===