Infraestrutura de eventos de pares

Artigo
06/13/2023

A Infraestrutura de Pares usa eventos para notificar aplicativos de alterações que ocorreram em uma rede par, por exemplo, um nó que é adicionado ou removido de um grafo. As infraestruturas de emparelhamento gráfico e agrupamento de pares usam a infraestrutura de eventos de pares.

Recebendo notificação de evento par

Um par pode se registrar para receber notificação quando um atributo de um grafo ou grupo é alterado ou ocorre um evento par específico. Um aplicativo par chama a função PeerGraphRegisterEvent ou PeerGroupRegisterEvent e passa um identificador de evento para a Infraestrutura de Pares, que é criada anteriormente por uma chamada para CreateEvent. A Infraestrutura de Pares usa o identificador para sinalizar a um aplicativo que ocorreu um evento par.

O aplicativo também passa uma série de estruturas de PEER_GRAPH_EVENT_REGISTRATION ou PEER_GROUP_EVENT_REGISTRATION que indicam à Infraestrutura de Pares os eventos par específicos para os quais o aplicativo está solicitando notificação. O aplicativo também deve especificar exatamente quantas estruturas estão sendo passadas.

Eventos de grafo de pares

Um aplicativo de Grafo de Pares pode se registrar para receber uma notificação de 9 eventos de grafo par. Cada nome de evento é precedido por PEER_GRAPH_EVENT_, por exemplo, PEER_GRAPH_STATUS_CHANGED. A menos que indicado de outra forma, as informações sobre uma alteração são recuperadas usando PeerGraphGetEventData.

PEER_GRAPH_EVENT_STATUS_CHANGED indica que o status de um grafo foi alterado, por exemplo, um nó foi sincronizado com um grafo.
PEER_GRAPH_EVENT_PROPERTY_CHANGED indica que uma propriedade de um grafo ou grupo foi alterada, por exemplo, o nome amigável de um grafo foi alterado.

Observação

O aplicativo deve chamar PeerGraphGetProperties para obter as informações alteradas.
PEER_GRAPH_EVENT_RECORD_CHANGED indica que um registro foi alterado, por exemplo, um registro é excluído.
PEER_GRAPH_EVENT_DIRECT_CONNECTION indica que uma conexão direta foi alterada, por exemplo, um nó conectado.
PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION indica que uma conexão com um nó vizinho foi alterada, por exemplo, um nó foi conectado.
PEER_GRAPH_EVENT_INCOMING_DATA indica que os dados foram recebidos de uma conexão direta ou vizinha.
PEER_GRAPH_EVENT_CONNECTION_REQUIRED indica que a Infraestrutura de Grafo requer uma nova conexão.

Observação

Uma chamada para PeerGraphConnect conecta-se a um novo nó. Uma chamada para PeerGraphGetEventData não retorna dados.
PEER_GRAPH_EVENT_NODE_CHANGED indica que as informações de presença do nó foram alteradas, por exemplo, um endereço IP foi alterado.
PEER_GRAPH_EVENT_SYNCHRONIZED indica que um tipo de registro específico está sincronizado.

Depois que um aplicativo recebe a notificação de que ocorreu um evento par, o aplicativo chama PeerGraphGetEventData e passa o identificador de evento par retornado por PeerGraphRegisterEvent. A Infraestrutura de Pares retorna um ponteiro para uma estrutura PEER_GRAPH_EVENT_DATA que contém os dados solicitados. Essa função deve ser chamada até que PEER_S_NO_EVENT_DATA seja retornado.

Depois que um aplicativo não requer uma notificação de evento par, o aplicativo chama PeerGraphUnregisterEvent e passa o identificador de evento par retornado por PeerGraphRegisterEvent quando o aplicativo é registrado.

Manipulando indicações de conexão do Graph

Quando PeerGraphConnect é chamado, o par de conexão é notificado de êxito ou falha por meio do evento assíncrono PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION . Se a conexão falhar devido a problemas de rede específicos (como um firewall configurado incorretamente), o evento PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION será gerado, com a conexão status definida como PEER_CONNECTION_FAILED.

No entanto, quando um par recebe uma indicação quando tenta se conectar a um nó ocupado, o PEER_GRAPH_EVENT_NEIGHBOR_CONNECTION é gerado no par de conexão, com a conexão status definida como PEER_CONNECTION_FAILED. O par de conexão pode ser referenciado a outro nó que está ocupado e pode enviar uma indicação, e o mesmo evento e status são gerados no par de conexão. Essa cadeia de indicações que resultam em PEER_CONNECTION_FAILED status de evento pode continuar até que o número máximo de tentativas de conexão seja esgotado. O par não tem um mecanismo para determinar a diferença entre uma tentativa de conexão completa e a indicação de conexão.

Para resolver esse problema, os desenvolvedores devem considerar o uso do grafo par status eventos de alteração para determinar se a tentativa de conexão suceeded. Se o evento não for recebido dentro de um período específico, o aplicativo poderá assumir que o par de conexão está sendo referenciado e que o aplicativo par deve considerar a tentativa de conexão uma falha.

Eventos de agrupamento de pares

Um aplicativo de Agrupamento de Pares pode se registrar para receber uma notificação de 8 eventos pares. Cada nome de evento é precedido por PEER_GROUP_EVENT_; por exemplo, PEER_GROUP_EVENT_STATUS_CHANGED. A menos que indicado de outra forma, as informações sobre uma alteração são recuperadas usando PeerGroupGetEventData.

