How To Set Device Configuration for RAS Phonebook Entry

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:

1. 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.
2. Get the driver specific information for that particular entry with the RasGetEntryProperties() API.
3. Change only the desired fields in the DEVCFG structure.
4. 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;
    }
    ....