IRTCClientPresence2::AddBuddyEx (Windows CE 5.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.
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 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 Values
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:
|
| 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
OS Versions: Windows CE .NET 4.2 and later.
Header: Rtccore.h, Rtccore.idl.
Link Library: Uuid.lib.
See Also
IRTCClientPresence2 | IRTCBuddy2 | IRTCClientPresence::AddBuddy | IRTCClientPresence2::EnablePresenceEx | IRTCClientProvisioning::EnumerateProfiles | IRTCClientProvisioning2::EnableProfileEx | IRTCProfile | RTC_BUDDY_SUBSCRIPTION_TYPE
Send Feedback on this topic to the authors