IRTCClientPresence::AddBuddy (Windows Embedded CE 6.0)

1/6/2010

Note

This method is unsupported in Windows Embedded CE 6.0.

This method adds a buddy to the buddy list.

Syntax

HRESULT AddBuddy(
  BSTR bstrPresentityURI,
  BSTR bstrUserName,
  BSTR bstrData,
  VARIANT_BOOL fPersistent,
  IRTCProfile* pProfile,
  long lFlags,
  IRTCBuddy** ppBuddy
);

Parameters

• bstrPresentityURI
  [in] The presentity Universal Resource Identifier (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.

  In 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] VARIANT_TRUE to save the buddy in persistent storage.

  VARIANT_FALSE if 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 Client API chooses the best profile to use.

  If the RTCCS_FORCE_PROFILE flag is set and the parameter is NULL, no profile is used.

• lFlags
  [in] RTCCS_ flags specifying the force profile flag setting.

• ppBuddy
  [out] Pointer to an IRTCBuddy interface.

  This parameter can be NULL, indicating that the method should not retrieve an interface.

  This method adds a reference to the Buddy object, which the caller is responsible for releasing.

Return Value

This method can return an RTC_E_ constant.

The following table shows an additional possible return value.

Value	Meaning
E_FAIL	Method failed. This can mean that a buddy with the supplied presentity URI already exists.

Remarks

If your application is using the storage features in the IRTCClientPresence::EnablePresence method, the application should not override the profile using the RTCCS_FORCEPROFILE flag and the pProfile parameter. The application must call EnablePresence before it calls IRTCClientPresence::AddBuddy.

The application can obtain a pointer to IRTCProfile from the IRTCEnumProfiles interface. If no profile is specified for a given session, the RTC Client API selects the best profile from the list of enabled profiles, based on the session type and destination address.

Security Note:
This method can send data over the network in unencrypted form. Therefore, someone eavesdropping on the network could read the data. Before using this method in an unencrypted session, consider the security risk of sending the data in clear text. An RTC session can be encrypted by specifying TLS in the profile used for the session.

Security Note:
The RTC Client API does not set ACLs on the presence storage file. An application might consider setting an ACL on this file for better security.

Requirements

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

See Also

Reference

IRTCClientPresence
IRTCBuddy
IRTCClientPresence::EnablePresence
IRTCEnumProfiles
IRTCProfile