PeerGroupCreateInvitation function (p2p.h)

Article
10/13/2021

The PeerGroupCreateInvitation function returns an XML string that can be used by the specified peer to join a group.

Syntax

NOT_BUILD_WINDOWS_DEPRECATE HRESULT PeerGroupCreateInvitation(
  [in]  HGROUP     hGroup,
  [in]  PCWSTR     pwzIdentityInfo,
  [in]  FILETIME   *pftExpiration,
  [in]  ULONG      cRoles,
  [in]  const GUID *pRoles,
  [out] PWSTR      *ppwzInvitation
);

Parameters

[in] hGroup

Handle to the peer group for which this invitation is issued. This handle is returned by the PeerGroupCreate, PeerGroupOpen, or PeerGroupJoin function. This parameter is required.

[in] pwzIdentityInfo

Pointer to a Unicode string that contains the XML blob (including the GMC) returned by a previous call to PeerIdentityGetXML with the identity of the peer. Alternatively, this parameter can contain a pointer to an XML blob generated by PeerIdentityGetXML using the peer information contained in PEER_CONTACT to generate an invitation for a peer contact.

[in] pftExpiration

Specifies a UTC FILETIME structure that contains the specific date and time the invitation expires. This value cannot be greater than the remaining lifetime of the issuing peer. If this parameter is NULL, the invitation lifetime is set to the maximum value possible - the remaining lifetime of the peer.

[in] cRoles

Specifies the count of roles in pRoleInfo.

[in] pRoles

Pointer to a list of GUIDs that specifies the combined set of available roles. The available roles are as follows.

Value	Meaning
PEER_GROUP_ROLE_ADMIN	This role can issue invitations, issue credentials, and renew the GMC of other administrators, as well as behave as a member of the peer group.
PEER_GROUP_ROLE_MEMBER	This role can publish records to the group database.

[out] ppwzInvitation

Pointer to a Unicode string that contains the invitation from the issuer. This invitation can be passed to PeerGroupJoin by the recipient in order to join the specified peer group. To return the details of the invitation as a PEER_INVITATION_INFO structure, pass this string to PeerGroupParseInvitation. To release this data, pass this pointer to PeerFreeData.

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 to perform the specified operation.
PEER_E_GROUP_NOT_READY	The peer group is not in a state where records can be added. For example, PeerGroupJoin is called, but synchronization with the group database has not completed.
PEER_E_CHAIN_TOO_LONG	The GMC chain is longer than 24 administrators or members. For more information about GMC chains, please refer to the How Group Security Works documentation.
PEER_E_IDENTITY_DELETED	The data passed as pwzIdentityInfo is for a deleted identity and no longer valid.
PEER_E_NOT_AUTHORIZED	The peer that called this method is not an administrator.
PEER_E_NO_KEY_ACCESS	Access to the 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 is 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

Peers cannot create invitations for peers whose assumed role is superior to their own. For example, a peer in a member role cannot create an invitation for a peer in an administrator role.

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