MORE INFORMATION
The TAPI Service Provider Microsoft ships with Windows 95 is known as
Unimodem (short for Universal Modem driver). While the TAPI data structures
described in this article only apply to the Microsoft Unimodem driver,
third party TSPs may be Unimodem compatible and may use the same
structures.
You can create a new Dial-Up phone book entry or modify the TAPI properties
of the existing entry with the RasSetEntryProperties() API. The fifth
parameter of this API is LPBYTE lpbDeviceInfo. This is a pointer to a
buffer that contains device-specific configuration information. While this
buffer is normally "black box" service provider information, in the case of
the Unimodem driver, this buffer contains a DEVCFG structure which is
defined as follows:
// Device setting information.
typedef struct tagDEVCFGDR {
DWORD dwSize;
DWORD dwVersion;
WORD fwOptions;
WORD wWaitBong;
} DEVCFGHDR;
typedef struct tagDEVCFG {
DEVCFGHDR dfgHdr;
COMMCONFIG commconfig;
} DEVCFG, *PDEVCFG, FAR* LPDEVCFG;
To find more information on this structure, query on "comm/datamodem" in
Microsoft Developer Network or in the Win32 SDK documentation. DEVCFG is a
complex structure that consists of many other structures and some driver
specific information fields. Follow these steps when you create new Dial-Up
phone book entries:
- Create a new phonebook entry with the default TAPI parameters, that is,
set the fifth parameter to of the RasSetEntryProperties() API to NULL.
Make sure the RASENTRY.szDeviceType == RASDT_Modem == "modem" and
RASENTRY.szDeviceName contains the name of a valid device.
- Get the driver specific information for that particular entry with the
RasGetEntryProperties() API.
- Change only the desired fields in the DEVCFG structure.
- Save the entry again with RasSetEntryProperties() API.
The fwOption field of DEVCFGHDR controls the following properties of the
entry via the setting of bit fields:
TERMINAL_PRE (0x00000001) Displays the pre-terminal screen.
TERMINAL_POST (0x00000002) Displays the post-terminal screen.
MANUAL_DIAL (0x00000004) Allows manual Dialing, if possible.
LAUNCH_LIGHTS (0x00000008) Displays the modem tray icon.
Many more serial port specific parameters (such as parity, flow control,
etc.) are set via the "dcb" structure field, which is nested in the
"commconfig" field of the DEVCFG. Please see the Win32 SDK documentation
for the COMMCONFIG structure.
NOTE: The COMMCONFIG structure has several dwProvider* variables. As stated
in the documentation: "If the provider subtype is PST_MODEM, the
wcProviderData member contains a MODEMSETTINGS structure." This is very
important because the modem specific settings, such as speaker mode and
volume, are set in the MODEMSETTINGS structure.
The following code shows how to set the Manual Dial property of the
existing Dial-Up entry "My Entry" in the RAS phonebook.
...
RASENTRY Info = {0};
PDEVCFG pDevCfg;
DWORD dwSize, dwDevInfo;
dwSize = Info.dwSize = sizeof (RASENTRY);
dwDevInfo = 0;
// First find out the size of the device-specific structure.
// This call will fail, but dwDevInfo will return the correct size.
RasGetEntryProperties (NULL, "My Entry", (BYTE *) &Info,
&dwSize, NULL, &dwDevInfo );
if (! (pDevCfg = (LPDEVCFG) LocalAlloc (LPTR, dwDevInfo ) ) )
{
printf ("LocalAlloc error: %d", GetLastError());
return 0;
}
if (code = RasGetEntryProperties (NULL, "My Entry", (BYTE *) &Info,
&dwSize, (LPBYTE) pDevCfg, &dwDevInfo ))
{
printf ("RasGetEntryProperties failed: %d\n", code);
return 0;
}
// Verify that the TAPI provider used is the correct version of the
// Unimodem driver. Check the size of the structure, version. and
// provider sub-type.
if ( ( ( pDevCfg->dfgHdr).dwSize < sizeof (DEVCFG) ) ||
( ( pDevCfg->dfgHdr).dwVersion != 0x00010003) ||
( (pDevCfg->commconfig).dwProviderSubType != PST_MODEM) )
{
printf ("TAPI provider is not UNIMODEM\n");
return 0;
}
// Set the "Manual Dial" bit flag.
(pDevCfg->dfgHdr).fwOptions |= 4;
if (code = RasSetEntryProperties (NULL, "My Entry", (BYTE *) &Info,
dwSize, (LPBYTE) pDevCfg, dwDevInfo))
{
printf ("RasSetEntryProperties failed: %d\n", code);
return 0;
}
....