HOWTO: Windows 95 and Windows 98 Session Management Modules (268359)

MORE INFORMATION

1. Overview

Dial-Up Networking uses Session Management Modules to abstract the interface that is presented by the dial-up server. This allows new modules and drivers to be "plugged in" as necessary to support new servers.

Microsoft Windows 95 has built-in support for four Session Management Modules; Point-to-Point Protocol (PPP), Remote Access Service (RAS), Netware Connect, and Serial Line Internet Protocol (SLIP).

Windows 95 Session Management Modules can also "overlay" other Session Management Modules, which allows such features as scripting and security to be added to the product.

2. Session Management Module Overlays

2.1. Overview

Windows 95 and Windows 98 Dial-Up Networking provides four built-in Session Management Modules (SMMs):

• Point-to-Point Protocol (PPP) Session Management Module for Windows 95 and Windows 98, Windows NT 3.5, and Internet providers.
• Remote Access Service (RAS) Session Management Module for Windows for Workgroups and Windows NT 3.1.
• Netware Connect Session Management.
• SLIP and CSLIP protocols for Unix connections.

However, in some dial-up environments, extra steps may be required to set up the dial-up session. Windows 95 and Windows 98 Dial-Up Networking allows a third-party developer to provide these steps in a separate Session Management Module, referred to as a "Session Management Module Overlay," in addition to the default or other Session Management Modules, referred to as "Overlaid Session Management Modules."

An overlaying Session Management Module is implemented and installed as a stand-alone SMM dynamic-linked library (DLL) (please see the third article of this series for installation details). Dial-Up Networking and users see it as an additional SMM (or Dial-Up Server type) and associate it with the connection. However, when Dial-Up Networking requests the overlaying SMM to configure and manage the session, it may choose to perform additional steps or fail the configuration before handing off the control to the overlaid SMM. Once the hand-off occurs, the overlaying SMM no longer controls the session. All the interactions occur directly between Dial-Up Networking and the overlaid SMM.

2.2. Setting Up the Session Management Module Overlay

The overlaying SMM can be installed for Windows 95 or Windows 98 Dial-Up Networking as an external SMM. Dial-Up Networking treats the overlaying SMM as a separate SMM from the one it overlays. You can choose to use the overlaying SMM by doing the following:

1. Open the Connection icon's Property pages.
2. Click the Server type page.
3. Select the overlaying SMM from the Dial-Up Server type list.

2.3. Loading the Session Management Module Overlay

When Dial-Up Networking completes the physical connection, it loads the overlaying SMM to manage the session. Only the Dial-Up Networking process attaches to the overlaying SMM DLL. At load time, the overlaying SMM DLL's entry point is notified that the Dial-Up Networking process is attaching to the DLL. The SMM's process-attach handler should allocate resources and initialize the internal data structure as necessary.

In the sample overlay SMM provided with the DDK, the sample SMM initializes the list for the session control block, which maintains the active session, and the list for the overlaid SMM control block, which maintains the overlaid SMM module handle and the Session Management Interface entries.

2.4. Overview of the Session Management Interface

2.4.1. RnaSessInitialize

The RnaSessInitialize function is called by Dial-Up Networking to allow the SMM to initialize and prepare itself for managing the session. The overlaying SMM should do the following during this function:

1. Call the RnaGetOverlaidSMM function to obtain the path of the SMM it is overlaying for the specified SMM type.
2. Load the DLL of the SMM it is overlaying by using the LoadLibrary function.
3. Use the GetProcAddress function to get the address of the RnaSessInitialize function from the overlaid SMM.
4. Call the overlaid SMM's RnaSessInitialize function to obtain the dispatch function table. The function table contains the entry points to start and stop functions.
5. Return the entry points to the start (RnaSessStart) and stop (RnaSessStop) functions for the overlaying DLL.

In the sample overlay SMM, the overlaying SMM calls the RnaGetOverlaidSMM function and the LoadLibrary function to load the DLL. If the DLL can be loaded, the overlaying SMM gets the entry point for the RnaSessInitialize function from the overlaid SMM and makes a call to it. If the function succeeds, it allocates an overlaid SMM control block to maintain the overlaid SMM module handle and the Session Management Interface entries returned from the RnaSessInitialize call. Finally, the overlaying SMM returns the entry points to its RnaSessStart and RnaSessStop functions (SMMSessStart and SMMSessStop, respectively) to Dial-Up Networking.

2.4.2. RnaSessGetErrorStringEx

