IRTCClient::CreateSession

  • Article

The CreateSession method creates a PC-PC, PC-phone, phone-phone, or IM session. The session starts in the RTCSS_IDLE state. To initiate a call or messaging session, you must call the AddParticipant method on the session returned by this method.

HRESULT CreateSession(RTC_SESSION_TYPEenType,
BSTRbstrLocalPhoneURI,
IRTCProfile*pProfile,
longlFlags,
IRTCSession**ppSession);

Parameters

  • enType
    [in] An RTC_SESSION_TYPE enumeration that specifies the type of session created.
  • bstrLocalPhoneURI
    [in] Used in phone-phone sessions to specify the local user TEL URI. If the session type is not phone-phone, this should be set to NULL.
  • pProfile
    [in] Profile to use for this session. If none is specified, the API will determine the profile to use for the session.
  • lFlags
    [in] RTCCS_ flags specifying the force profile and fail on redirect settings.
  • ppSession
    [out] Pointer to the newly created IRTCSession interface. This call adds a reference to the Session object, which the caller is responsible for releasing.

Return Values

RTC methods may return an RTC_E_ constant.

Value Meaning
E_FAIL The media could not be disabled for this session, or the local session description could not be set, or there is insufficient memory to perform this operation.

Remarks

If no profile is specified, RTC will determine first if a profile is needed for the session based on the SIP URL. If a profile is needed, a profile is chosen from the list of enabled profiles based on the session type.

A call to CreateSession for an RTCST_PC_TO_PC or RTCST_PC_TO_PHONE type session will fail if the media has been globally disabled. The media is disabled by initializing the Client object via the IRTCClient2::InitializeEx method with the RTCIF_DISABLE_MEDIA flag set.

A call to CreateSession for an RTCST_PC_TO_PC or RTCST_PC_TO_PHONE type session will fail if the media has been globally disabled. The media can be globally disabled by initializing the Client object with the IRTCClient2::InitializeEx method with the RTCIF_DISABLE_MEDIA flag set.

If the application wants to limit the media types allowed on outgoing sessions, it should call the IRTCClient::SetPreferredMediaTypes method to specify the allowed media types. For example, if the application wants to create a PC-to-PC session with only T120 media, but wants to accept incoming calls with audio and video media as well, it should ensure that the preferred media types are set appropriately at the different stages. The sequence of RTC API calls in this case will be:

  1. Call IRTCClient::SetPreferredMediaTypes specifying RTCMT_T120_SENDRECV in the lMediaTypes parameter.
  2. Call IRTCClient::CreateSession and specify RTCST_ PC_TO_PC in the enType parameter.
  3. Call IRTCSession::AddParticipant to connect the session.
  4. Wait for IRTCSessionStateChangeEvent. The session state can be either RTCSS_CONNECTED or RTCSS_DISCONNECTED.
  5. Call IRTCClient::SetPreferredMediaTypes with the lMediaTypes parameter set to RTCMT_ALL. This call will ensure that the application is able to receive incoming audio and video calls.

Requirements

Client: Requires Windows XP.
Server: Requires Windows Server 2003.
Redistributable: Requires Rtcdll.dll on Windows 2000, and Windows Me/98.
Header: Declared in Rtccore.h.
Library: Included as a resource in Rtcdll.dll.
GUID: IID_IRTCClient is defined as 07829e45-9a34-408e-a011-bddf13487cd1.

See Also

Create an IM Session, Create a Session and Make a Call, IRTCClient, IRTCProfile, IRTCSession, RTC_SESSION_TYPE, RTCCS_, Create a Multiparty IM Session and Add a Participant, Create an Outgoing Session When the Client is Behind a NAT