Direct Connections

The Peer Graphing and Peer Grouping Infrastructures allow applications to connect directly to one node (Graphing) or member (Grouping), and then exchange data directly with the node. This connection is called a direct connection.

Direct Connections using the Peer Graphing Infrastructure

Before a direct connection can be established between two nodes in a graph, both nodes must be registered for the PEER_GRAPH_EVENT_DIRECT_CONNECTION event. To receive data over a direct connection, the nodes must also be registered for the PEER_GRAPH_EVENT_INCOMING_DATA event.

PEER_GRAPH_EVENT_DIRECT_CONNECTION is an event that notifies an application whether or not a direct connection attempt succeeds or fails. The actual success or failure status of a call to PeerGraphOpenDirectConnection is returned in the PEER_GRAPH_EVENT_DATA structure.

To create a direct connection, an application calls PeerGraphOpenDirectConnection, and then passes a handle to the graph, a pointer to the identity of the other node that is participating in the connection, and a pointer to an IPv6 address structure for the participating node. The node identity and IPv6 address that are specified in the call to PeerGraphOpenDirectConnection must be registered for the PEER_GRAPH_EVENT_INCOMING_DATA event, or it cannot receive data sent by a calling peer. When successful, PeerGraphOpenDirectConnection returns a 64-bit connection ID. However, the peer must wait for the PEER_GROUP_EVENT_DIRECT_CONNECTION event before the direct connection ID can be identified as valid.

After a connection is made and a valid connection ID is confirmed, an application can call PeerGraphSendData to send the data across the connection specified by the valid connection ID to the participating peer—if the participating peer is registered for the PEER_GRAPH_EVENT_INCOMING_DATA event. The opaque data is available as a PEER_DATA structure in the PEER_EVENT_INCOMING_DATA returned by the PEER_GRAPH_EVENT_INCOMING_DATA event.

When a connection is not needed, an application calls PeerGraphCloseDirectConnection with the graph handle and the connection ID.

Direct Connections using the Peer Grouping Infrastructure

Direct connections within the Peer Grouping Infrastructure are handled similar to the Peer Graphing Infrastructure.

Before a direct connection can be established between two members in a group, both members must register for the PEER_GROUP_EVENT_DIRECT_CONNECTION event. If a group member wants to receive data over a direct connection, the group member must also register for the PEER_GROUP_EVENT_INCOMING_DATA event.

PEER_GROUP_EVENT_DIRECT_CONNECTION is an event that is an event that notifies an application whether or not a direct connection attempt succeeds or fails. The actual success or failure status of a call to PeerGroupOpenDirectConnection is returned in the PEER_GROUP_EVENT_DATA structure.

To create a direct connection, an application calls PeerGroupOpenDirectConnection, and then passes a handle to the group, a pointer to the identity of the other member that will participate in this connection, and a pointer to an IPv6 address structure for the participating member. The member whose identity and IPv6 address are specified in the call to PeerGroupOpenDirectConnection must be registered for the PEER_GROUP_EVENT_INCOMING_DATA event, or the member cannot receive data sent by a calling peer. PeerGroupOpenDirectConnection returns a 64-bit connection ID when successful. However, a peer must wait for the PEER_GRAPH_EVENT_DIRECT_CONNECTION event to be raised before the direct connection ID can be identified as valid.

After a connection is made and a valid connection ID is confirmed, then an application can call PeerGroupSendData to send data across a connection specified by the valid connection ID to the participating peer—if the participating peer is registered for the PEER_GROUP_EVENT_INCOMING_DATA event. The opaque data is available as a PEER_DATA structure in the PEER_EVENT_INCOMING_DATA returned by the PEER_GROUP_EVENT_INCOMING_DATA event.

When the connection is not needed, the application calls PeerGroupCloseDirectConnection with the group handle and the connection ID.

Example of a Direct Connection for Graphing

#include <p2p.h>

#pragma comment(lib, "p2pgraph.lib")

//-----------------------------------------------------------------------------
// Function: CreateDirectConnection
//
// Purpose:  Demonstrate how to create a direct connection.
//
// Arguments:
//           hGraph - the graph in which to create the connection
//           pwzId  - the peer identification string
//
// Returns:  ULONGLONG - the connection id or 0
//

ULONGLONG CreateDirectConnection(HGRAPH hGraph, PCWSTR pwzId)
{
    HRESULT   hr = S_OK;

    ULONGLONG ullConnection = 0; // the connection id to return

    HPEERENUM hPeerEnum = NULL;
 
    hr = PeerGraphEnumNodes(hGraph, pwzId, &hPeerEnum);

    if (SUCCEEDED(hr))
    {
        ULONG cItem = 1; // want only one matching result

        PEER_NODE_INFO ** ppNodeInfo = NULL;

        hr = PeerGraphGetNextItem(hPeerEnum, &cItem, (PVOID**) &ppNodeInfo);

        if (SUCCEEDED(hr))
        {
            if ((cItem > 0) && (NULL != ppNodeInfo))
            {
                if ((*ppNodeInfo)->cAddresses > 0)
                {
                    hr = PeerGraphOpenDirectConnection(hGraph, pwzId,
                            &(*ppNodeInfo)->pAddresses[0], &ullConnection);
                }
                PeerGraphFreeData(ppNodeInfo);
            }
        }
        PeerGraphEndEnumeration(hPeerEnum);
    }
    return ullConnection;
}