Hold and Unhold

  • Article

This feature is exposed on the IRTCSessionCallControl::Hold and IRTCSessionCallControl::UnHold methods and applies only to voice, video, and T120, PC-PC, or PC-phone calls. The session state must be RTCSS_CONNECTED for the call to be placed on hold. The hold method temporarily frees media resources that are associated with the call so that another incoming call can be answered or another outgoing call can be made.

Placing a Call on Hold

The application calls the IRTCSessionCallControl::Hold method with the cookie for the session. Placing the call on hold stops all media streams associated with the call. The call is placed on hold with no confirmation needed from the party that is placed on hold. The Hold method requires a cookie that the RTC API uses to track the session that is placed on hold. Subsequent calls to IRTCSessionCallControl::UnHold uses a different cookie to identify the session to place off hold. More than one session at a time can be placed on hold.

The IRTCSessionOperationCompleteEvent is fired when the operation associated with the cookie has completed, regardless of whether it was successful. The cookies set in the Hold method can be retrieved by the IRTCSessionOperationCompleteEvent::get_Cookie method. If the attempt to place a call on hold is successful, an IRTCSessionStateChangeEvent is fired specifying that the session state is RTCSS_HOLD.

Placing a Call off Hold

The IRTCSessionCallControl::UnHold method is used to place a call off hold. This method uses a cookie to unhold the call. The IRTCSessionOperationCompleteEvent is fired when the operation associated with the cookie has completed and the status of the attempt to place the call off hold can be obtained from this interface. If the call is successfully placed off hold, an IRTCSessionStateChangeEvent is fired specifying that the session state is RTCSS_CONNECTED.

Note  It is possible for a session to change from RTCSS_HOLD to RTCSS_DISCONNECTED.

The Party Placed on Hold

The application for the party that is placed on hold receives notification via the IRTCMediaEvent interface that the media stream for the call has stopped. The media event type will be RTCMET_STOPPED and the reason will be RTCMER_HOLD, indicating that the media stream stopped because the call was placed on hold. The session state remains in the RTCSS_CONNECTED state while the call is on hold. The third party does not have the option to allow or disallow placing the call on hold. When the call is placed off hold, an IRTCMediaEvent notification is fired to indicate that the media stream has started.