Share via

IRTCClientPresence2::AddBuddyEx

  • Article

The AddBuddyEx method extends the capability of the IRTCClientPresence::AddBuddy method with the ability to define the type of subscriptions allowed for this buddy.

HRESULT AddBuddyEx(BSTRbstrPresentityURI,
BSTRbstrUserName,
BSTRbstrData,
VARIANT_BOOLfPersistent,
RTC_BUDDY_SUBSCRIPTION_TYPEenSubscriptionType,
IRTCProfile*pProfile,
longlFlags,
IRTCBuddy2**ppBuddy2);

Parameters

  • bstrPresentityURI
    [in] The presentity URI of the new Buddy, with or without the sip: namespace prefix. This is used as a key in the list, and no duplicate is allowed.

  • bstrUserName
    [in] The displayable name of the new Buddy.

  • bstrData
    [in] Optional private data.

  • fPersistent
    [in] If VARIANT_TRUE, the Buddy is saved in the persistent storage. If VARIANT_FALSE, the Buddy is volatile and is lost when the RTC Client is shut down.

  • enSubscriptionType
    [in] The RTC_BUDDY_SUBSCRIPTION_TYPE enumeration that contains information about subscriptions for this buddy.

  • pProfile
    [in] Pointer to an IRTCProfile interface specifying a provisioning profile to use for this Buddy.

    If this parameter is NULL, the following three cases apply:

    • Case 1: IRTCClientProvisioning2::EnablePresenceEx has been called before calling this method. The profile used in the call to EnablePresenceEx is used to create the buddy.
    • Case 2: IRTCClientProvisioning2::EnablePresenceEx has not been called before calling this method. If the buddy's URI is of the form username@hostname, the RTC Client API chooses a profile with RTCST_PC_TO_PC capabilities from the list of created profile objects.
    • Case 3: IRTCClientProvisioning2::EnablePresenceEx has been called before calling this method and the buddy's SIP URI is not of the form username@hostname. No profile is used for this buddy session.

    If this parameter is not NULL, the profile specified must be the profile previously specified in the call to IRTCClientProvisioning2::EnablePresenceEx. If the profile specified in this parameter was not specified in the call to EnablePresenceEx, this method will fail with an RTC_E_NOT_PRESENCE_PROFILE return code.

  • lFlags
    [in] This parameter is reserved for future use and should be zero.

  • ppBuddy2
    [out] Pointer to the IRTCBuddy2 interface on the newly created Buddy object. This parameter may be NULL, indicating that the method should not return an interface. This call adds a reference to the Buddy object, which the caller is responsible for releasing.

Return Values

RTC methods may return an RTC_E_ constant.

Value Meaning
RTC_E_NOT_PRESENCE_NOT_ENABLED Presence has not been enabled.
RTC_E_NOT_ALLOWED The polled buddy type cannot be persisted. If the enSubscriptionType parameter specifies RTCBT_POLL and the fPersistent parameter specifies VARIANT_TRUE, this method will fail.
E_INVALIDARG The bstrPresentityURI is not a valid URI or the length of the bstrPresentityURI, bstrData, or bstrUserName parameter is too long. The following maximum lengths are enforced for each of these parameters:

  • bstrPresentityURI: 4096
  • bstrUserName: 1024
  • bstrData: 65536
E_POINTER One of the pointers in the parameter list is not a valid pointer.

Remarks

Roaming contacts are not supported when the Registrar server in the profile specifies the UDP transport. If UDP is the transport, presence can only be enabled with a local presence store. Local presence storage is specified in the IRTCClientPresence2::EnablePresenceEx method.

The IRTCClientPresence2::EnablePresenceEx method must be called before calling this method.

Note  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.

The RTC Client API does not set ACLs on the presence storage file. An application may want to consider setting an ACL on this file for better security.

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_IRTCClientPresence2 is defined as AD1809E8-62F7-4783-909A-29C9D2CB1D34.

See Also

IRTCBuddy, IRTCBuddy2, IRTCClientPresence2, IRTCClientPresence::AddBuddy, IRTCProfile, IRTCProfile2, RTC_BUDDY_SUBSCRIPTION_TYPE, Presence, Create a Buddy Group and Add Buddies