SIP
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/28/2008
Session Initiation Protocol (SIP) is a signaling protocol used for establishing sessions in an IP network. A session can be a simple two-way telephone call or a collaborative multimedia conference session.
SIP is a request-response protocol that closely resembles two other Internet protocols: HTTP and SMTP. Using SIP, telephony becomes another Web application and integrates easily into other Internet services.
The primary benefits of SIP are as follows:
- Ability to create and manage any type of session
- Ability to separate physical devices, such as telephones, from users, and the service-logic from centralized control
The abstraction of service from physical devices that SIP provides allows features such as presence (subscriptions and notifications) and mobility to be possible.
After SIP establishes a connection, the RTC Client API uses the Real-time Transport Protocol (RTP) to transfer media information, like voice. For more information about RTP, see RTP/RTCP.
SIP is described in Internet Engineering Task Force (IETF) RFC 3261. You can read this RFC at this Internet Engineering Task Force Web site.
SIP Headers
A SIP message can contain a SIP header that carries additional information with the message. Specific types of SIP headers are associated with specific types of SIP transactions.
Retrieving SIP Headers
RTC exposes SIP headers to applications so that applications can retrieve specific types of headers from a SIP message.** When an event occurs, an application can call the IRTCSIPEvent::GetSIPMessage method to retrieve a SIP message in the form of IRTCSIPMessage. Methods such as IRTCSIPMessage::GetFirstHeader and IRTCSIPMessage::GetHeader can be used to retrieve headers.**
The following list shows several events that implement the IRTCSIPEvent interface.
| Interface | Description |
|---|---|
Retrieves information about an event of type RTCE_INFO. This type of event concerns an incoming SIP INFO message. |
|
Retrieves information about an event of type RTCE_REGISTRATION_STATE_CHANGE. This type of event is triggered when a registration changes state. |
|
Retrieves information about an event of type RTCE_REINVITE. |
|
Retrieves information for an event of type RTCE_SESSION_OPERATION_COMPLETE. |
|
Retrieves information about an event of RTCE_SESSION_REFERRED. This type of event occurs when a session is transferred (referred) or a referred session is accepted. |
|
Retrieves information about an event of type RTCE_SESSION_STATE_CHANGE. This type of event is triggered when a session changes state. |
|
Represents the RTC Subscription State Change Event object. This object is a notification event concerning the status of a SUBSCRIBE transaction. It is completely analogous to IRTCSessionStateChangeEvent. |
|
Represents the RTC Subscription Notification Event object. This object is sent after receiving an incoming SIP NOTIFY message, which corresponds to a custom subscription (IRTCSubscription). |
Adding SIP Headers
In addition to receiving incoming SIP messages and retrieving specific types of headers, an application can also add specific types of headers to outgoing SIP messages.
"Allow Events" Header
An application can add the "Allow Events" header to a SIP message by using RTC. The application can add the header by using of the following features:
- The customizable header feature
- The Invite Created Subscription feature
Subtle differences exist in the ways in which RTC handles incoming NOTIFY messages from servers. An application must determine which way to add the "Allow Events" header that will meet their specific needs.**
Customizable Header Feature
Applications can insert an "Allow Events" header into subsequent outgoing messages by calling the IRTCSIPObject::SetAdditionalHeaderValues method until the application resets the additional headers by calling the method a final time, passing in NULL. To call this method, you need an interface pointer to IRTCSIPObject. To get an interface pointer to IRTCSIPObject, an application can use either the IRTCSession or IRTCSubscription interface to call QueryInterface for IRTCSIPObject. If IRTCSIPObject is in an RTC session, the additional "Allow Events" header will be added to every outgoing message on that session until the application resets it.
Notice that IRTCSIPObject is for advanced users. RTC will not perform any validation on the content. If the application passes in invalid data, it can affect existing VoIP scenarios. Applications should not override essential SIP headers that RTC already provides, such as the "Call Id", "Seq", "To", "From", or "Required" headers. Additionally, IRTCSIPObject is not intended to be used in situations where the header needs to be changed based on responses from the server. It is only for static headers that are attached to all transactions or responses that are associated with a particular dialog, such as for "Call Info" in the Shared Line Appearance scenarios.**
Invite Created Subscription
An application can insert an "Allow Events" header into INVITE-related SIP messages that are leaving the RTC stack by calling IRTCClientSubscriber2::AllowDialogNotifications, a method which is defined in rtccore.idl and provides one [in] BSTR parameter. Calling this method can enable the Invite Created Subscription feature for specific types of SIP server implementations.
When RTC receives the corresponding incoming NOTIFY messages, RTC encapsulates the message in the form of IRTCSessionNotificationEvent, which is also defined in rtccore.idl. Then, it notifies the application about the incoming NOTIFY message. The application can act upon this event, if it is necessary.
If you want to add the "Allow Events" header to a SIP message, we recommend doing this by using the Invite Created Subscription feature.