Creating IPX Address Objects

This topic discusses how to create typical address objects using the IDirectPlay8Address methods for Internetwork Packet Exchange (IPX) 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® IPX service provider.

 hr = g_pDeviceAddress->SetSP(&CLSID_DP8SP_IPX );

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 IPX service providers.

Device Addresses

If you are creating a device address for the local player and using IPX 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.

Host Addresses

If you are creating a host address and using IPX 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, 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 wstrIPX[MAX_PATH];
// Set wstrIPX to the host IPX address
hr = StringCbLengthW(wstrIPX, MAX_PATH, &cb);

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

In this example, pwszHost contains the IPX network and node number of the session host. If you were to use (hexadecimal) network 2702 and node 00-02-B3-10-87-64, the host name string would be "00002702,0002B3108764".

Similarly, you may need to set the port for the host address. If you set the port for the device address of the player who is hosting, it is recommended that you set the port for the host address passed in EnumHosts or Connect. If you did not use EnumHosts to find a session's host address, 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.