The RnaSessGetErrorStringEx function is called when Dial-Up Networking wants to get the displayable error string for the messages resource ID returned to Dial-Up Networking in the RnaComplete call. The overlaying SMM should do the following during this function:

• If the overlaying SMM passes a message resource ID when it makes the RnaComplete call to Dial-Up Networking, it needs to return its own error string that corresponds to the message ID.
• If the overlaying SMM does not call RnaComplete, it means the overlaid SMM fails the session and calls RnaComplete; the overlaying SMM should do the following:
  • Identify the module handle of the overlaid SMM for the specified SMM type.
  • Use GetProcAddress to get the address of the RnaSessGetErrorStringEx function from the overlaid SMM.
  • If the RnaSessGetErrorStringEx entry point exists, it should call the entry point and pass the return information from the overlaid SMM to Dial-Up Networking.
  • If the RnaSessGetErrorStringEx entry point does not exist, it should use GetProcAddress to get the address of the RnaSessGetErrorString entry point.
  • If the RnaSessGetErrorString entry point exists, it should call the entry point and pass the return information from the overlaid SMM to Dial-Up Networking.
  • If the RnaSessGetErrorString entry point does not exist, it should use LoadString to get the error string from the overlaid SMM.

In the sample overlay SMM, the overlaying SMM does not own any error string/message ID. If this function is called it means that the overlaid SMM failed the session configuration and passed a message resource ID when it called RnaComplete to Dial-Up Networking.

2.4.3. RnaSessStart

The RnaSessStart function is called when Dial-Up Networking wants the SMM to start managing the session. The overlaying SMM should do the following during this function:

• Call RnaGetDevicePort to get the information of the connection Dial-Up Networking wants to start the session. The device information contains the class of the device through which the connection was made. The overlaying SMM needs to verify that it can handle the device class.
• The overlaying SMM also needs to verify all other conditions (for example, the session types, and so on) to ensure that it wants to manage the session.
• If the overlaying SMM does not want to manage the session, it calls the Start function of the overlaid SMM, and returns to Dial-Up Networking when the overlaid SMM returns.
• If the overlaying SMM wants to it can proceed to manage the session. The SMM can manage the session in two ways:
  • If the overlaying SMM wants to perform a short task, it can do so within the RnaSessStart function. When it finishes managing the session, it can hand off the control to the overlaid SMM by calling its Start function. When the overlaid SMM returns, it can return to Dial-Up Networking.
  • If the overlaying SMM wants to perform a long task, it should spawn a new thread to manage the session, and return to Dial-Up Networking immediately after the thread starts. When the thread finishes managing the session, it can hand off the control to the overlaid SMM by calling its Start function. In this case, if the overlaid SMM returns failure, the overlaying SMM needs to terminate the session by calling the RnaComplete function.

In the sample overlay SMM, the function is named SMMSessStart. It verifies the session is for the "COM" device class and the "initiator" session type (client) before it spawns a session management thread to manage the session and return to Dial-Up Networking. If either condition is not met, it hands off the control to the overlaid SMM immediately.

2.4.4. RnaSessStop

The RnaSessStop function is called when Dial-Up Networking wants to terminate the SMM. The overlaying SMM should do the following during this function:

1. If the overlaying SMM has not handed off the control to the overlaid SMM (by calling its Start function) when this function is called, it means the overlaying SMM is managing the session in a separate thread. The overlaying SMM must stop managing the session as soon as possible. When it can stop the task, it needs to call the RnaTerminate function.
2. If the overlaying SMM has already called the overlaid SMM's Start function, it can just call the overlaid SMM's Stop function, and then return immediately.

In the sample overlay SMM, SMMSessStop determines whether it has started managing the session by the existence of the session control block for the connection. If the session control block does not exist, it never manages the session, so it can bypass the Stop function to the overlaid SMM immediately. Otherwise, it signals an event to the session management thread to stop managing the session. When the thread detects the event, it terminates the session and calls RnaComplete or just calls the overlaid SMM to stop the session.

2.5. Unloading the Session Management Module Overlay

When Dial-Up Networking terminates the session, it unloads the SMM. The DLL's entry point is notified that the Dial-Up Networking process is detaching from the DLL. The process-detach handler should do the following:

1. Deinitialize the internal data structures and free the allocated resources.
2. Unload the DLL of the overlaid SMM by using FreeLibrary.

In the sample, the SMM frees all the session control blocks that are left in the list, and then traverses the list of overlaid SMM to free each overlaid SMM DLL before freeing the overlaid SMM control block.

2.6. Accessing the Communications Port

