Managing Group Records

A group record is specific data published to all active members of a peer group, for example, a chat message or an application-specific status update. A record is represented by the PEER_RECORD structure, and contains the following information about a peer:

• The record ID is a value that uniquely identifies a record in the peer group.
• A GUID that specifies the record type. Applications can support different record types. An application interprets the data field of a record based on the record type. Some GUIDs are reserved, and the API call returns PEER_E_NOT_AUTHORIZED when the application attempts to use them.
• A set of record attributes described as an XML string. The attributes are used when searching records. For more information about attributes, see Record Attribute Schema.
• The peer time that a record is created.
• The peer time that a record expires.
• The peer time that a record is modified.
• The creator of a record.
• The member who modifies a record.
• A PEER_DATA structure that contains the cryptographic signature for all of the fields in this PEER_RECORD structure. This field cannot be directly updated or altered by a peer.
• A PEER_DATA structure that contains the application-specific data associated with this record as an array of bytes. The type of data present in this field is determined by application-defined record type.

Obtaining Peer Group Records

Individual records are obtained by calling PeerGroupGetRecord with the ID of the record. When processing all records of a specific type, the enumerated set of all current peer group records is obtained by first calling PeerGroupEnumRecords to open the enumeration and then iteratively calling PeerGetNextItem until all records are retrieved. When finished, close the enumeration and release the memory associated with it by calling PeerEndEnumeration.

When a record is created, deleted, or updated by a peer, the affected record is published to all members of the peer group by way of the PEER_GROUP_EVENT_RECORD_CHANGE event. Note that if a peer is not connected to the group, it will receive the updated record then next time it connects. It is important to register for this event with PeerGroupRegisterEvent if your application maintains or manages records in any meaningful way. Alternatively, the application can query the record database on demand using PeerGroupSearchRecords.

When the PEER_GROUP_EVENT_RECORD_CHANGE event is raised, the specific record ID and type as well as the type of change (add, update, delete) is received as a PEER_EVENT_RECORD_CHANGE_DATA structure. This structure is obtained with a call to PeerGroupGetEventData. If the change is an add or an update, you should use PeerGroupGetRecord to obtain the record with the supplied ID. The local record database for the infrastructure is updated automatically.

You can also search for specific records based on specific custom attributes supplied in the pwzAttributes field of PEER_RECORD, as well as any predefined attributes. To accomplish this, use the PeerGroupSearchRecords function with an XML search query formatted as specified in the Record Search Query Format topic.

For more details on working with records in the Peer Infrastructure, please refer to the Records topic in Using the Peer Infrastructure.

Administration of Peer Group Records

When the initial invitations are issued by the peer group's creator, it can specify that certain members serve in an administrative role (PEER_GROUP_ROLE_ADMIN) whenever it issues new credentials to the user (via either PeerGroupCreateInvitation or PeerGroupIssueCredentials). An administrator has the ability to directly add, delete, and update any peer group records. Conversely, a peer group member with it's role set to either PEER_GROUP_ROLE_MEMBER or PEER_GROUP_ROLE_INVITING_MEMBER can only add, update, and delete its own record(s).

The creator has the administrator role by default.

To update a record, obtain the record with PeerGroupGetRecord or PeerGroupEnumRecords, make the changes, and pass the updated record to PeerGroupUpdateRecord.

To delete a record, pass the record ID to delete to PeerGroupDeleteRecord.

To add a record, create a new PEER_RECORD structure and populate the following fields:

• dwSize. This field contains the value of sizeof(PEER_RECORD).
• ftExpiration. This field contains the expiration date and time of this record, expressed in peer time as a FILETIME structure.
• type. This field contains a GUID value that identifies the record type to the application. If this type is custom to your application infrastructure, you should also populate the data field.

The following fields are populated by the infrastructure, and will be ignored if set by the application:

• id
• pwzCreatorId
• pwzLastModifiedById
• ftCreation
• ftLastModified
• securityData

The remaining fields are optional. To add this new record to the peer group, pass it to PeerGroupAddRecord.

Importing and Exporting Records

Peer-to-peer group records are maintained locally as a database. To save a current snapshot of the peer group record database to a local file, call PeerGroupExportDatabase, and pass it the handle to the peer group. This file can then be transported to a different computer or application, which can extract and use this record database by calling PeerGroupImportDatabase.