Creating TCP/IP Address Objects

This topic discusses how to create typical Address objects using the IDirectPlay8Address methods for Transmission Control Protocol/Internet Protocol (TCP/IP) service providers.

The first step in creating an address object is to call CoCreateInstance to create an IDirectPlay8Address object. The parameters include the class identifier of an address object (CLSID_DirectPlay8Address), the identifier of the interface (IID_IDirectPlay8Address), and the address of a pointer to an IDirectPlay8Address interface. The following example illustrates how to create an address object.

IDirectPlay8Address*  g_pDeviceAddress;
.
.
.
hr = CoCreateInstance( CLSID_DirectPlay8Address, NULL,	
                       CLSCTX_INPROC_SERVER,
                       IID_IDirectPlay8Address,
                       (LPVOID*) &g_pDeviceAddress );

For more information about using CoCreateInstance, see Creating a COM Object.

After creating the address object, you must set the service provider component, at a minimum. To do that, call IDirectPlay8Address::SetSP. The following example illustrates how to set the service provider to the Microsoft® DirectPlay® TCP/IP protocol service provider.

hr = g_pDeviceAddress->SetSP(&CLSID_DP8SP_TCPIP );

The EnumHosts, Connect, and Host methods each have an OKTOQUERYFORADDRESSING flag (DPNENUMHOSTS_OKTOQUERYFORADDRESSING, DPNCONNECT_OKTOQUERYFORADDRESSING, and DPNHOST_OKTOQUERYFORADDRESSING) that allow DirectPlay to prompt the user for any missing information in the address beyond the service provider component. However, for most applications you will want to override these standard dialogs to improve the user experience. The following sections describe the common and required components used for the TCP/IP protocol service providers.

Device Addresses

If you are creating a device address for the local player and using TCP/IP protocol as your service provider, you may also want to set the device port. For a list of other data values you may set, see Data Value Summary.

The following example illustrates how to set the port for a device address using the IDirectPlay8Address::AddComponent method.

DWORD dwPort;
// Set dwPort to the port number for the device address.

hr = g_pDeviceAddress->AddComponent( DPNA_KEY_PORT,           // pwszName
                                   &dwPort, sizeof(dwPort),   // lpvData, dwDataSize
                                   DPNA_DATATYPE_DWORD );     // dwDataType

If you set the port for the player hosting the session, it is recommended that you also set the DPNSESSION_NODPNSVR flag in the DPN_APPLICATION_DESC structure passed in the Host method. However, if you disable DPNSVR, you should do one of the following:

• Specify the host port in the pdpaddrHost parameter when you call EnumHosts.
• Specify the host port in the pHostAddr parameter when you call Connect.

For more information about DPNSVR, see Using the DirectPlay DPNSVR Application.

Host Addresses

If you are creating a host address and using TCP/IP protocol as your service provider, you may need to set the host name address component. For a list of other data values you may set, see Data Value Summary. If you did not use EnumHosts to find a session and do not pass the DPNCONNECT_OKTOQUERYFORADDRESSING flag to Connect, the host name must be specified for the host address.

The following example illustrates how to set the host name for a host address using the IDirectPlay8Address::AddComponent method.

size_t cb;
WCHAR wstrIP[MAX_PATH];
// Set wstrIP to the host IP address
hr = StringCbLengthW(wstrIP, MAX_PATH, &cb);

hr = g_pHostAddress->AddComponent(DPNA_KEY_HOSTNAME,     // pwszName
                                 wstrIP,                 // lpvData
                                 cb,                     // dwDataSize in bytes
                                 DPNA_DATATYPE_STRING ); // dwDataType

In this example, wstrIP contains the Internet Protocol (IP) address or name of the session host in dotted notation, that is, the string "123.123.123.123" or "DirectPlayMaze.rte.microsoft.com".

Similarly, you may need to set the port for the host address. If you set the port component of the device address for the player calling Host, it is recommended that you set the port component of the host address passed in EnumHosts or Connect. If you did not use EnumHosts to find a session's host address and do not pass the DPNCONNECT_OKTOQUERYFORADDRESSING flag, the port must be specified for the host address in order to connect to the session.

The following example illustrates how to set the port for a host address using the IDirectPlay8Address::AddComponent method.

DWORD dwPort;
// Set dwPort to the port number of the host address

hr = g_pHostAddress->AddComponent( DPNA_KEY_PORT,        // pwszName
                                &dwPort, sizeof(dwPort), // lpvData, dwDataSize
                                DPNA_DATATYPE_DWORD );   // dwDataType

After you have created the address objects, you connect to the session by passing the device address in the pDeviceInfo parameter and the host address in the pHostAddr parameter in the Connect method.