IRTCSession3::AddParticipantEx

  • Article

The AddParticipantEx method creates a participant with the specified URI on the specified device and adds it to the session. Adding a participant to an idle session initiates the call. Phone-phone calls and MIM sessions can add more than one participant.

Calling the get_CanAddParticipants property on the session enables the UI to determine if it is possible to add a participant to the session.

HRESULT AddParticipantEx(BSTRbstrAddress,
BSTRbstrName,
BSTRbstrEPID,
IRTCParticipant2**ppParticipant);

Parameters

  • bstrAddress
    [in] A BSTR that specifies the URI of the participant. This could be a SIP or TEL URI, e-mail address, IP address, or DNS name. Note that a SIP URI must contain legal characters as specified in RFC 3261.
  • bstrName
    [in] A BSTR that specifies the displayable name of the participant.
  • bstrEPID
    [in] A BSTR that specifies device ID. The device ID can be obtained by calling IRTCPresenceDevice2::get_DeviceID. Note that the device ID is case-sensitive.
  • ppParticipant
    [out] Returns a pointer to the IRTCParticipant2 interface on the newly created Participant object. If this parameter is NULL, the method will not return an interface. This call adds a reference to the Participant object, which the caller is responsible for releasing.

Return Values

RTC methods may return an RTC_E_ constant.

Value Meaning
RTC_E_INVALID_SESSION_STATE Participant cannot be added in this state.
ERROR_USER_EXISTS There is already a participant with the same User URI.
RTC_E_INVALID_ID The endpoint identifier must be 16 hexadecimal characters or less.

Remarks

This function may send data over the wire in unencrypted form; therefore, someone eavesdropping on the network may be able to read the data. The security risk of sending the data in clear text should be considered before using this method in an unencrypted session. An RTC session can be encrypted by specifying TLS in the profile used for the session.

Note  The online status of participants in a MIM session will be available to all other participants in the session. This may result in compromised privacy information. If none of the participants in the session has blocked another participant from viewing his online status, no privacy information would be compromised. However, if any participant in the session has blocked another participant from viewing his online status, the first participant's privacy information would be compromised in a MIM session.

Note  Routing of the INVITE request depends on the routing support of the SIP server. When the client application uses Microsoft® Live Communications Server 2005 as the SIP server, the INVITE request is routed to the endpoint specified by the device ID.

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_IRTCSession is defined as A46E81AD-1D5A-4063-9521-62E1FA85DF5C.

See Also

IRTCSession, IRTCSession3, IRTCParticipant, IRTCParticipant2, IRTCSession::RemoveParticipant, Enhanced MPOP Support, IRTCSession::get_CanAddParticipants, Create a Session and Make a Call, Create a Multiparty IM Session and Add a Participant, Add a Participant to an Existing Session, Create an Outgoing Application Session, Create an Outgoing Session When the Client is Behind a NAT