PeerGroupIssueCredentials function (p2p.h)

Article
10/13/2021

The PeerGroupIssueCredentials function issues credentials, including a GMC, to a specific identity, and optionally returns an invitation XML string the invited peer can use to join a peer group.

Syntax

NOT_BUILD_WINDOWS_DEPRECATE HRESULT PeerGroupIssueCredentials(
  [in]  HGROUP               hGroup,
  [in]  PCWSTR               pwzSubjectIdentity,
  [in]  PEER_CREDENTIAL_INFO *pCredentialInfo,
  [in]  DWORD                dwFlags,
  [out] PWSTR                *ppwzInvitation
);

Parameters

[in] hGroup

Handle to a peer group for which a peer will issue credentials to potential invited peers. This handle is returned by the PeerGroupCreate, PeerGroupOpen, or PeerGroupJoin function. This parameter is required.

[in] pwzSubjectIdentity

Specifies the identity of a peer to whom credentials will be issued. This parameter is required.

[in] pCredentialInfo

PEER_CREDENTIAL_INFO structure that contains information about the credentials of a peer whose identity is specified in pwzSubjectIdentity. If this parameter is NULL, the information stored in the peer database is used, instead. This parameter is optional.

If this parameter is provided, the following fields in PEER_CREDENTIAL_INFO are ignored:

pwzIssuerPeerName
pwzIssuerFriendlyName

[in] dwFlags

Specifies a set of flags used to describe actions taken when credentials are issued. If this parameter is set to 0 (zero), the credentials are returned in ppwzInvitation. This parameter is optional.

Value	Meaning
PEER_GROUP_STORE_CREDENTIALS	Publish the subject identity's newly-created GMC in the group database. The GMC is picked up automatically by the subject. If this flag is not set, the credentials must be obtained by a different application such as email.

[out] ppwzInvitation

Pointer to an invitation XML string returned by the function call. This invitation is passed out-of-band to the invited peer who uses it in a call to PeerGroupJoin. This parameter is optional.

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_IDENTITY_DELETED	The identity creating the credentials has been deleted.
PEER_E_IDENTITY_NOT_FOUND	The identity cannot be found in the group database, and pCredentialInfo is NULL.
PEER_E_NO_KEY_ACCESS	Access to the identity or 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.

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

Remarks

This function can only be called successfully by an administrator.

The credentials for a member (PEER_CREDENTIAL_INFO) are obtained by calling PeerGroupEnumMembers. The credentials are located in the pCredentialInfo field of the PEER_MEMBER structure for a specific member.

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

Share via