HOWTO: Set Device Configuration for RAS Phonebook Entry

ID: Q163236

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;

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

Additional query words:

Keywords          : kbnetwork kbAPI kbRAS kbSDKPlatform kbTAPI kbCodeSam Tapi kbGrpNet 
Platform          : WINDOWS
Issue type        : kbhowto

Last Reviewed: August 6, 1998