Share via

IRTCClientPresence::AddWatcher

  • Article

The AddWatcher method adds a Watcher to the allowed/blocked Watcher list.

HRESULT AddWatcher(BSTRbstrPresentityURI,
BSTRbstrUserName,
BSTRbstrData,
VARIANT_BOOLfBlocked,
VARIANT_BOOLfPersistent,
IRTCWatcher**ppWatcher);

Parameters

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

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

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

  • fBlocked
    [in] The initial state of the Watcher (blocked or allowed). If VARIANT_TRUE, the Watcher is blocked; otherwise, it is allowed.

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

  • ppWatcher
    [out] Pointer to the IRTCWatcher interface on the newly created Watcher object. This parameter may be NULL, indicating that the method should not return an interface. This call adds a reference to the Watcher 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

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, IRTCWatcher, IRTCClientPresence::RemoveBuddy, IRTCClientPresence2::AddWatcherEx, Presence Access Control