Creating Serial Address Objects

This topic discusses how to create typical address objects using the IDirectPlay8Address methods for serial 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® serial service provider.

hr = g_pDeviceAddress->SetSP(&CLSID_DP8SP_SERIAL );

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

Device Addresses

If you are creating a device address for the local player and using the serial service provider, you need to set the following components.

• baud
• stop bits
• parity
• flow control
• device (depends on your setup)

For a list of other data values you may set, see Data Value Summary.

Baud

The following example illustrates how to set the baud rate using the IDirectPlay8Address::AddComponent method.

DWORD dwBaudRate;
//  Set dwBaudRate

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

In this example, the dwBaudRate variable can contain any of the DPNA_BAUD_RATE constants defined in dpaddr.h.

Stop bits

The following example illustrates how to set the stop bits using the IDirectPlay8Address::AddComponent method.

size_t cb;
hr = StringCbLengthW(DPNA_STOP_BITS_ONE, MAX_PATH, &cb);

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

In this example, the stop bits setting is 1, as indicated by the use of the DPNA_STOP_BITS_ONE constant defined in dpaddr.h.

Parity

The following example illustrates how to set the parity using the IDirectPlay8Address::AddComponent method.

size_t cb;
hr = StringCbLengh(DPNA_PARITY_NONE, MAX_PATH, &cb);

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

In this example, the parity setting is none, as indicated by the use of the DPNA_PARITY_NONE constant defined in dpaddr.h.

Flow Control

The following example illustrates how to set the flow control using the IDirectPlay8Address::AddComponent method.

size_t cb;
hr = StringCbLengh(DPNA_FLOW_CONTROL_RTSDTR, MAX_PATH, &cb);

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

In this example, the flow control is set to RTS/DTR, as indicated by the use of the DPNA_FLOW_CONTROL_RTSDTR constant defined in dpaddr.h.

Device

You may need to set the device if you do not pass the respective OKTOQUERYFORADDRESSING flag to EnumHosts, Connect, or Host.

Use the EnumServiceProviders method to obtain a list of available devices. The following example illustrates how to retrieve a list of available serial devices by calling the EnumServiceProviders method with the pguidServiceProvider parameter set to CLSID_DP8SP_SERIAL.

DWORD dwSize;
DWORD dwItems;
PDPN_SERVICE_PROVIDER_INFO pSPInfoBuffer;

hr = g_pDP->EnumServiceProviders(&CLSID_DP8SP_SERIAL,       //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 serial device by using the IDirectPlay8Address::AddComponent method as is shown below.

GUID pGuid;
//  Set pGuid

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 serial device.

Host Addresses

Serial host addresses do not need to contain any additional information beyond the serial provider component.