IRTCSession2::put_PreferredSecurityLevel

The put_PreferredSecurityLevel method sets the encryption for a specified media type. This method sets the security level retrieved in IRTCSession2::get_PreferredSecurityLevel.

HRESULT put_PreferredSecurityLevel(RTC_SECURITY_TYPEenSecurityType,
RTC_SECURITY_LEVELenSecurityLevel);

Parameters

  • enSecurityType
    [in] An RTC_SECURITY_TYPE enumeration specifying the media type.
  • enSecurityLevel
    [in] An RTC_SECURITY_LEVEL enumeration specifying the level of encryption for the specified media type.

Return Values

RTC methods may return an RTC_E_ constant.

Value Meaning
RTC_E_INVALID_SESSION_STATE The session is not in the incoming or idle state.
RTC_E_INVALID_SESSION_TYPE The session type is not PC-PC or the media is not enabled.
E_INVALIDARG The enSecurityLevel or enSecurityType parameter is not in the valid range.

Remarks

Encryption for data collaboration (RTCMT_T120_SENDRECV) sessions requires Windows XP SP1 or greater.

This method gives the application the flexibility to determine what security levels should be applied on a per-session basis. The security levels set by this method affect only the session that the method is called on. For example, the application may want to look at the URI of an incoming session to determine the required security level. Then if the application determines that the incoming session requires audio/video encryption, it calls the put_PreferredSecurityLevel method and specifies RTCSECT_AUDIO_VIDEO_MEDIA_ENCRYPTION and RTCSECL_REQUIRED for the enSecurityType and enSecurityLevel parameters before accepting the incoming session.

This method can be called for sessions that are in the RTCSS_IDLE, RTCSS_INCOMING, or RTCSS_CONNECTED state as follows:

  • If the session is in the RTCSS_IDLE state, the application can set the security level for this session before adding a participant with the IRTCSession::AddParticipant method.
  • If the session is in the RTCSS_INCOMING state, the application can call put_PreferredSecurityLevel before accepting the incoming session.
  • If the session is in the RTCSS_CONNECTED state, a call to put_PreferredSecurityLevel will not affect a security type already in use. However, the new security settings will apply to security types that are added to the session (for example, by calling IRTCSession::AddStream) after the call to put_PreferredSecurityLevel. If put_PreferredSecurityLevel is called with security levels that are already active in a session, the call will fail. For example, if a session is in the RTCSS_CONNECTED state with active audio and video streams and the application calls the put_PreferredSecurityLevel method specifying the RTCSECT_AUDIO_VIDEO_MEDIA_ENCRYPTION security type, the call to put_PreferredSecurityLevel will fail.
  • If the application wants to change security levels for a security type that is currently active in the session, the application must perform the following steps:
  1. Stop the media stream.
  2. Call the put_PreferredSecurityLevel method with the required security type and security level.
  3. Restart the media stream.

For a session to be successfully established or for a new media stream type to be successfully added in a connected session, the security levels of the local party must be compatible with the security levels of the remote party. For example, if the local party sends a session invite that requires audio/video encryption to the remote party and the remote does not support audio/video encryption, a session cannot be established.

When a Reinvite fails to add a new stream to an existing session because of incompatible security levels, the session will continue with the same setting as before the Reinvite. For example, if an existing session with audio/video streams failed to add a T120 stream to the session due to incompatible security levels, the session will continue with the audio/video streams active as before.

If the application attempts to lower the security setting to RTCSECL_UNSUPPORTED for an incoming request that has RTCSECL_REQUIRED specified, this method will fail.

Requirements

Redistributable: Requires Rtcdll.dll on Windows 2000, Windows XP, and Windows Server 2003.
Header: Declared in Rtccore.h.
Library: Included as a resource in Rtcdll.dll.
GUID: IID_IRTCSession2 is defined as 17D7CDFC-B007-484c-99D2-86A8A820991D.

See Also

IRTCSession2, RTC_SECURITY_LEVEL, RTC_SECURITY_TYPE, Security, Set the Security Level for the Session Object