Generally, the overlaying SMM wants to directly access and transfer raw data across the connected device. For instance, it may want to do the front-end user verification or run a script over the wire. Dial-Up Networking provides a standard scheme for the SMM to access the device directly through the following steps:

1. During the RnaSessStart function, the SMM needs to verify that the connection was made through the class of the device it knows how to access. The SMM must call the RnaGetDeviceInfo function to obtain the device information, and then verify the device class contained in the device information. The device class identifies the API set that the SMM can use with the device. For instance, the "COM" device class is for the Win32 Comm API set.
2. When the SMM wants to access the device, it uses the TAPI information in the device information (obtained from the RnaGetDeviceInfo call.) The TAPI information includes the TAPI line handle, the TAPI call handle, and the address ID of the device.
3. The SMM calls TAPI's lineGetID function with all the TAPI information for the known device class to obtain the device handle that the SMM can use to directly access the device.

In the sample, the SMM obtains the Win32 Comm handle by calling the lineGetID function for the "data/modem" class. Then it uses this handle with the Win32 communication APIs to transfer data to/from the Dial-up Server.

3. Installing a Session Management Module

Session Management Modules are configured in the authentication key of the remote access branch of the registry. This section describes the layout of this key and how it is used.

3.1. Registry layout

  HKEY_LOCAL_MACHINE/SYSTEM/SERVICES/REMOTEACCESS/AUTHENTICATION
    CLASS
      <device class>
        <Dial-Up Adapter name 0>
        ...
        <Dial-Up Adapter name n>
      ...
    DRIVERS
      <Dial-Up Adapter name 0>
        0 = <Session Management Module 0>
        ...
        m = <Session Management Module m>
      ...
    SMM_FILES
      <Session Management Module 0>
        Desc = 
        Path = 
        Options = 
        Protocols = 
        Usage =
        <Overlaid_SMM>
          0 =
          1 =
          ...
      ... 

• CLASS key
  This key contains the subkeys for the classes of the devices that are installed for Dial-Up Networking. After Dial-Up Networking completes the physical connection through a TAPI device, it requests the unique device class name for the physical device from the corresponding service provider (through the lineGetID call with the NDIS class).
• CLASS\<device class> key
  This key contains the keys for the names of the Dial-Up adapters. Dial-Up Networking uses the names in this list to determine what adapter can be used in this session. Each adapter is tried sequentially until one successfully configures the session, or all fail to configure the session.
• CLASS\<device class>\<Dial-Up Adapter name x> key
  This key is the name of the Dial-Up adapter. Dial-Up Networking uses this name to determine the list of corresponding Session Management Modules (SMMs) that can be used for this session from the DRIVERS key. The name of this key must match one of the <Dial-Up Adapter name x> subkeys of the DRIVERS key.
• DRIVERS key
  This key contains the list of all the Dial-Up Adapters that are installed on the system. Dial-Up Networking uses only the adapters that match the device class in a session.
• DRIVERS\<Dial-Up Adapter name x> key
  This key contains the values for the SMMs that can be used with the adapter. The value name is a zero-based integer that signifies the order that the SMM Dial-Up Networking should attempt. The value is a string type for the SMM name that must match the name of one of the <Session Management Module x> subkeys of the SMM_FILES key.
• SMM_FILES key
  This key contains the keys for all the SMMs that are installed for Dial-Up Networking. Dial-Up Networking uses only the SMMs that correspond to the attempted adapters in a session.
• SMM_FILES\<Session Management Module x> key
  This key contains the information for the Session Management Module that Dial-Up Networking needs to start the SMM properly. This information is stored in the following values:

• Desc
  A string-type value that contains the descriptive name of the SMM. The name is used to populate the list of SMMs in the Server Type dialog boxes in the connection icon's Property page.
• Path
  A string-type value that contains the path of the Dynamic Linked Library (DLL) for the SMM. The path can be relative or a full path.
• Options
  A four-byte binary value for a set of flags that indicate the user-configurable options for the SMM. If the flag is set, you can configure the option from the Server Type dialog box in the connection icon's Property page. The current options are:

• Protocols
  A four-byte binary value for a set of flags that indicates the network protocols that can be used by the corresponding Dial-Up adapter. If the flag is set, users can specify the protocols to use for the connection from the Server Type dialog box in the connection icon's Property page. The current protocols are:

• Usage
  A four-byte binary value for a set of flags that indicates the type of the SMM. The current usage includes:

