Como se conectar a um grupo de pares

Este tópico discute como um aplicativo se conecta a um grupo de pares usando as APIs de Agrupamento de Pares.

Ingressar em um grupo de pares

Para ingressar em um grupo de pares, chame PeerGroupJoin, passando o nome da identidade do par e o convite (e um nome de nuvem PNRP opcional, se o nome da nuvem no convite for ambíguo).

Se tiver êxito, PeerGroupJoin retornará um identificador para o grupo de pares.

Se o par tiver ingressado anteriormente no grupo de pares e fechado o identificador, o grupo de pares deverá ser reaberto chamando PeerGroupOpen e passando o nome do grupo de pares. Essa chamada retorna um novo identificador de grupo par.

Depois que o grupo de pares for unido com êxito, o par poderá se conectar diretamente ao grupo de pares e começar a interagir chamando PeerGroupConnect. Após a conexão, o par é considerado "online".

Se um aplicativo não interagir com o grupo no momento, ele poderá permanecer "offline". Se ele optar por participar diretamente do grupo de pares em uma instância posterior, uma chamada subsequente para PeerGroupConnect o colocará online. Depois que um par tiver ingressado no grupo de pares, ele deverá se conectar pelo menos uma vez antes de poder publicar registros no grupo de pares.

Abrindo um grupo de pares sem se conectar (offline)

Muitas vezes, talvez você queira que um aplicativo se conecte a um grupo de pares, mas não participe diretamente dele, recebendo e publicando atualizações de registro, mas não enviando ou recebendo mensagens de dados. Um aplicativo está nesse estado "offline" imediatamente após PeerGroupCreate, PeerGroupJoin ou PeerGroupOpen terem sido chamados.

Um aplicativo offline pode ficar online a qualquer momento chamando PeerGroupConnect. Uma vez conectado, um grupo de pares não pode ficar offline até que todos os outros aplicativos associados a essa identidade e compartilhamento desse grupo também tenham conexões fechadas com ele.

Um grupo de pares é um recurso compartilhado, com o mesmo grupo de pares disponível para vários aplicativos. Se mais de um aplicativo para a mesma identidade e o usuário do Windows estiver usando o mesmo grupo de pares, ele também compartilhará o mesmo banco de dados e conexões subjacentes (vizinho e direto). Se qualquer um desses aplicativos chamar PeerGroupConnect, todos os outros aplicativos dessa identidade/usuário que participam do grupo também se conectarão ao grupo. Se um registro for adicionado por um aplicativo enquanto o grupo estiver offline, outros aplicativos também poderão vê-lo. Como resultado, um aplicativo deve estar pronto para ficar online a qualquer momento.

Conectando-se a um grupo de pares (online)

Para começar a participar de um grupo, chame PeerGroupConnect depois de criar, ingressar ou abrir o grupo. Nesse estado, as conexões diretas podem ser abertas com outros pares que participam do mesmo grupo chamando PeerGroupOpenDirectConnection.

Para detectar se uma tentativa de conexão falhou, registre-se para o evento PEER_GROUP_EVENT_CONNECTION_FAILED. Esse evento será gerado se a infraestrutura de agrupamento não puder encontrar outro membro ao qual se conectar ou se a conexão falhar antes que o banco de dados de grupo seja sincronizado e outra conexão não possa ser estabelecida.

Embora vários aplicativos em execução no par e participando do mesmo grupo com a mesma identidade de par possam estar offline, uma chamada para PeerGroupConnect por qualquer um dos aplicativos resulta em todos os aplicativos ficando online.

Além disso, se um aplicativo no par tiver se conectado ao grupo, todos os outros aplicativos que chamam PeerGroupJoin ou PeerGroupOpen também serão conectados imediatamente. Se um aplicativo chamar PeerGroupClose, o identificador será fechado somente para esse aplicativo. Portanto, uma chamada subsequente para PeerGroupOpen pelo aplicativo retorna um novo identificador de grupo e o aplicativo é colocado online imediatamente se outros aplicativos que participam do mesmo grupo ainda estiverem conectados.

Enviando e recebendo dados

Para enviar e receber dados entre nós de membro específicos no grupo, as conexões diretas devem ser estabelecidas com os membros com os quais você pretende interagir. Estabelecer uma conexão direta é uma chamada assíncrona para PeerGroupOpenDirectConnection, passando o identificador para um grupo conectado, bem como a identidade do par dentro do grupo ao qual você deseja se conectar. Esse método retornará uma ID de conexão. Se a chamada for bem-sucedida, um evento PEER_GROUP_EVENT_DIRECT_CONNECTION será gerado no par, validando a ID da conexão.

Para receber conexões diretas de outros pares online, registre-se para o evento PEER_GROUP_EVENT_DIRECT_CONNECTION com uma chamada para PeerGroupRegisterEvent.

Depois que uma conexão direta tiver sido estabelecida com êxito, o aplicativo poderá começar a enviar dados com chamadas para PeerGroupSendData, passando a ID de conexão válida. A ordenação de transmissões de dados de várias partes é tratada por PeerGroupSendData. No entanto, os aplicativos devem implementar uma pilha de protocolo adequada para lidar com os dados opacos retornados por essa chamada à API.

Para receber dados por meio de uma conexão direta, o aplicativo deve se registrar para o evento PEER_GROUP_EVENT_INCOMING_DATA com PeerGroupRegisterEvent. O manipulador de eventos é responsável por obter e ordenar os dados opacos e passá-los para o aplicativo. Esses dados são obtidos dentro do manipulador de eventos chamando PeerGroupGetEventData com o identificador para os eventos registrados.

Uma conexão direta é fechada chamando PeerGroupCloseDirectConnection e passando a ID de conexão obtida por uma chamada anterior para PeerGroupOpenDirectConnection ou recebida nos dados do evento para PEER_EVENT_GROUP_DIRECT_CONNECTION.