PeerCollabAsyncInviteContact function (p2p.h)
The PeerCollabAsyncInviteContact function sends an invitation to a trusted peer contact to join the sender's peer collaboration activity over a secured connection. The availability of the invitation response is updated through an asynchronous event.
Syntax
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
);
Parameters
[in, optional] pcContact
Pointer to a PEER_CONTACT structure that contains the contact information associated with the recipient of the invite. This parameter is optional.
To invite the endpoint of the calling peer specified in pcEndpoint, set the pointer value to NULL.
[in] pcEndpoint
Pointer to a PEER_ENDPOINT structure that contains information about the invited peer's endpoint. The endpoint must be associated with the peer contact specified in pcContact.
[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.
[optional] phInvitation
A pointer to a handle to the sent invitation. The framework will cleanup the response information after the invitation response is received if NULL is specified. When NULL is not the specified handle to the invitation provided, it 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. |
|
pcEndpoint is NULL. |
|
The Windows Peer infrastructure is not initialized. Calling the relevant initialization function is required. |
Remarks
This API ensures the peer that receives the invitation is the contact specified as input. The connection will fail if the specific contact is not present on the endpoint specified. The use of PeerCollabAsyncInviteContact is recommended in place of the less secure PeerCollabAsyncInviteEndpoint.
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 contact 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.
To cancel an outstanding invitation, call PeerCollabCancelInvitation.
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 |