| Microsoft DirectX 9.0 SDK Update (Summer 2003) |
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.
If you are creating a device address for the local player and using the serial service provider, you need to set the following components.
For a list of other data values you may set, see Data Value Summary.
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.
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.
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.
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.
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.
Serial host addresses do not need to contain any additional information beyond the serial provider component.