PeerGroupCreateInvitation function

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


HRESULT WINAPI PeerGroupCreateInvitation(
  _In_  HGROUP       hGroup,
  _In_  PCWSTR       pwzIdentityInfo,
  _In_  FILETIME     *pftExpiration,
  _In_  ULONG        cRoles,
  _In_  PEER_ROLE_ID *pRoles,
  _Out_ PWSTR        *ppwzInvitation


hGroup [in]

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.

pwzIdentityInfo [in]

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.

pftExpiration [in]

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.

cRoles [in]

Specifies the count of roles in pRoleInfo.

pRoles [in]

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


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.


This role can publish records to the group database.


ppwzInvitation [out]

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 codeDescription

One of the parameters is not valid.


There is not enough memory to perform the specified operation.


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.


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.


The data passed as pwzIdentityInfo is for a deleted identity and no longer valid.


The peer that called this method is not an administrator.


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.


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.


Minimum supported client

Windows XP with SP2 [desktop apps only]

Minimum supported server

None supported


Windows XP with SP1 with the Advanced Networking Pack forWindows XP







See also