グループを操作する方法

ピア ツー ピア グループ化は、開発者がセキュリティで保護されたピア ネットワークを迅速かつ効果的に作成できるようにするテクノロジです。 次の一覧は、ピア グループ化アプリケーションの作成に関する主な考慮事項を示しています。

• ピア ID の取得
• ピア グループの起動
• グループ化イベントの登録
• グループへの接続
• 管理者ロールとメンバー ロールの作成
• ピアの検索
• ピアへの直接接続
• グループの終了とシャットダウン

ピア ID の取得

グループを作成または接続する前に、ピアはピア ID (グループへのピアを一意に識別するために使用される名前) を取得する必要があります。 ピアで定義されているすべてのピア ID の列挙リストを取得するには、 PeerEnumIdentities を呼び出して、列挙型へのハンドルを返します。 ピア ID を取得するには、列挙ハンドルと取得するメンバーの数を指定して PeerGetNextItem を呼び出します。 pCount パラメーターが要求されたピア ID の数より小さい値を返すまで、PeerGetNextItem の呼び出しを続けます。

ピアのピア ID が存在しない場合は、 PeerIdentityCreate を呼び出して作成できます。 ピア ID を作成した後、ピアは、割り当てられた公開キーを含む ID XML BLOB を生成します

ピア ID 情報は、 PeerIdentityGetXML を呼び出すことによって取得されます。 このピア ID 情報は、グループの作成者または管理者が、グループへの参加に必要な資格情報を招待 XML BLOB として発行するために使用されます。

ピア ID の詳細については、 Identity Manager API のドキュメントを参照してください

ピア グループ化インフラストラクチャの開始

ピア グループ化 API の関数がアプリケーションによって呼び出される前に、 PeerGroupStartup を呼び出す必要があります。 この関数は、アプリケーションのピア グループ化インフラストラクチャを初期化し、サポートされているバージョンを設定します。

グループ ハンドルの取得

グループに接続して参加を開始するには、ピア グループへのハンドルを取得する必要があります。 次の一覧は、ピア グループに接続する 3 つの方法を示しています。

• PeerGroupCreate を呼び出してピア グループを作成します。これにより、新しいピア グループが初期化され、所有者および唯一の管理者としてピアで有効なハンドルが返されます。
• PeerGroupJoin を呼び出して ピア グループに参加する。 ピア グループに参加するには、ピア グループ管理者から招待を受け取る必要があります。 招待を取得するには、招待を作成する管理者に ID 情報 XML BLOB を送信し、電子メールや FTP などの外部メカニズムによって送信します。 招待とピア ID は PeerGroupJoin に渡され、有効なハンドルがグループに返されます。
• PeerGroupOpen を呼び出して、ピアが以前に参加した ピア グループを開きます。 このような状況では、招待を取得する必要はありません。

上記のいずれかの関数から有効なピア グループ ハンドルを取得したら、新しいハンドルで PeerGroupConnect を呼び出してピア グループに接続できます。

ピア グループ化イベントの登録

ピアがピア グループに参加する前に、ピア グループ イベントにピアを登録する必要があります。 特定のピア イベントに登録するには、 PeerGroupRegisterEvent を呼び出し、PEER_GROUP_EVENT_TYPEで定義されている 1 つ以上のピア イベントの種類を渡します。 アプリケーションに適用されるピア イベントごとに登録する必要があります。たとえば、直接接続を介してデータを受信するには、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 を呼び出します。 pCount パラメーターが要求されたメンバー数より小さい値を返すまで PeerGetNextItem の呼び出しを続けます。 使用可能なメンバーの完全な一覧が返されない場合があることに注意してください。

各メンバーは 、 アクティブなピアのピア、ノード ID、IP アドレスの ID を含むPEER_MEMBER構造体として表されます。

完了したら、列挙を閉じ、 PeerEndEnumeration を呼び出して関連付けられているメモリを解放します。

ピアへの直接接続

ピアがピア グループに接続されている場合は、 PeerGroupOpenDirectConnection を呼び出し、もう一方のピアの ID を指定することで、他の接続されているメンバーとの直接の一対一の交換が開始されます。 この呼び出しは非同期であり、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 を呼び出す必要があります。