| Microsoft DirectX 8.1 (C++) |
This topic discusses how to create typical address objects using the IDirectPlay8Address methods for modem 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 on 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® modem service provider.
hr = g_pDeviceAddress->SetSP(&CLSID_DP8SP_MODEM );
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 modem service providers.
If you are creating a device address for the local player and using the modem service provider, you may need to set the device. For a list of other data values you may set, see Data Value Summary. If you do not pass the respective OKTOQUERYFORADDRESSING flag to EnumHosts, Connect, or Host, the device must be specified for the device address.
Use the EnumServiceProviders method to obtain a list of available devices. The following example illustrates how to retrieve a list of available modem devices by calling the EnumServiceProviders method with the pguidServiceProvider parameter set to &CLSID_DP8SP_MODEM.
hr = g_pDP->EnumServiceProviders(&CLSID_DP8SP_MODEM, //pguidServiceProvider
NULL, pSPInfoBuffer, //pguidApplication, pSPInfoBuffer
&dwSize, &dwItems, 0 ); //pcbEnumData, pcReturned, dwFlags
The pSPInfoBuffer parameter is the address of the buffer where DirectPlay places the service provider device information if the call is successful. Typically EnumServiceProviders is called twice, once to retrieve the buffer size required, and again to actually fill in the buffer.
After enumerating the available devices, select a modem device by using the IDirectPlay8Address::AddComponent method as is shown below.
hr = g_pDeviceAddress->AddComponent( DPNA_KEY_DEVICE, //pwszName
pGuid, sizeof(GUID), //lpvData, dwDataSize
DPNA_DATATYPE_GUID); //dwDataType
In this example, pGuid is the address of the globally unique identifier (GUID) that represents the selected modem device.
If you are creating a host address and using the modem service provider, you may need to set the phone number. For a list of other data values you may set, see Data Value Summary. If you do not pass the respective OKTOQUERYFORADDRESSING flag to EnumHosts or Connect, the phone number must be specified for the host address.
The following example illustrates how to set the phone number for a host address using the IDirectPlay8Address::AddComponent method.
hr = pHostAddress->AddComponent( DPNA_KEY_PHONENUMBER, //pwszName
wstrPhone, //lpvData
(wcslen(wstrPhone)+1)*sizeof(WCHAR), //dwDataSize
DPNA_DATATYPE_STRING ); //dwDataType
In this example, wstrPhone contains the phone number of the host to which you will connect.
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.