IRTCClientPresence2::AddBuddyEx (Windows Embedded CE 6.0)

1/6/2010

Note

This method is unsupported in Windows Embedded CE 6.0.

This method allows the application to define the type of subscriptions allowed for a buddy. It extends the functionality of the IRTCClientPresence::AddBuddy method.

Syntax

HRESULT AddBuddyEx(
  BSTR bstrPresentityURI,
  BSTR bstrUserName,
  BSTR bstrData,
  VARIANT_BOOL fPersistent,
  RTC_BUDDY_SUBSCRIPTION_TYPE enSubscriptionType,
  IRTCProfile* pProfile,
  long lFlags,
  IRTCBuddy2** ppBuddy2
);

Parameters

• bstrPresentityURI
  [in] The presentity URI of the new buddy, with or without the sip: namespace prefix.

  This URI 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] VARIANT_TRUE if the buddy is saved in the persistent storage.

  VARIANT_FALSE if the buddy is volatile and is lost when the RTC client is shut down.

• enSubscriptionType
  [in] An RTC_BUDDY_SUBSCRIPTION_TYPE enumeration value specifying 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:

  • IRTCClientProvisioning2::EnableProfileEx has been called before calling this method. The profile used in the call to IRTCClientPresence2::EnablePresenceEx is used to create the buddy.
  • IRTCClientProvisioning2::EnableProfileEx 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.
  • IRTCClientProvisioning2::EnableProfileEx has not 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::EnableProfileEx. Otherwise, this method fails with an RTC_E_NOT_PRESENCE_PROFILE return code.

• lFlags
  [in] Reserved for future use and should be zero.

• ppBuddy2
  [out] Pointer to the IRTCBuddy2 interface.

  This parameter can be NULL, indicating that the method did 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 additional return values.

Value	Meaning
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 fails.
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 these parameters: bstrPresentityURI: 4,096 bstrUserName: 1,024 bstrData: 65,536
E_POINTER	A pointer in the parameter list is not valid.

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.

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 set an ACL on this file for better security.

Requirements

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

See Also

Reference

IRTCClientPresence2
IRTCBuddy2
IRTCClientPresence::AddBuddy
IRTCClientPresence2::EnablePresenceEx
IRTCClientProvisioning::EnumerateProfiles
IRTCClientProvisioning2::EnableProfileEx
IRTCProfile
RTC_BUDDY_SUBSCRIPTION_TYPE