Enumerating Hosts

One way to arrange a session is to have session hosts advertise themselves as available. Peers or clients can look for a game to join by enumerating the available hosts, selecting one, and then join the game by sending a connection request. See Peer-to-Peer Sessions or Client/Server Sessions for a detailed discussion.

Unlike other enumerations, the information needed to respond to a request for available hosts is not stored on the local computer. Instead, a client or peer must broadcast a request, for instance on their local subnet, and wait for available hosts to respond. Hosts, on the other hand, must wait for these requests, and then respond appropriately. There are thus two slightly different procedures, depending on whether you are a potential session member, or a session host.

The following procedure illustrates how to enumerate the available hosts for a peer-to-peer session. The procedure for a client/server session is essentially the same. IDirectPlay8Peer::EnumHosts is the method that starts the enumeration. The key parameters to set are pApplicationDesc, pdpaddrDeviceinfo, and pdpaddrHost.

1. Assign the globally unique identifier (GUID) of the game you are interested in playing to the guidApplication member of the DPN_APPLICATION_DESC structure and assign the structure pointer to the pApplicationDesc parameter.
2. Create an address object for your device and assign its pointer to pdpaddrDeviceinfo. This object contains the information needed to make a network connection.
3. To query a specific computer for available hosts, create a host address object for that computer and assign its pointer to pdpaddrHost. If you set this parameter to NULL, Microsoft® DirectPlay® will create an address object from the information contained in pdpaddrDeviceinfo. See DirectPlay Addressing for further discussion of address objects. If you are using an Internet Protocol (IP) or Internetwork Packet Exchange (IPX) service provider, the query will then normally be broadcast to your local subnet. If you set the DPNENUMHOSTS_OKTOQUERYFORADDRESSING flag, the service provider may display a dialog box to the user to request address information.
4. Call IDirectPlay8Peer::EnumHosts.
5. Your callback message handler will then receive a series of DPN_MSGID_ENUM_HOSTS_RESPONSE messages, one for each host that responds.

   Examine the information returned to your message handler, select a session, and ask to join it by calling IDirectPlay8Peer::Connect.

If you want to be the host of a session, advertise yourself as available, and wait for queries or connection requests. The following procedure applies to peer-to-peer hosts, but is essentially similar to the procedure for client/server hosts.

1. Call IDirectPlay8Peer::SetPeerInfo to specify the static settings for your player.
2. Specify the configuration of the game by assigning values the DPN_APPLICATION_DESC structure.
3. Call IDirectPlay8Peer::Host to advertise yourself as a potential host. Set the pdnAppDesc parameter to the DPN_APPLICATION_DESC structure defined in the previous step.
4. Wait for enumeration requests. They will take the form of a DPN_MSGID_ENUM_HOSTS_QUERY message sent to your callback message handler. If you want to respond to the enumeration request, fill in the DPN_APPLICATION_DESC and return S_OK. The peer will receive a DPN_MSGID_ENUM_HOSTS_RESPONSE message with the information.
5. If the peer decides that they would like to join your session, you will receive a DPN_MSGID_INDICATE_CONNECT message.

See the Peer-to-Peer Sessions and Client/Server Sessions sections for further discussion of how to arrange and launch a game.