如何使用组
对等分组是一种技术,允许开发人员快速有效地创建安全的对等网络。 以下列表列出了创建对等分组应用程序时的主要注意事项。
获取对等标识
在创建或连接到组之前,对等方必须获取对等标识,该标识是用于唯一标识组的对等方的名称。 若要获取对等方上定义的所有对等标识的枚举列表,请调用 PeerEnumIdentities,这将返回枚举的句柄。 若要获取对等标识,请使用枚举句柄和要检索的成员数调用 PeerGetNextItem 。 继续调用 PeerGetNextItem ,直到 pCount 参数返回的值小于请求的对等标识数。
如果对等方的对等标识不存在,可以通过调用 PeerIdentityCreate 来创建它。 创建对等标识后,对等方将生成一个标识 XML Blob,其中包含分配给它的公钥
通过调用 PeerIdentityGetXML 获取对等标识信息。 组创建者或管理员使用此对等标识信息作为邀请 XML Blob 颁发加入组所需的凭据。
有关对等标识的详细信息,请参阅 Identity Manager API 文档
启动对等分组基础结构
在应用程序调用对等分组 API 中的任何函数之前,必须调用 PeerGroupStartup 。 此函数初始化应用程序的对等分组基础结构并设置支持的版本。
获取组句柄
若要连接到组并开始参与,必须获取对等组的句柄。 以下列表标识了连接到对等组的三种方法:
- 通过调用 PeerGroupCreate 创建对等组,这将初始化一个新的对等组,并返回一个有效句柄,该对等方作为所有者和唯一管理员。
- 通过调用 PeerGroupJoin 加入对等组。 若要加入对等组,对等方必须收到来自对等组管理员的邀请。 若要获取邀请,请将标识信息 XML Blob 发送给创建邀请的管理员,并通过外部机制(如电子邮件或 FTP)将其发送给你。 邀请和对等标识传递给 PeerGroupJoin,这将返回组的有效句柄。
- 通过调用 PeerGroupOpen 打开对等方之前已加入 的对等组。 在这种情况下,无需获取邀请。
从上述函数之一获取有效的对等组句柄后,可以通过使用新句柄调用 PeerGroupConnect 来连接到对等组。
注意
如果与对等组的连接失败,则会发生PEER_GROUP_EVENT_CONNECTION_FAILED事件。 处理程序可以尝试重新建立与对等组的连接。
注册对等分组事件
在对等方参与对等组之前,对等方必须注册对等组事件。 若要注册特定的对等事件,请调用 PeerGroupRegisterEvent,并传入PEER_GROUP_EVENT_TYPE中定义的一个或多个对等事件类型。 必须注册适用于应用程序的每个对等事件;例如,若要通过直接连接接收数据,请注册PEER_GROUP_EVENT_DIRECT_CONNECTION和PEER_GROUP_EVENT_INCOMING_DATA事件。 每次调用都会接受一个事件句柄,并返回该对等事件的 HPEEREVENT 句柄。
事件处理程序可以通过将已注册的对等事件的句柄传递给 PeerGroupGetEventData 来获取与对等事件关联的数据。 此对等事件数据作为PEER_GROUP_EVENT_DATA联合返回。 如果对等事件队列为空,则此函数返回PEER_S_NO_EVENT_DATA。
可以通过调用 PeerGroupUnregisterEvent 并为要注销的对等事件提供句柄来取消注册对等事件。 调用函数后,不再注册与句柄关联的对等事件。
创建管理员和成员角色
创建对等组的对等方称为对等组创建者,默认情况下具有管理员角色。 只有对等组创建者才能设置组属性。
受邀加入对等组的对等方可以是管理员或成员。 如果发出邀请的管理员为他们分配了管理员角色,他们可以邀请新成员加入对等组,并将管理员角色同样分配给其他成员。
对等组成员的角色在管理员提供给成员的邀请中设置。 若要添加更多管理员,请在创建邀请时将 PeerGroupCreateInvitation的 pRoles 参数的值设置为PEER_GROUP_ROLE_ADMIN。
成员可以参与对等组,但不能邀请和授权新成员、设置组属性,或者更新或删除他们不专门创建的组记录。 若要将成员状态分配给参与对等方,请在为该对等方创建邀请时,将 PeerGroupCreateInvitation 的 pRoles 参数的值设置为PEER_GROUP_ROLE_MEMBER。
若要更改成员的角色,必须将包含新角色的新凭据颁发给该成员。 为此,请从 PeerGroupEnumMembers 返回的 PEER_MEMBER 结构中获取此成员的PEER_CREDENTIAL_INFO结构。 将 PEER_CREDENTIAL_INFO 中的 pRoles 字段更改为新角色,并将结构传递给 PeerGroupIssueCredentials。
新凭据在连接到对等组之前不会对对对等方生效。 如果它们当前已连接,则必须关闭组并重新连接以获取更新的凭据。
查找对等方
若要获取参与对等组的所有对等方的枚举列表,请使用组句柄调用 PeerGroupEnumMembers ,这将返回枚举的句柄。 若要获取成员,请使用枚举句柄和要检索的成员数调用 PeerGetNextItem 。 继续调用 PeerGetNextItem ,直到 pCount 参数返回的值小于请求的成员数。 请注意,可能不会返回可用成员的完整列表。
每个成员都表示为一个 PEER_MEMBER 结构,该结构包含对等方的标识、节点 ID 和活动对等方的 IP 地址。
完成后,关闭枚举并通过调用 PeerEndEnumeration 释放关联的内存。
直接连接到对等方
当对等方连接到对等组时,通过调用 PeerGroupOpenDirectConnection 并提供另一对等方的标识,启动与其他已连接成员的直接交换。 此调用是异步的,并返回 64 位连接 ID。 如果调用成功,则会收到PEER_GROUP_EVENT_DIRECT_CONNECTION_EVENT对等事件,指示连接成功。 如果连接成功,则连接 ID 有效,可用于通过直接连接发送和接收数据。
为了能够接收直接连接,另一对等方还必须事先注册PEER_GROUP_EVENT_DIRECT_CONNECTION对等事件。
若要将数据发送到对等方,请使用有效的连接 ID 调用 PeerGroupSendData 。 若要接收数据,必须为PEER_GROUP_EVENT_INCOMING_DATA对等事件注册另一对等方。 同样,如果发送对等方想要依次接收数据,则还必须为PEER_GROUP_EVENT_INCOMING_DATA对等事件注册数据。
若要接收与组中其他对等方当前活动的直接连接的总集,请调用 PeerGroupEnumConnections 以打开枚举,并使用 PeerGetNextItem 循环访问连接列表。
若要关闭直接连接,请调用 PeerGroupCloseDirectConnection 并传入连接 ID。
关闭和关闭对等组
若要关闭与对等组的连接,请调用 PeerGroupClose,这会使组句柄失效,但不会关闭对等组基础结构。 通过调用 PeerGroupDelete 删除对等组数据。
应用程序使用完对等分组基础结构后,必须调用 PeerGroupShutdown。