Edit

Share via

Working with Graphs

  • Article

When working with peer graphs, functions must be called in a specific order. The flow of calls depends on whether you are creating or opening a peer graph. This topic identifies the flow of function calls in a simple peer graph application.

Starting Up a Graph

Before an application calls a function in the Peer Graphing API, PeerGraphStartup must be called to initialize the Peer Graphing API for an application, and then set the supported version.

Creating a Peer Graph

The following procedure identifies the flow of calls for creating a peer graph.

Important

Only one peer should call PeerGraphCreate. All other peers should call PeerGraphOpen. Multiple calls to PeerGraphCreate invalidate a graph.

 

  • Create a peer graph. Call PeerGraphCreate.

  • Register for peer events. Call PeerGraphRegisterEvent.

    Note

    For more information about registering for peer events, see Events Infrastructure.

     

  • Listen for connections to a peer graph. Call PeerGraphListen.

  • Perform application-dependent functions for the remainder of the running time, for example, process peer events and work with connections.

  • Close the connection to a peer graph. Call PeerGraphClose.

Opening a Peer Graph

The flow of function calls to open a peer graph depends on the return value of the call to PeerGraphOpen. The most important values are S_OK and PEER_S_DATA_CREATED, which are explained in the following sections of this topic.

Note

If a call to PeerGraphOpen does not return S_OK or PEER_S_DATA_CREATED, handle the error.

 

When PeerGraphOpen Returns S_OK

When a call to PeerGraphOpen returns S_OK, a peer graph and an existing database have been opened. The following procedure identifies what you can do to open a peer graph when a call to PeerGraphOpen returns S_OK

  • Register for peer events. Call PeerGraphRegisterEvent.

    Note

    For more information about registering for events, see Events Infrastructure.

     

  • Locate a node. This is a process performed outside of the Peer Graphing Infrastructure, by using a method or application that you identify. The Peer Graphing API does not provide a specific mechanism to find an initial graph node to connect to. An application must use another mechanism, such as the Peer Name Resolution Protocol (PNRP) API, to locate the initial node.

  • If a node is found, connect to it. Call PeerGraphConnect, then call PeerGraphListen to listen for connections to the peer graph.

    Note

    If a node is not found, do not call PeerGraphConnect and PeerGraphListen.

     

  • Perform application-dependent functions for the remainder of the running time, for example, process peer events and work with connections, depending on whether the node is connected to the peer graph or not. For example, the application can choose to timeout or periodically perform discovery for an active node in the graph.

  • Close the connection to the peer graph. Call PeerGraphClose.

When PeerGraphOpen Returns PEER_S_DATA_CREATED

When PeerGraphOpen returns PEER_S_DATA_CREATED, it means that an existing database for a peer graph is not found, a new database is created, and this is the first time it is opened. To use or listen on a peer graph, a peer must be connected to and synchronized with a peer graph.

The following procedure identifies what you can do to open a peer graph when a call to PeerGraphOpen returns PEER_S_DATA_CREATED.

  • Open a peer graph. Call PeerGraphOpen.

  • Register for peer events. Call PeerGraphRegisterEvent.

    Note

    For more information about registering for peer events, see Events Infrastructure.

     

  • Locate a node. This is a process performed outside of the Peer Graphing Infrastructure, by using a method or application that you identify. The Peer Graphing API does not provide a specific mechanism to find an initial graph node to connect to. An application must use another mechanism, such as the Peer Name Resolution Protocol (PNRP) API, to locate the initial node.

  • If a node is found, connect to it. Call PeerGraphConnect, then call PeerGraphListen to listen for connections to the peer graph.

    Note

    If a node is not found, do not call PeerGraphConnect and PeerGraphListen.

     

  • Perform application-dependent functions for the remainder of the running time, for example, process peer events and work with connections, depending on whether the node is connected to the peer graph or not. For example, the application can choose to timeout or periodically perform discovery for an active node in the graph.

  • Close the connection to the peer graph. Call PeerGraphClose.