Routing Requests to a Specific Device

Previous versions of the RTC Client API supported routing of session requests to the most available device based on the SIP server configuration. With version 1.3, requests can be routed to a specific device with a specific device ID.

Note that your application can continue to use the routing features of the SIP server (for example, your application can take advantage of server features such as forking depending on what routing features your SIP server supports). However, if your application routes a session request to a specific device, it will override routing behaviors in the SIP server such as forking or routing to the most available device.

When a session is created and a participant is added that is actively logged onto the server from multiple devices, the server decides which device to route the session request to based on the server configuration set by the administrator. In RTC Client API version 1.2, an application could not specify the specific device to route the session request to.

With RTC Client API version 1.3, the device ID is created when the profile is enabled (when the application calls IRTCClientProvisioning::EnableProfile or IRTCClientProvisioning2::EnableProfileEx). The device ID is a case-sensitive string of hexadecimal values.

As in RTC Client API version 1.2, your application can use the IRTCBuddy2::EnumeratePresenceDevices method to enumerate the presence devices. When your application uses the IRTCEnumPresenceDevices interface to enumerate each device, it can call QueryInterface on the IRTCPresenceDevice pointer in order to get the IRTCPresenceDevice2 interface and then use IRTCPresenceDevice2::get_DeviceID to get the device ID of the presence device. Your application can use the other information about the presence device (notes, status, presence property, or presence data) to determine which specific device your application wants to route the session request to.

Note that the device ID is not available when the buddy is offline.

To add a buddy on a specific device as a participant of a session, your application can use the IRTCSession3::AddParticipantEx method. This method enables you to specify the device ID when adding the participant and returns an IRTCParticipant2 interface pointer. The SIP server uses the device ID in the session request and routes it to that particular device. Note that the session request is routed to a specified device only if the SIP server supports routing to a specific device.

The IRTCParticipant2 interface also provides the IRTCParticipant2::get_DeviceID property. This method enables you to get the device ID for the device of the participant in a session.

Note that the device ID is generated by the RTC Client API. Therefore, the receiving application must publish application-specific information in its presence information and the calling application must have the logic to use that application-specific information to select the appropriate device.