• SMM_FILES\<Session Management Module x>\Overlaid_SMM key
  This key contains the values for the list of SMMs that are overlaid by the SMM in the Path value. The value name is a zero-based integer that signifies the order that the SMM Dial-Up Networking should pass to the control on or after it finishes its task. The value is a string type for the path of the DLL for the SMM. The path can be relative or a full path.

3.2. How Dial-Up Networking Uses the Registry

The following is the default registry layout when Dial-Up Networking is first installed:

  HKEY_LOCAL_MACHINE/SYSTEM/SERVICES/REMOTEACCESS/AUTHENTICATION
    CLASS
      COM
        PPPMAC
    DRIVERS
      PPPMAC
        0 = "PPP"
        1 = "RAS"
        2 = "NWC"
    SMM_FILES
      NWC
        Desc = "NRN: Netware Connect"
        Path = "rasapi32.dll"
        Options = 04 00 00 00
        Protocols = 02 00 00 00
        Usage = 01 00 00 00
      PPP
        Desc = "PPP: Windows 95, Windows NT 3.5, Internet"
        Path = "rasapi32.dll"
        Options = 17 00 00 00
        Protocols = 07 00 00 00
        Usage = 03 00 00 00
      RAS
        Desc = "Windows for Workgroup and Windows NT 3.1"
        Path = "rasapi32.dll"
        Options = 04 00 00 00
        Protocols = 01 00 00 00
        Usage = 03 00 00 00

The default Dial-Up Adapter (Microsoft Dial-Up Adapter) is PPPMAC. PPPMAC handles a modem device and has three default Session Management Modules: NWC, PPP, and RAS. When the modem connection is established, Dial-Up Networking gets the device class of the modem from TAPI's lineGetID call for the NDIS type. The Unimodem service provider returns the COM device class for the modem. Dial-Up Networking looks for the Dial-Up adapters from the REMOTEACCESS/AUTHENCATION/CLASS/COM key and finds PPPMAC as the only adapter. Next, Dial-Up Networking enumerates the Session Management Modules for PPPMAC from the REMOTEACCESS/AUTHENCATION/-DRIVERS/PPPMAC key, starting from the PPP type. When Dial-Up Networking is ready to hand off control to the SMM, it looks up the Path value in the REMOTEACCESS/AUTHENCATION/SMM_FILES/PPP key for the DLL name, and then loads it and starts the session management phase.

4. Setting Up an External Session Management Module

Two elements are required to set up an external Session Management Module for Windows 95 Dial-Up Networking.

4.1. Session Management Module Setup DLL (SMMSetup.dll)

SMMSetup.dll contains utilities to modify the machine-dependent Dial-Up Networking information in the registry layout, which cannot be specified statically in the Setup .inf file. These are: a) the SMM order for a Dial-Up adapter and b) the list of the overlaid SMM.

4.1.1. Modifying the Session Management Module Order

To run the utility, the Setup utility in SMMSetup.dll must be invoked with the following command line: Rundll32.exe loads SMMSetup.dll, and then starts executing the SMM_Setup entry point. Three options are available for the command:

• a The <Session Management Module> key is appended at the end of the SMM list for the DRIVERS\<Dial-Up Adapter name x> key.
• i The <Session Management Module> key is inserted at the beginning of the SMM list for the DRIVERS\<Dial-Up Adapter name x> key.
• d The <Session Management Module> key is deleted from the SMM list for the DRIVERS\<Dial-Up Adapter name x> key.

Multiple <Session Management Module> parameters can be specified in a single call; the command operates on each parameter from left to right. The command line is specified as a part of the Setup .inf file for the external SMM.

4.1.2. Modifying the List of Overlaid Session Management Modules

To run the utility, the Setup utility in SMMSetup.dll must be invoked with the following command line: Rundll32.exe load SMMSetup.dll, and then starts executing the Overlaid_SMM entry point. Three options are available for the command.

• i The <pathname> value is inserted into the overlaid SMM list by replacing the current path in the Path value and moving the current path to the SMM list in the <Overlaid_SMM> key.
• d The <pathname> value is deleted from the overlaid SMM list whether it is in the Path value or the SMM list in the <Overlaid_SMM> key.
• r The existing Overlaid SMM chain is removed and replaced with the <pathname> list (with the first <pathname> at the beginning of the chain).

Multiple <pathname> parameters can be specified in a single call; the command operates on each name from right to left. The command line is specified as a part of the Setup .inf file for the external SMM.

4.2. Session Management Module Setup .inf file

Dial-Up Networking uses the standard Windows Setup program to add the Session Management Module into the Dial-Up Networking registry layout. The Windows Setup program requires a Setup .inf file. The following highlights the required sections in the .inf file:

