IRTCClientPresence::AddBuddy

  • Article

The AddBuddy method adds a Buddy to the list of buddies.

HRESULT AddBuddy(BSTRbstrPresentityURI,
BSTRbstrUserName,
BSTRbstrData,
VARIANT_BOOLfPersistent,
IRTCProfile*pProfile,
longlFlags,
IRTCBuddy**ppBuddy);

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.

    **RTC 1.2:  **This parameter can be set to NULL to allow the display name to be used.

  • bstrData
    [in] An optional private data BLOB.

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

  • pProfile
    [in] Pointer to an IRTCProfile interface specifying a provisioning profile to use for this Buddy. It is taken into account only when the RTCCS_FORCE_PROFILE flag is specified in lFlags; otherwise, it must be set to NULL, and the RTC API automatically chooses the best profile to use. If the RTCCS_FORCE_PROFILE flag is set and the parameter is NULL, no profile is used. For more information, please see the Remarks section.

  • lFlags
    [in] RTCCS_ flags indicating the force profile flag setting. For more information, please see the Remarks section.

  • ppBuddy
    [out] Pointer to the IRTCBuddy 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_CLIENT_NOT_INITIALIZED The client is not initialized.
E_FAIL Method failed. This may mean that a buddy with this presentity URI already exists.
RTC_E_PRESENCE_NOT_ENABLED Presence is not enabled.

Remarks

If you are using the storage features in the EnablePresence method, you should not override the profile using the RTCCS_FORCEPROFILE flag and the pProfile parameter. The EnablePresence method must be called before calling this method.

An IRTCProfile can be obtained from EnumerateProfiles. If no profile is specified for a given session, the RTC API selects the best profile from the list of enabled profiles based on the session type and destination address.

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

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_IRTCClientPresence is defined as 11c3cbcc-0744-42d1-968a-51aa1bb274c6.

See Also

IRTCClientPresence, IRTCClientPresence2::AddBuddyEx, IRTCProfile, IRTCBuddy, IRTCClientPresence::get_Buddies, IRTCClientPresence::EnumerateBuddies, IRTCClientPresence::RemoveBuddy