Microsoft KB Archive/232708

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

ID: Q232708

---

The information in this article applies to:

• Microsoft Windows 98, on platform(s):
  • The Microsoft Windows operating system versions 95, 98
• Microsoft Windows 95 Driver Development Kit (DDK)
• Microsoft Windows 98 Driver Development Kit (DDK)

---

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.1. Overview

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

• Point-to-point Protocol Session Management Module for Windows 95/98, Windows NT 3.5, and Internet providers.
• Remote Access Service 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/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:

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 corresponding 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 the 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

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:

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

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 kbOSWin95 kbOSWin98
Version : WINDOWS:; Win95:; Win98:
Platform :
Issue type : kbhowto
Technology :

Last Reviewed: October 2, 2000 © 2000 Microsoft Corporation. All rights reserved. Terms of Use.