Purpose: This document discusses the SessionLock class's methods and using them to control the current user's session.

SessionLock Methods

The MicroFour.StrataFrame.Security.SessionLock class is a sealed, static class that contains shared (static) methods that are used to lock the application session allowing quick user switching and monitor idle user sessions to automatically lock them. There are 7 public methods within the SessionLock class:

• LockSession()
• StartSessionMonitoring()
• StopSessionMonitoring()
• PauseSessionMonitoring()
• ResumeSessionMonitoring()
• PauseSessionTimer()
• ResumeSessionTimer()

LockSession()

The LockSession() method is used to explicitly lock the session. When a session locks, all forms within the application are minimized, and a login form is show that forces the user to re-authenticate or allows another user to log into the system. When a user is successfully authenticated, the application resumes normally. This method can be called explicitly to lock the session and is called internally when the session lock shortcut key is pressed and when a user's session times out.

Imports MicroFour.StrataFrame.Security
...
Private Sub Lock()
    '-- Call the method to lock the session
    '   This call blocks until a user is re-authenticated
    SessionLock.LockSession()
End Sub

using MicroFour.StrataFrame.Security;
...
private void Lock()
{
    //-- Call the method to lock the session
    //   This call blocks until a user is re-authenticated
    SessionLock.LockSession();
}

StartSesionMonitoring() and StopSessionMonitoring()

The StartSessionMonitoring() and StopSessionMonitoring() methods are used in conjunction to start and stop session monitoring respectively. Session monitoring consists of two things:

1. Session Timer - The session timer watches for idle sessions and automatically locks the session if the idle time exceeds the current user's idle timeout.
2. Keyboard Monitoring - Keyboard activity is monitored for the session lock shortcut key. StartSessionMonitoring() installs a low-level Windows input hook into the current process to monitor both keyboard and mouse input and determine when the user’s session timed-out. This low-level hook also watches for the session lock shortcut key.

Note: The hook installed by the StartSessionMonitoring() method must be in place for the automatic session monitoring to work. Therefore, the StartSessionMonitoring() method must be called to attach to the Windows hook before the application executes; this is usually done within the InitApplication method of the AppMain.vb (program.cs) file.

StopSessionMonitoring() manually removes the low-level Windows hook.  This method is generally never called since the hook is automatically removed when the process exits.

Imports MicroFour.StrataFrame.Security
...
Private Shared Sub InitApplication(ByVal e As InitializingApplicationEventArgs)
    '-- Start the session locking monitor
    SessionLock.StartSessionMonitoring()
End Sub

using MicroFour.StrataFrame.Security;
...
private static void InitApplication(InitializingApplicationEventArgs e)
{
    //-- Start the session locking monitor
    SessionLock.StartSessionMonitoring();
}

PauseSessionMonitoring() and ResumeSessionMonitoring()

The PauseSessionMonitoring() and ResumeSessionMonitoring() are used in conjunction to respectively pause and resume the session monitoring.

When PauseSessionMonitoring() is called, the session timer is paused and the session lock shortcut key is ignored. This method is generally used when the application needs to perform a processing intensive task that requires the computer to be idle for an extended period of time.

For example, if a user requests a report that takes a considerable amount of time to compute, but the user’s session timeout is very short, the session might timeout and lock while waiting on the report to complete. In such situations, using the PauseSessionMonitoring() and ResumeSessionMonitoring() methods allows you to wrap critical sections of the application within a Pause/Resume block to make sure that the session does not lock while in that block.

Imports MicroFour.StrataFrame.Security
...
Private Sub ComputeReport()
    '-- Pause the session
    SessionLock.PauseSessionMonitoring()
    
    '-- Compute the report
    '  This code takes a while to complete and the session should not
    '  be allowed to lock while inside it
    
    '-- Resume the monitoring
    SessionLock.ResumeSessionMonitoring()
End Sub

using MicroFour.StrataFrame.Security;
...
private void ComputeReport()
{
    //-- Pause the session
    SessionLock.PauseSessionMonitoring();
    
    //-- Compute the report
    //  This code takes a while to complete and the session should not
    //  be allowed to lock while inside it
    
    //-- Resume the monitoring
    SessionLock.ResumeSessionMonitoring();
}

PauseSessionTimer() and ResumeSessionTimer()

Like the PauseSessionMonitoring() and ResumeSessionMonitoring() methods, the PauseSessionTimer() and ResumeSessionTimer() methods are used in conjunction to pause the session timer and prevent a user’s session from automatically timing out during a critical code block within the application. However, unlike the pause/resume monitoring methods, these pause/resume timer methods do not prevent the session lock shortcut key from locking the session, they only pause the automatic timer.

Imports MicroFour.StrataFrame.Security
...
Private Sub ComputeReport()
    '-- Pause the session
    SessionLock.PauseSessionTimer()
    
    '-- Compute the report
    '  This code takes a while to complete and the session should not
    '  automatically lock while inside it
    
    '-- Resume the monitoring
    SessionLock.ResumeSessionTimer()
End Sub

using MicroFour.StrataFrame.Security;
...
private void ComputeReport()
{
    //-- Pause the session
    SessionLock.PauseSessionTimer();
    
    //-- Compute the report
    //  This code takes a while to complete and the session should not
    //  automatically to lock while inside it
    
    //-- Resume the monitoring
    SessionLock.ResumeSessionTimer();
}

© 2005-2006 MicroFour, Inc. All Rights Reserved.