| Microsoft DirectX 8.1 (C++) |
This topic discusses how to create typical Address objects using the IDirectPlay8Address methods for 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.
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 DirectPlay TCP/IP 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 Microsoft® 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 service providers.
If you are creating a device address for the local player and using TCP/IP 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.
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:
If you are creating a host address and using TCP/IP 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.
hr = g_pHostAddress->AddComponent(DPNA_KEY_HOSTNAME, //pwszName
pwszHost, //lpvData
2*(wcslen(pwszHost) + 1), //dwDataSize in bytes
DPNA_DATATYPE_STRING ); //dwDataType
In this example, pwszHost contains the 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.
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.