HOWTO: Windows 95/98 Session Management Modules (2/5)

ID: Q232708

The information in this article applies to:

SUMMARY

Dial-Up Networking uses Session Management Modules (SMM) to abstract the interface presented by the dial-up server. This is the second of five Knowledge Base articles describing the use of Session Management Modules.


MORE INFORMATION

2. Session Management Module Overlays

2.1. Overview

Windows 95/98 Dial-Up Networking provides four built-in Session Management Modules (SMMs): However, in some Dial-Up environments, extra steps may be required to set up the dial-up session. Windows 95/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 (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/98 Dial-Up Networking as an external SMM. Dial-Up Networking treats the overlaying SMM as a separate SMM from the one it overlays. The user can choose to use the overlaying SMM by doing the following:
  1. Opening the Connection icon's Property pages.


  2. Selecting the Server type page.


  3. Selecting 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

This 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 LoadLibrary.


  3. Use GetProcAddress 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 would contain 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

This 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: 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

This 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: 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

This 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 simply call the overlaid SMM's Stop function and 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 simply 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 left in the list and 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 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. Them it uses this handle with the Win32 communication APIs to transfer data to/from the Dial-up Server.


REFERENCES

For additional information about the use of Session Management Modules, please see the following articles in the Microsoft Knowledge Base:

Q232675 HOWTO: Windows 95/98 Session Management Modules (1/5)

Q232716 HOWTO: Windows 95/98 Session Management Modules (3/5)

Q232719 HOWTO: Windows 95/98 Session Management Modules (4/5)

Q232725 HOWTO: Windows 95/98 Session Management Modules (5/5)

Additional query words: 


Keywords          : kbnetwork kbNDIS kbWinOS95 kbWinOS98 
Version           : WINDOWS:; Win95:; Win98:
Platform          : Win95 WINDOWS Win98 
Issue type        : kbhowto

Last Reviewed: June 9, 1999