[DestinationDirs]
SMM_SYS_CopyFiles   =11    

[Optional Components]
EXT_SMM

[EXT_SMM]
OptionDesc=%SMM_Desc%
Tip=%SMM_Tip%
CopyFiles=SMM_SYS_CopyFiles
AddReg=SMM_Reg
IconIndex= 21          ;Dial-Up Networking mini-icon for dialog boxes.

[SMM_SYS_CopyFiles]
extsmm.dll
smmsetup.dll

[SMM_Reg]
;
; Session Management Module registration
;
HKLM, SYSTEM\CurrentControlSet\Services\RemoteAccess\Authentication\SMM_Files\EXTSMM, Desc,, %SMM_Desc%
HKLM, SYSTEM\CurrentControlSet\Services\RemoteAccess\Authentication\SMM_Files\EXTSMM, Usage,1,01,00,00,00
HKLM, SYSTEM\CurrentControlSet\Services\RemoteAccess\Authentication\SMM_Files\EXTHOOK, Options,1,17,00,00,00
HKLM, SYSTEM\CurrentControlSet\Services\RemoteAccess\Authentication\SMM_Files\EXTHOOK, Protocols,1,07,00,00,00
;
; RunOnce for SMMSetup utility
;
HKLM, Software\Microsoft\Windows\CurrentVersion\RunOnce,"%SMMSetup_Order_Desc%",,"rundll32.exe smmsetup.dll,SMM_Setup /a MAC EXTHOOK"
HKLM, Software\Microsoft\Windows\CurrentVersion\RunOnce,"%SMMSetup_Overlay_Desc%",,"rundll32.exe smmsetup.dll,Overlaid_SMM /i EXTHOOK extsmm.dll"

;****************************************************************************
; User-visible strings
;****************************************************************************

[Strings]
SMM_Desc  = "External Session Management Module name"
SMM_Tip   = "Allows you to do additional session management over Dial-up Networking"
SMM_Desc      = "External Session Management Module"
SMMSetup_Order_Desc = "External SMM Order Setup"
SMMSetup_Overlaid_Desc = "External SMM Overlaying List Setup"

When you want to install an external SMM, this .inf Setup file and all the SMM modules and the SMMSetup.dll should be on the provided disks. The steps for installing an SMM are:

1. On the Start menu, point to Settings, and then double-click Control Panel.
2. Double-click Add/Remove Programs.
3. Click the Windows Setup tab.
4. Open the Windows Setup page in the Add/Remove Programs icon in Control Panel.
5. Click Have Disk.
6. Insert the disks with the .inf Setup file when prompted. The next page displays the external SMM item.
7. Check the item and click Install.

The Windows Setup program uses the information from this .inf Setup file as follows:

 [DestinationDirs] 
"SMM_SYS_CopyFiles   =11" 

This section tells Setup to copy the external files to the Windows system directory:

[Optional Components] 

This section lists the items that can be set up from this .inf file. EXT_SMM is the only item:

[EXTHOOK] 

This section contains the following values:

OptionDesc	The displayed string value for the item in the selection box.
Tip	The displayed string value for the description box when the item is selected.
CopyFiles	SMM_SYS_CopyFiles indicates the section that contains the list of file(s) to copy.
AddReg	SMM_Reg indicates the set of registry keys and values to add during installation.
IconIndex	The integer value 21 is for a Dial-Up Networking mini-icon to be displayed in the selection box.

[SMM_SYS_CopyFiles] 

This section contains the list of files to be copied to the Windows system directory.

[SMM_Reg] 

The lines below the Session Management Module registration comment sets up the Dial-Up Networking registry layout for the Session Management Module except for the SMM order. The line below the RunOnce for SMMSetup utility comment tells Windows Setup to run the SMM Setup utility during the installation.

5. Session Management Module Function Reference

Following is a list of functions and structures that are used by SMM. These functions are documented in the MSDN. You must use the Search tab to locate them:

Functions

RnaSessInitialize
RnaSessStart
RnaSessStop
RnaComplete
RnaTerminate
RnaGetDevicePort
RnaOpenMac
RnaCloseMac
RnaGetUserProfile
RnaStartCallback
RnaUICallbackDialog
RnaUIUsernamePassword
RnaGetOverlaidSMM

Structures

RNA_FUNCS
SESS_CONFIGURATION_INFO
COMPLETE_INFO
PROJECTION_INFO
DEVICE_PORT_INFO
USER_PROFILE