HOWTO: Set Device Configuration for RAS Phonebook Entry

The information in this article applies to:

• Microsoft Win32 Software Development Kit (SDK) for the following platforms: - Windows 95
• Microsoft Win32 Application Programming Interface (API) included with: - Windows 95

SUMMARY

While many phone book settings are modifiable via the RASENTRY structure, there are many settings that are accessible through the Dial-Up Networking interface that don't have counterparts in the RASENTRY structure. This is because the RAS client uses TAPI to access physical devices (such as modems) and relies on the TAPI Service Provider to configure the device. The dialog box that appears when you click "Configure..." is really implemented by the TAPI Service Provider (TSP) and can vary from TSP to TSP. For more information on this topic, see the lineConfigDialog help page in the Win32 SDK.

This article explains how to programmatically control the device configuration parameters (such as operator-assisted call option) of the Dial-Up Network connection for Windows 95. Windows NT 4.0 does not use the TSP specific configuration information at all, so none of this article applies to Windows NT 4.0.

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;

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.

   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.

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;
    }
    ....