PeerCollabAsyncInviteEndpoint function (p2p.h)
The PeerCollabAsyncInviteEndpoint function sends an invitation to a specified peer endpoint to join the sender's peer collaboration activity. The availability of the response to the invitation is updated through an asynchronous event.
Syntax
NOT_BUILD_WINDOWS_DEPRECATE HRESULT PeerCollabAsyncInviteEndpoint(
[in] PCPEER_ENDPOINT pcEndpoint,
[in] PCPEER_INVITATION pcInvitation,
[in, optional] HANDLE hEvent,
[out, optional] HANDLE *phInvitation
);
Parameters
[in] pcEndpoint
Pointer to a PEER_ENDPOINT structure that contains information about the invited peer. This peer is sent an invitation when this API is called.
This parameter must not be set to NULL.
[in] pcInvitation
Pointer to a PEER_INVITATION structure that contains the invitation request to send to the endpoint specified in pcEndpoint. E_INVALIDARG is returned if this parameter is set to NULL.
[in, optional] hEvent
Handle to the event for this invitation, created by a previous call to CreateEvent. The event is signaled when the status of the asynchronous invitation is updated. To obtain the response data, call PeerCollabGetInvitationResponse.
If the event is not provided, the caller must poll for the result by calling PeerCollabGetInvitationResponse.
[out, optional] phInvitation
A pointer to a handle to the sent invitation. If this parameter is NULL, the framework will cleanup the response information after the invitation response is received. If this parameter is not NULL, the handle must be closed by calling PeerCollabCloseHandle.
Return value
Returns S_OK if the function succeeds. Otherwise, the function returns one of the following values.
| Return code | Description |
|---|---|
|
There is not enough memory to support this operation. |
|
One of the arguments is invalid. |
Remarks
This API sends an invitation to the endpoint specified as input. It does not guarantee that the recipient of the invite is the specific contact that the user intended to send the invite to. To ensure that the invitation is sent to the correct contact use PeerCollabAsyncInviteContact.
A toast will appear for the recipient of the invitation. This toast will be converted to a dialog box in which the user can accept or decline the invitation. When the invitation is successfully accepted, the collaborative application is launched on the recipient's machine.
To successfully receive the invitation, the application must be registered on the recipient's machine using PeerCollabRegisterApplication. It is also possible for the sender of the invite to have failure codes returned because the recipient has turned off application invites.
The PeerCollabGetInvitiationResponse function will return PEER_E_CONNECTION_FAILED if the endpoint to which the invitation is being sent is not accepting invitations.
If the recipient is accepting invitations only from trusted contacts, then the sender of the invite must be added to the contact store of the recipient machine. The sender must be added to the contact store before the invitation attempt. To add a contact to the contact store, call PeerCollabAddContact.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | None supported |
| Target Platform | Windows |
| Header | p2p.h |
| Library | P2P.lib |
| DLL | P2P.dll |