Cómo trabajar con grupos

La agrupación punto a punto es una tecnología que permite a un desarrollador crear una red del mismo nivel segura de forma rápida y eficaz. En la lista siguiente se identifican las consideraciones principales para crear una aplicación de agrupación del mismo nivel.

• Obtención de una identidad del mismo nivel
• Inicio de un grupo del mismo nivel
• Registro para eventos de agrupación
• Conexión a un grupo
• Creación de roles de administrador y miembro
• Buscar un elemento del mismo nivel
• Conexión directa a un elemento del mismo nivel
• Cerrar y cerrar un grupo

Obtención de una identidad del mismo nivel

Antes de crear o conectarse a un grupo, un elemento del mismo nivel debe obtener una identidad del mismo nivel, que es un nombre que se usa para identificar de forma única un elemento del mismo nivel a un grupo. Para obtener una lista enumerada de todas las identidades del mismo nivel definidas en el mismo nivel, llame a PeerEnumIdentities, que devuelve un identificador a la enumeración. Para obtener las identidades del mismo nivel, llame a PeerGetNextItem con el identificador de enumeración y el número de miembros que se van a recuperar. Siga llamando a PeerGetNextItem hasta que el parámetro pCount devuelva un valor menor que el número de identidades del mismo nivel solicitadas.

Si no existe una identidad del mismo nivel para el mismo nivel, se puede crear mediante una llamada a PeerIdentityCreate. Después de crear una identidad del mismo nivel, el mismo nivel genera un blob XML de identidad que contiene la clave pública asignada.

La información de identidad del mismo nivel se obtiene mediante una llamada a PeerIdentityGetXML. El creador del grupo o un administrador usan esta información de identidad del mismo nivel para emitir las credenciales necesarias para unirse al grupo, como un blob XML de invitación.

Para más información sobre las identidades del mismo nivel, consulte la documentación de la API de Identity Manager .

Inicio de la infraestructura de agrupación de emparejamiento

Antes de que una aplicación llame a cualquier función de peer grouping API, se debe llamar a PeerGroupStartup . Esta función inicializa la infraestructura de agrupación del mismo nivel para la aplicación y establece la versión admitida.

Obtención de un identificador de grupo

Para conectarse a un grupo y comenzar a participar, se debe obtener un identificador para un grupo del mismo nivel. En la lista siguiente se identifican las tres maneras de conectarse a un grupo del mismo nivel:

• Para crear un grupo del mismo nivel, llame a PeerGroupCreate, que inicializa un nuevo grupo del mismo nivel y devuelve un identificador válido con el mismo nivel como propietario y administrador único.
• Unirse a un grupo del mismo nivel llamando a PeerGroupJoin. Para unirse a un grupo del mismo nivel, un elemento del mismo nivel debe recibir una invitación de un administrador de grupos del mismo nivel. Para obtener una invitación, envíe el blob XML de información de identidad al administrador que crea una invitación y la envía a usted mediante un mecanismo externo, como correo electrónico o FTP. La invitación y la identidad del mismo nivel se pasan a PeerGroupJoin, que devuelve un identificador válido al grupo.
• Abrir un grupo del mismo nivel al que se ha unido anteriormente llamando a PeerGroupOpen. En esta situación, no es necesario obtener una invitación.

Después de obtener un identificador de grupo del mismo nivel válido de una de las funciones anteriores, puede conectarse a un grupo del mismo nivel llamando a PeerGroupConnect con el nuevo identificador.

Registro de eventos de agrupación del mismo nivel

Antes de que un elemento del mismo nivel participe en un grupo del mismo nivel, el mismo nivel debe registrarse para los eventos del grupo del mismo nivel. Para registrarse para eventos de mismo nivel específicos, llame a PeerGroupRegisterEvent y pase uno o varios de los tipos de eventos del mismo nivel definidos en PEER_GROUP_EVENT_TYPE. Debe registrarse para cada evento del mismo nivel que se aplique a la aplicación; por ejemplo, para recibir datos a través de una conexión directa, regístrese para los eventos de PEER_GROUP_EVENT_DIRECT_CONNECTION y PEER_GROUP_EVENT_INCOMING_DATA. Cada llamada toma un identificador de eventos y devuelve un controlador HPEEREVENT para ese evento del mismo nivel.

Los controladores de eventos pueden obtener los datos asociados a un evento del mismo nivel pasando el identificador a eventos del mismo nivel registrados a PeerGroupGetEventData. Estos datos de eventos del mismo nivel se devuelven como una unión PEER_GROUP_EVENT_DATA. Si la cola de eventos del mismo nivel está vacía, esta función devuelve PEER_S_NO_EVENT_DATA.

Puede anular el registro de los eventos del mismo nivel llamando a PeerGroupUnregisterEvent y proporcionando el identificador para el evento del mismo nivel que desea anular el registro. Después de llamar a la función , los eventos del mismo nivel asociados al identificador ya no se registran.

Creación de roles de administrador y miembro