PEER_GROUP_EVENT_STATUS_CHANGED indica que o grupo status foi alterado. Há dois valores status possíveis: PEER_GROUP_STATUS_LISTENING, que indica que o grupo não tem conexões e está aguardando novos membros; e PEER_GROUP_STATUS_HAS CONNECTIONS, o que indica que o grupo tem pelo menos uma conexão. Esse valor de status pode ser obtido chamando PeerGroupGetStatus depois que esse evento é gerado.
PEER_GROUP_EVENT_PROPERTY_CHANGED indica que as propriedades do grupo foram alteradas ou atualizadas pelo criador do grupo.
PEER_GROUP_EVENT_RECORD_CHANGED indica que uma operação de registro foi executada. Esse evento é gerado quando um par que participa do grupo publica, atualiza ou exclui um registro. Por exemplo, esse evento é gerado quando um aplicativo de chat envia uma mensagem de chat.
PEER_GROUP_EVENT_MEMBER_CHANGED indica que a status de um membro no grupo foi alterada. As alterações de status incluem:
- PEER_MEMBER_CONNECTED. Um par se conectou ao grupo.
- PEER_MEMBER_DISCONNECTED. Um par se desconectou do grupo.
- PEER_MEMBER_JOINED. Novas informações de associação foram publicadas para um par.
- PEER_MEMBER_UPDATED. Um par foi atualizado com novas informações, como um novo endereço IP.
PEER_GROUP_EVENT_NEIGHBOR_CONNECTION. Os pares que participarão de conexões vizinhas dentro do grupo devem se registrar para esse evento. Observe que o registro para esse evento não permite que o par receba dados; O registro desse evento só garante a notificação quando uma solicitação para uma conexão vizinha é recebida.
PEER_GROUP_EVENT_DIRECT_CONNECTION. Os pares que participarão de conexões diretas dentro do grupo devem se registrar para esse evento. Observe que o registro para esse evento não permite que o par receba dados; O registro desse evento só garante a notificação quando uma solicitação de uma conexão direta é recebida.
PEER_GROUP_EVENT_INCOMING_DATA. Os pares que receberão dados por meio de uma conexão direta ou vizinha devem se registrar para esse evento. Quando esse evento é gerado, os dados opacos transmitidos pelo outro par participante podem ser obtidos chamando PeerGroupGetEventData. Observe que, para receber esse evento, o par deve ter se registrado anteriormente para PEER_GROUP_EVENT_DIRECT_CONNECTION ou PEER_GROUP_EVENT_NEIGHBOR_CONNECTION.
PEER_GROUP_EVENT_CONNECTION_FAILED. Uma conexão falhou por algum motivo. Nenhum dado é fornecido quando esse evento é gerado e PeerGroupGetEventData não deve ser chamado.

Depois que um aplicativo recebe a notificação de que ocorreu um evento par (excluindo PEER_GROUP_EVENT_CONNECTION_FAILED), o aplicativo chama PeerGroupGetEventData e passa o identificador de evento par retornado por PeerGroupRegisterEvent. A Infraestrutura de Pares retorna um ponteiro para uma estrutura PEER_GROUP_EVENT_DATA que contém os dados solicitados. Essa função deve ser chamada até que PEER_S_NO_EVENT_DATA seja retornado. Quando um aplicativo não requer mais notificação para um evento par, uma chamada deve ser feita para PeerGroupUnregisterEvent, passando o identificador de evento par retornado por PeerGroupRegisterEvent quando o aplicativo registrado para o evento específico.

Exemplo de registro para eventos de grafo de pares

O exemplo de código a seguir mostra como registrar-se com os eventos do Peer Graphing.

//-----------------------------------------------------------------------------
// Function: RegisterForEvents
//
// Purpose:  Registers the EventCallback function so it can be called for only
//           the events that are specified.
//
// Returns:  HRESULT
//
HRESULT RegisterForEvents()
{
    HPEEREVENT  g_hPeerEvent = NULL;        // The one PeerEvent handle
    HANDLE      g_hEvent = NULL;            // Handle signaled by Graphing when we have an event
    HRESULT hr = S_OK;
    PEER_GRAPH_EVENT_REGISTRATION regs[] = {
        { PEER_GRAPH_EVENT_RECORD_CHANGED, 0 },
        { PEER_GRAPH_EVENT_NODE_CHANGED,   0 },
        { PEER_GRAPH_EVENT_STATUS_CHANGED, 0 },
        { PEER_GRAPH_EVENT_DIRECT_CONNECTION, 0 },
        { PEER_GRAPH_EVENT_INCOMING_DATA, 0 },
    };

    g_hEvent = CreateEvent(NULL, FALSE, FALSE, NULL);
    if (g_hEvent == NULL)
    {
        wprintf(L"CreateEvent call failed.\n");
        hr = E_OUTOFMEMORY;
    }
    else
    {
        hr = PeerGraphRegisterEvent(g_hGraph, g_hEvent, celems(regs), regs,  &g_hPeerEvent);
        if (FAILED(hr))
        {
           wprintf(L"PeerGraphRegisterEvent call failed.\n");
            CloseHandle(g_hEvent);
            g_hEvent = NULL;
        }
    }

    if (SUCCEEDED(hr))
    {
        if (!RegisterWaitForSingleObject(&g_hWait, g_hEvent, EventCallback, NULL, INFINITE, WT_EXECUTEDEFAULT))
        {
            hr = HRESULT_FROM_WIN32(GetLastError());
            wprintf(L"Could not set up event callback.\n");
            CloseHandle(g_hEvent);
            g_hEvent = NULL;
        }
    }

    return hr;
}

Compartilhar via