PeerGroupPasswordJoin function (p2p.h)

Article
10/13/2021

The PeerGroupPasswordJoin function prepares a peer with an invitation and the correct password to join a password-protected peer group prior to calling PeerGroupConnect or PeerGroupConnectByAddress.

Syntax

NOT_BUILD_WINDOWS_DEPRECATE HRESULT PeerGroupPasswordJoin(
  [in]  PCWSTR pwzIdentity,
  [in]  PCWSTR pwzInvitation,
  [in]  PCWSTR pwzPassword,
  [in]  PCWSTR pwzCloud,
  [out] HGROUP *phGroup
);

Parameters

[in] pwzIdentity

Pointer to a Unicode string that contains the identity opening the specified peer group. If this parameter is NULL, the implementation uses the identity obtained from PeerIdentityGetDefault.

[in] pwzInvitation

Pointer to a Unicode string that contains the XML invitation granted by another peer. An invitation with a password is created when the inviting peer calls PeerGroupCreatePasswordInvitation. Specific details regarding this invitation, including the password set by the group creator, can be obtained as a PEER_INVITATION_INFO structure by calling PeerGroupParseInvitation. This parameter is required.

[in] pwzPassword

Pointer to a zero-terminated Unicode string that contains the password required to validate and join the peer group. This password must match the password specified in the invitation. This parameter is required.

[in] pwzCloud

Pointer to a Unicode string that contains the name of the PNRP cloud where a group is located. The default value is NULL, which indicates that the cloud specified in the invitation must be used.

[out] phGroup

Pointer to the handle of the peer group. To start communication with a group, call PeerGroupConnect. This parameter is required.

Return value

Returns S_OK if the operation succeeds. Otherwise, the function returns one of the following values.

Return code	Description
E_INVALIDARG	One of the parameters is not valid.
E_OUTOFMEMORY	There is not enough memory available to complete the operation.
PEER_E_CLOUD_NAME_AMBIGUOUS	The cloud cannot be uniquely discovered, for example, more than one cloud matches the provided name.
PEER_E_INVALID_PEER_NAME	The peer identity specified in pwzIdentity is invalid.
PEER_E_INVITATION_NOT_TRUSTED	The invitation is not trusted by the peer. It has been altered or contains errors.
PEER_E_NO_CLOUD	The cloud cannot be located.
PEER_E_UNSUPPORTED_VERSION	The invitation is not supported by the current version of the Peer Infrastructure.
PEER_E_NO_KEY_ACCESS	Access to the peer identity or peer group keys is denied. Typically, this is caused by an incorrect access control list (ACL) for the folder that contains the user or computer keys. This can happen when the ACL has been reset manually.
PEER_S_ALREADY_A_MEMBER	The local peer attempted to join a group based on a password more than once.

Cryptography-specific errors may be returned from the Microsoft RSA Base Provider. These errors are prefixed with CRYPT_* and defined in Winerror.h.

Remarks

In the event of a clock skew between participating machines, the initial PeerGroupPasswordJoin function may still succeed while the following call of PeerGroupConnect can result in a failure to join depending on the severity of the skew.

Requirements

Requirement	Value
Minimum supported client	Windows XP with SP2 [desktop apps only],Windows XP with SP1 with the Advanced Networking Pack forWindows XP
Minimum supported server	None supported
Target Platform	Windows
Header	p2p.h
Library	P2P.lib
DLL	P2P.dll