PeerCollabAsyncInviteContact 函数 (p2p.h)

项目
03/13/2024

PeerCollabAsyncInviteContact 函数向受信任的对等联系人发送邀请，以通过安全连接加入发件人的对等协作活动。邀请响应的可用性通过异步事件更新。

语法

NOT_BUILD_WINDOWS_DEPRECATE HRESULT PeerCollabAsyncInviteContact(
  [in, optional] PCPEER_CONTACT    pcContact,
  [in]           PCPEER_ENDPOINT   pcEndpoint,
  [in]           PCPEER_INVITATION pcInvitation,
  [in, optional] HANDLE            hEvent,
  [optional]     HANDLE            *phInvitation
);

参数

[in, optional] pcContact

指向包含与邀请收件人关联的联系信息的PEER_CONTACT 结构的指针。此参数是可选的。

若要邀请 pcEndpoint 中指定的调用对等方的终结点，请将指针值设置为 NULL。

[in] pcEndpoint

指向 PEER_ENDPOINT 结构的指针，该结构包含有关受邀对等方的终结点的信息。终结点必须与 pcContact 中指定的对等联系人相关联。

[in] pcInvitation

指向 PEER_INVITATION 结构的指针，该结构包含要发送到 pcEndpoint 中指定的终结点的邀请请求。如果此参数设置为 NULL，则返回E_INVALIDARG。

[in, optional] hEvent

此邀请的事件的句柄，该事件由上次调用 CreateEvent 创建。当异步邀请的状态更新时，将发出事件信号。若要获取响应数据，请调用 PeerCollabGetInvitationResponse。

如果未提供事件，调用方必须通过调用 PeerCollabGetInvitationResponse 轮询结果。

[optional] phInvitation

指向已发送邀请的句柄的指针。如果指定 了 NULL ，框架将在收到邀请响应后清理响应信息。如果 NULL 不是提供的邀请的指定句柄，则必须通过调用 PeerCollabCloseHandle 将其关闭。

返回值

如果函数成功，则返回S_OK。否则，该函数返回以下值之一。

返回代码	说明
E_OUTOFMEMORY	内存不足，无法支持此操作。
E_INVALIDARG	其中一个参数无效。
E_NOTIMPL	pcEndpoint 为 NULL。
PEER_E_NOT_INITIALIZED	Windows 对等基础结构未初始化。需要调用相关的初始化函数。

注解

此 API 确保接收邀请的对等方是指定为输入的联系人。如果指定的终结点上不存在特定联系人，则连接将失败。建议使用 PeerCollabAsyncInviteContact 代替不太安全的 PeerCollabAsyncInviteEndpoint。

将为邀请的收件人显示一个 toast。此 Toast 将转换为一个对话框，用户可以在其中接受或拒绝邀请。成功接受邀请后，将在收件人的计算机上启动协作应用程序。

若要成功接收邀请，必须使用 PeerCollabRegisterApplication 在收件人的计算机上注册应用程序。邀请的发件人也可能返回失败代码，因为收件人已关闭应用程序邀请。

如果发送邀请的联系人不接受邀请， PeerCollabGetInvitiationResponse 函数将返回PEER_E_CONNECTION_FAILED。

如果收件人只接受来自受信任联系人的邀请，则必须将邀请的发件人添加到收件人计算机的联系人存储中。在邀请尝试之前，必须将发件人添加到联系人存储中。若要将联系人添加到联系人存储，请调用 PeerCollabAddContact。

若要取消未完成的邀请，请调用 PeerCollabCancelInvitation。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	无受支持的版本
目标平台	Windows
标头	p2p.h
Library	P2P.lib
DLL	P2P.dll