Dialog Management Layer

A dialog represents a persistent peer-to-peer relationship between two user agents. A dialog facilitates the sequencing of messages between the user agents and the proper routing of requests between the user agents. The dialog represents a context in which to interpret SIP messages. A dialog is uniquely identified by a dialog id, which is a combination of the Call-ID, From, and To tags.

Dialog use is optional. You can create dialogs using INVITE and SUBSCRIBE as methods. A response to an INVITE in the 101–299 range combined with a To tag creates a dialog. A response to a SUBSCRIBE in the 200–299 range or a NOTIFY request creates a dialog. Provisional responses create dialogs that are marked as EARLY dialogs. Final responses in the 200–299 range create dialogs that are marked as CONFIRMED dialogs. An EARLY dialog becomes a confirmed dialog when the stack receives a response in the 200–299 range. If the application registers a callback function with the stack to send notification when a dialog changes state, the stack invokes that function.

An application can perform dialog management internally, or delegate dialog management to the stack. If the stack manages dialogs, the stack automatically creates and maintains dialogs. The stack also delivers any dialogs, matching any incoming messages to the application. If the stack is not managing dialogs, there is no dialog-related interaction between the application and the stack.

UAC Dialog Creation

For clients, if the stack is configured to maintain dialogs, the stack creates a dialog for an incoming response to a dialog creating request. Dialog creating requests are either INVITE or SUBSCRIBE. For SUBSCRIBE requests, a corresponding NOTIFY request also creates a dialog. The stack can create multiple dialogs for a single request if the application specifies multiple dialogs by using the sip_sendmsg() function.

For servers, if the stack is configured to maintain dialogs, the stack creates a dialog when the application sends a response to the dialog creating request. The stack also creates a dialog when it sends a NOTIFY request in response to a SUBSCRIBE request.

UAS Dialog Creation

When the stack receives a dialog creating request, it creates a partial dialog by using the request. The stack sends the partial dialog to the application along with the request. The stack completes the dialog when the application sends a response. Because the stack does not insert the partial dialog into a hash table, the stack does not return partial dialogs as results of a lookup. The stack starts a timer when it creates the partial dialog. The timer's duration is set to the duration of an INVITE transaction timeout. If the UAS does not respond during this time interval, the stack deletes the partial dialog. If the application registers a callback function with the stack for dialog deletion notifications, the stack invokes the callback function before deleting the partial dialog. The stack also deletes the partial dialog if the response is outside the 100–299 range.

Dialog Caching

For an incoming message, the stack sends any existing dialog, along with the message to the application. When the application's receive function returns, the stack decrements the reference count to the dialog. If the dialog's reference count is zero after this decrement, the stack destroys the dialog if the dialog is in a terminated state. If the application needs to use the dialog in the future, it must hold a reference to the dialog by using the sip_hold_dialog() function to prevent the stack from destroying the dialog After using the dialog the application must release the reference by using the sip_release_dialog() function.

Dialog Termination, Deletion, and Notification

When the stack processes a SIP message, the processing can result in the termination of the dialog. A dialog marked as EARLY terminates if the final response is not in the 200–299 range, or if no response arrives. The termination mechanism for confirmed dialogs are method specific. The BYE method terminates an INVITE dialog and the session that is associated with it. An application can explicitly delete a dialog by using the sip_delete_dialog() function.

When the stack terminates a dialog, it notifies the application if the application has registered a callback function with the stack for this purpose.