IRTCSession2::PreferredSecurityLevel

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

This method sets or gets the preferred encryption level for the media type for this session. This method gives the application the flexibility to determine what security levels should be applied on a per-session basis.

The application can call this method for a session that is in the RTCSS_IDLE, RTCSS_INCOMING, or RTCSS_CONNECTED state.

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

Syntax

HRESULT put_PreferredSecurityLevel(
  RTC_SECURITY_TYPE enSecurityType,
  RTC_SECURITY_LEVEL enSecurityLevel
);
HRESULT get_PreferredSecurityLevel(
  RTC_SECURITY_TYPE enSecurityType,
  RTC_SECURITY_LEVEL* penSecurityLevel
);

Parameters

• enSecurityType
  [in] An RTC_SECURITY_TYPE enumeration value specifying the media type.

• enSecurityLevel, penSecurityLevel
  [in, out] Pointer to an RTC_SECURITY_LEVEL enumeration value specifying the security level for the specified media type.

  The security level is set as a result of negotiations between the participants in the session.

Return Value

This method can return an RTC_E_ constant.

The following table shows additional return values and additional information about a specific return value.

Value	Meaning
E_INVALIDARG	The enumeration value is not within the valid range.
E_POINTER	The enSecurityLevel, enSecurityType, or penSecurityLevel parameter is not a valid pointer.
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-to-PC or the media is not enabled.

Remarks

The security level set by this method affects only the session on which the method is called.

For example, the application might 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 or video encryption, it calls this method before accepting the incoming session.

In the call, the application specifies RTCSECT_AUDIO_VIDEO_MEDIA_ENCRYPTION for enSecurityType and RTCSECL_REQUIRED for enSecurityLevel.

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 PreferredSecurityLevel before accepting the incoming session.

If the session is in the RTCSS_CONNECTED state, a call to 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 PreferredSecurityLevel.

If the application calls PreferredSecurityLevel with a security level that is 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 PreferredSecurityLevel method specifying the RTCSECT_AUDIO_VIDEO_MEDIA_ENCRYPTION security type, the call will fail.

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 PreferredSecurityLevel 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 the remote party a session INVITE request that requires audio or video encryption and the remote party does not support audio or video encryption, a session cannot be established.

When a REINVITE request 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 request.

For example, if an existing session with audio or video streams fails to add a T120 stream to the session due to incompatible security levels, the session will continue with the audio or video streams active as before. Windows Embedded CE does not support video or T120 streams.

Requirements

Header	rtccore.h, rtccore.idl
Library	uuid.lib
Windows Embedded CE	Windows CE .NET 4.2 and later

See Also

Reference

IRTCSession2
IRTCSession::AddParticipant
IRTCSession::AddStream
RTC_SECURITY_LEVEL
RTC_SECURITY_TYPE