El elemento del mismo nivel que crea el grupo del mismo nivel se conoce como creador del grupo del mismo nivel y tiene el rol de administrador de forma predeterminada. Solo el creador del grupo del mismo nivel puede establecer las propiedades del grupo.

Los elementos del mismo nivel invitados al grupo del mismo nivel pueden ser un administrador o un miembro. Si el administrador le asigna un rol de administrador que emite la invitación, puede invitar a nuevos miembros al grupo del mismo nivel y, del mismo modo, asignar el rol de administrador a otros miembros.

Los roles de los miembros del grupo del mismo nivel se establecen en las invitaciones que el administrador proporciona a un miembro. Para agregar más administradores, establezca el valor del parámetro pRoles de PeerGroupCreateInvitation en PEER_GROUP_ROLE_ADMIN al crear una invitación.

Los miembros pueden participar en un grupo del mismo nivel, pero no pueden invitar y autorizar nuevos miembros, establecer propiedades de grupo o actualizar o eliminar registros de grupo que no creen específicamente. Para asignar el estado de miembro a un elemento del mismo nivel participante, establezca el valor del parámetro pRoles de PeerGroupCreateInvitation en PEER_GROUP_ROLE_MEMBER al crear una invitación para ese mismo nivel.

Para cambiar el rol de un miembro, se deben emitir nuevas credenciales que contengan el nuevo rol a ese miembro. Para ello, obtenga la estructura PEER_CREDENTIAL_INFO para este miembro de la estructura PEER_MEMBER devuelta por PeerGroupEnumMembers. Cambie el campo pRoles de PEER_CREDENTIAL_INFO al nuevo rol y pase la estructura a PeerGroupIssueCredentials.

Las nuevas credenciales no entrarán en vigor para el elemento del mismo nivel hasta que se conecten al grupo del mismo nivel. Si están conectados actualmente, deben cerrar el grupo y volver a conectarse para obtener las credenciales actualizadas.

Buscar un elemento del mismo nivel

Para obtener una lista enumerada de todos los elementos del mismo nivel que participan en el grupo del mismo nivel, llame a PeerGroupEnumMembers con el identificador de grupo, que devuelve un identificador a la enumeración. Para obtener los miembros, llame a PeerGetNextItem con el identificador de enumeración y el número de miembros que se van a recuperar. Siga llamando a PeerGetNextItem hasta que el parámetro pCount devuelva un valor menor que el número de miembros solicitados. Tenga en cuenta que es posible que no se devuelva la lista completa de miembros disponibles.

Cada miembro se representa como una estructura de PEER_MEMBER , que contiene la identidad del mismo nivel, los identificadores de nodo y las direcciones IP de los elementos del mismo nivel activos.

Cuando termine, cierre la enumeración y libere la memoria asociada llamando a PeerEndEnumeration.

Conexión directa a un elemento del mismo nivel

Cuando un elemento del mismo nivel está conectado a un grupo del mismo nivel, los intercambios directos uno a uno con otros miembros conectados se inician llamando a PeerGroupOpenDirectConnection y proporcionando la identidad del otro elemento del mismo nivel. Esta llamada es asincrónica y devuelve un identificador de conexión de 64 bits. Si la llamada se realiza correctamente, recibirá el PEER_GROUP_EVENT_DIRECT_CONNECTION_EVENT evento del mismo nivel para indicar que la conexión se ha realizado correctamente. Si la conexión se realiza correctamente, el identificador de conexión es válido y se puede usar para enviar y recibir datos a través de la conexión directa.

Para poder recibir conexiones directas, el otro elemento del mismo nivel también debe haberse registrado previamente para el evento del mismo nivel PEER_GROUP_EVENT_DIRECT_CONNECTION.

Para enviar datos a un mismo nivel, llame a PeerGroupSendData con un identificador de conexión válido. Para recibir datos, el otro elemento del mismo nivel debe registrarse para el evento del mismo nivel PEER_GROUP_EVENT_INCOMING_DATA. Del mismo modo, si el elemento del mismo nivel de envío quiere recibir datos a su vez, también debe registrarse para el evento del mismo nivel PEER_GROUP_EVENT_INCOMING_DATA.

Para recibir el conjunto total de conexiones directas actualmente activas con otros elementos del mismo nivel de un grupo, llame a PeerGroupEnumConnections para abrir la enumeración y recorrer en iteración la lista de conexiones mediante PeerGetNextItem.

Para cerrar una conexión directa, llame a PeerGroupCloseDirectConnection y pase el identificador de conexión.

Cerrar y cerrar un grupo del mismo nivel

Para cerrar una conexión a un grupo del mismo nivel, llame a PeerGroupClose, que invalida el identificador de grupo, pero no cierra la infraestructura de agrupación de pares. Los datos de grupo punto a punto se eliminan mediante una llamada a PeerGroupDelete.

Cuando la aplicación termine de usar la infraestructura de agrupación del mismo nivel, debe llamar a PeerGroupShutdown.