Creating Modem Address Objects

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.

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® 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.

Device Addresses

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.

DWORD dwSize;
DWORD dwItems;
PDPN_SERVICE_PROVIDER_INFO pSPInfoBuffer;

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.

GUID pGuid;
//  Set pGuid to the GUID of the modem device.

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.

Host Addresses

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.

size_t cb;
WCHAR wstrPhone[MAX_PATH];
//  Set wstrPhone to the phone number of the host address
hr = StringCbLengthW(wstrPhone, MAX_PATH, &cb);

hr = pHostAddress->AddComponent( DPNA_KEY_PHONENUMBER,                 //pwszName
                                 wstrPhone,                            //lpvData
                                 cb,                                   //dwDataSize in bytes
                                 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.