Overview of the Session Management Interface

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.

• Calls the overlaid SMM's RnaSessInitialize functions to obtain the dispatch function table. The function table would contain the entry points to Start and Stop functions.
• Returns the entry points to the Start (RnaSessStart) and Stop (RnaSessStop) functions for the overlaying DLL.

In the sample, the SMM calls the PPPSMM's RnaSessInitialize function. If the function succeeds, the SMM successfully overlays the PPPSMM and returns the entry points to its RnaSessStart and RnaSessStop functions (SMMSessStart and SMMSessStop respectively) to Dial-Up Networking.

RnaSessGetErrorString

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 should try to get the RnaSessGetErrorString entry point from the overlaid SMM and do the following:

• If the RnaSessGetErrorString entry point exists, it should call the entry point and passes 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, the overlaying SMM does not own any error string/message ID. If this function is called it means that the SMM for PPP fails the session configuration and passes a message resource ID when it calls RnaComplete to Dial-Up Networking.

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, etc.) 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 returns 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, 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 returns to Dial-Up Networking. If either condition is not met, it hands off the control to the overlaid SMM (SMM for PPP) immediately.

RnaSessStop

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

• 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.
• If the overlaying SMM already calls the overlaid SMM's Start function, it can simply call the overlaid SMM's Stop function and return immediately.

In the sample, 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 PPPSMM immediately. Otherwise, it signals an event the session management thread to stops managing the session. When the thread detects the event, it terminates the session and calls RnaComplete or simply calls the PPPSMM to stop the session.