| Microsoft DirectX 8.1 (C++) |
Before your application can join a peer-to-peer session, you need the address of the session host. In some cases, lobby-launched applications might give you the host address. With Microsoft® DirectPlay® 8.1, you can use that address to connect to the session. There is no need to enumerate the available hosted sessions. However, if you do not have the address of a session host, you must obtain it by enumerating the available hosted sessions. This tutorial extends Tutorial 2, and discusses how to enumerate available hosts. The complete sample code for this tutorial is included with the Microsoft® DirectX® software development kit (SDK) and can be found at (SDK root)\Samples\Multimedia\DirectPlay\Tutorials\Tut03_EnumHosts.
Refer to the preceding tutorials for a discussion of the initial steps in the process:
Note The error handling code for the examples in this document has been deleted for clarity. See the tutorial sample for a complete version of the code.
When you run this tutorial sample, a Microsoft® MS-DOS® command window opens and you have the choice to either Host or Connect.
If you choose Host, enter a session name. A message prints on the screen telling you that you are "currently hosting."
If you choose Connect, enter an IP address. The application prints all the sessions found at the address on the screen. If the address does not exist, the application prints error messages. If no session is found at the address, the sample ends.
You can run this sample twice—once to host a session and once to connect. When connecting, enter your computer's IP address.
To enumerate hosts, you must basically advertise a description of the type of session that you are interested in, your target address, and the device you perform the enumeration on. You then wait for any available hosts to respond.
You describe your application by assigning values to a DPN_APPLICATION_DESC structure, as discussed in Tutorial 2. Tutorial 2 also describes how to create an address object to contain your address.
To start the host enumeration, pass the DPN_APPLICATION_DESC structure and your address object to IDirectPlay8Peer::EnumHosts. You can specify a host address if you want to direct your enumeration query to a particular address. Otherwise, host enumeration queries are broadcast to every address in your TCP/IP subnet.
The following excerpt from the tutorial sample illustrates how to start enumerating the available hosts at a specified address.
ZeroMemory(&dpAppDesc, sizeof(DPN_APPLICATION_DESC));
dpAppDesc.dwSize = sizeof(DPN_APPLICATION_DESC);
dpAppDesc.guidApplication = g_guidApp;
hr = g_pDP->EnumHosts( &dpAppDesc, // pApplicationDesc
g_pHostAddress, // Host Address
g_pDeviceAddress,// Device Address
NULL, 0, // pvUserEnumData, size
4, // dwEnumCount
0, // dwRetryInterval
0, // dwTimeOut
NULL, // pvUserContext
NULL, // pAsyncHandle
DPNENUMHOSTS_SYNC); // dwFlags
A host receives your query in the form of a DPN_MSGID_ENUM_HOSTS_QUERY message sent to their message handler. The associated structure includes the information that you passed to IDirectPlay8::EnumHosts. After examining this information, the host can respond to your query by returning DPN_OK, or reject the query by returning a different value.
When a host responds affirmatively, your application's message handler receives a DPN_MSGID_ENUM_HOSTS_RESPONSE message. The structure associated with the message contains information describing the session.
The following excerpt from the tutorial sample illustrates how to process a DPN_MSGID_ENUM_HOSTS_RESPONSE message. Essentially, the message handler places the associated structure in a list, to be examined after the enumeration is finished. Refer to the tutorial sample for details.
HRESULT WINAPI DirectPlayMessageHandler( PVOID pvUserContext, DWORD dwMessageId, PVOID pMsgBuffer )
{
.
.
.
switch( dwMessageId )
{
case DPN_MSGID_ENUM_HOSTS_RESPONSE:
{
PDPNMSG_ENUM_HOSTS_RESPONSE pEnumHostsResponseMsg;
const DPN_APPLICATION_DESC* pAppDesc;
HOST_NODE* pHostNode = NULL;
WCHAR* pwszSession = NULL;
pEnumHostsResponseMsg = (PDPNMSG_ENUM_HOSTS_RESPONSE) pMsgBuffer;
pAppDesc = pEnumHostsResponseMsg->pApplicationDescription;
.
.
.
// Copy the Host Address
pEnumHostsResponseMsg->pAddressSender->Duplicate(&pHostNode->pHostAddress)
pHostNode->pAppDesc = new DPN_APPLICATION_DESC;
ZeroMemory(pHostNode->pAppDesc, sizeof(DPN_APPLICATION_DESC));
memcpy(pHostNode->pAppDesc, pAppDesc, sizeof(DPN_APPLICATION_DESC));
When enumeration is finished, the IDirectPlay8::EnumHosts method returns, and your application can decide which session to join.
If a DirectPlay peer object was successfully initialized you should first close the object by calling IDirectPlay8Peer::Close. Then release all active objects and terminate the application. See Tutorial 1 for further discussion.