When you create an instance of the MessageInterceptor class, the first thing you need to decide is whether you would like the intercepted messages to be available to other interceptor applications including the Windows Mobile Text Message reader. If you would like the message to be available to other interceptor applications, create the MessageInterceptor instance passing the InterceptionAction.Notify enumeration value to the MessageInterceptor constructor. In this case, the messaging system passes a copy of the message to your application and continues notifying other interceptor applications. If you instead pass InterceptionAction.NotifyAndDelete, the messaging system deletes the message when your application finishes with it. If you create an instance of the MessageInterceptor class with a constructor that does not accept a InterceptionAction parameter, the value defaults to InterceptionAction.Notify.

Note:

Setting the InterceptionAction to InterceptionAction.NotifyAndDelete prevents the Windows Mobile Text Message reader from receiving the message but does not guarantee that no other message interceptor receives the message. An InterceptionAction value of InterceptionAction.NotifyAndDelete does not affect any interceptors that process the message prior to the messaging subsystem notifying your application.

In most situations, the user's mobile device is not used exclusively for your application. The user likely uses the device for a variety of work and personal purposes. For this reason, when registering to intercept SMS messages, you should provide a filter condition. Creating a copy of the message and routing the copy to your application consumes device resources, therefore you should register your SMS interceptor so that it receives only those messages that meet a specific criteria. Allowing the messaging system to filter the incoming messages is much more efficient than performing the filtering in your application.

To create a filter condition you simply assign an instance of the MessageCondition class to the MessageInterceptor instance's MessageCondition property. The MessageCondition class requires four pieces of information for a complete condition. First you must identify the part of the message to which the condition applies; you specify this value with the MessageProperty enumeration. Second is the type of comparison to perform such as equal, contains, starts-with, and so on; you specify the comparison using the MessagePropertyComparisonType enumeration. Finally, the condition needs the value to use for the comparison and whether the comparison should be case-sensitive. Tables 1 and 2, respectively, show the values for the MessageProperty and MessagePropertyComparisonType enumerations.

Table 1. MessageProperty enumeration values

Table 2. MessagePropertyComparisonType enumeration values

By default, the comparisons are case-sensitive. You can specify a case-insensitive comparison by passing false to the caseSensitive parameter of the MessageCondition constructor that accepts four parameters.

The MessageInterceptor class exposes a single event named MessageReceived that accepts a MessageInterceptorEventHandler delegate. The MessageInterceptor class signals the MessageReceived event when the device receives an SMS message meeting the condition associated with the MessageInterceptor instance.

When the MessageReceived event signals, it passes a MessageInterceptorEventArgs reference to your event handler method. The MessageInterceptorEventArgs class has only one public member: the Message property that returns a reference to the received SMS message. The Message property return type is the base class Message, which does not provide a reference to the message body; therefore, to access the message body you must cast the Message reference to a SmsMessage reference.

Once your application associates an event handler with the MessageReceived event, you cannot make any modifications to the MessageInterceptor instance; therefore, you must associate the MessageCondition with the MessageInterceptor instance before associating the event handler. For this reason, Visual Basic .NET developers cannot use the WithEvents declaration modifier. The WithEvents declaration modifier automatically associates an event handler when the MessageInterceptor instance is created, which does not give you an opportunity to associate a MessageCondition. To associate a MessageCondition with the MessageInterceptor class in Visual Basic .NET, you must declare the MessageInterceptor reference without the WithEvents keyword and use the AddHandler keyword to attach an event handler to the MessageInterceptor instance after you assign the MessageCondition.

When you create an instance of the MessageInterceptor class and attach a delegate to the MessageReceived event, the MessageInterceptor class creates a temporary registry entry under HKLM\Software\Microsoft\Inbox\Rules. The registry entry contains information about the MessageInterceptor instance, which the messaging subsystem uses to notify the MessageInterceptor instance when a message arrives. Once you are done with the MessageInterceptor instance, the registry entry should be removed. Unfortunately, the MessageInterceptor class does not always clean up the registry properly. As a result, the registry entry may remain in the registry indefinitely even though the MessageInterceptor class will never use that entry again. These excess entries clutter the registry and over time, as the number of these unused entries grows, they may negatively impact message processing performance.

The MessageInterceptor class creates the registry entry when you attach an event handler to the MessageReceived event; the MessageInterceptor will also delete the entry if you remove the event handler from the MessageReceived event. Most applications do not explicitly remove event handlers and instead just let the .NET Compact Framework garbage collector remove them. Due to the problem in the MessageInterceptor class' cleanup process, you must explicitly remove the event handlers to assure that the MessageInterceptor class properly removes its registry entries.

A persistent message interceptor usually starts as a transient message interceptor. You create the MessageInterceptor instance specifying the InterceptionAction and MessageCondition; in most cases, you will also associate an event handler with the MessageReceived event. To make the message interceptor persistent, you call the MessageInterceptor.EnableApplicationLauncher method.

You can call the EnableApplicationLauncher method any time after you set the MessageCondition property. Unlike the MessageCondition property, you can safely call the EnableApplicationLauncher method after you attach an event handler to the MessageReceived event; this is safe because the EnableApplicationLauncher method does not change the state of the MessageInterceptor instance. Exactly when you call the EnableApplicationLauncher method is up to you. You can call the EnableApplicationLauncher method immediately after you create and configure the MessageInterceptor instance, at the end of your program just before you call the MessageInterceptor instance's Dispose method, and anywhere in between.

The EnableApplicationLauncher method accepts a string parameter that uniquely identifies the MessageInterceptor. The string can be any value that you like as long as it will not collide with any other persistent message interceptor identifiers. Common examples of persistent message interceptor identifiers include globally unique identifiers (GUIDs), URLs, strings comprised of a combination of your organization and application name, and so on. Other versions of the EnableApplicationLauncher method let you specify a program other than the calling program as the program that the messaging subsystem should notify; you can also specify command-line arguments that the messaging subsystem will include when launching the application.

Note:
For a more detailed discussion of creating persistent notification identifiers, see the Persistent Notifications section of The State and Notifications Broker API Part 2.

Once you call the EnableApplicationLauncher method, your application is registered as a persistent notification handler; however, nothing changes for your application until the application exits.

Once you create a persistent message interceptor, you create the MessageInterceptor instance to handle the message notifications differently. Rather than specifying the InterceptionAction and MessageCondition again, you instead pass the persistent notification identifier to the MessageInterceptor constructor. Using the identifier, the constructor reads the persistent message interceptor information from the registry and sets the MessageInterceptor instance's InterceptionAction and MessageCondition appropriately. Whether you create the MessageInterceptor instance using the transient notification or persistent notification constructor, you must associate an event handler with the MessageReceived event to receive the message notifications.

If you attempt to construct a MessageInterceptor instance with a message interceptor identifier that that has not yet been registered by a call to the EnableApplicationLauncher method, the MessageInterceptor constructor will throw an exception. To confirm that the message interceptor identifier is already registered, use the MessageInterceptor.IsApplicationLauncherEnabled static method. The IsApplicationLauncherEnabled method accepts a persistent message interceptor identifier and returns true if a persistent message interceptor definition exists with the specified identifier. When the IsApplicationLauncherEnabled method returns true, you create the MessageInterceptor instance using the constructor that accepts the identifier; otherwise, you create the MessageInterceptor normally and call the EnableApplicationLauncher to create the persistent message interceptor.

Because the persistent notification information is stored in the registry, the persistent notification information is truly persistent; even a soft reset of the device will not remove it. To disable a persistent notification, you must explicitly remove it. To remove a persistent notification, you call the MessageInterceptor.DisableApplicationLauncher method on a MessageInterceptor instance that is associated with the persistent notification. You associate a MessageInterceptor instance with a persistent notification by either calling the MessageInterceptor constructor with the persistent notification identifier as a parameter or by calling the EnableApplicationLauncher method.

Two of the MessageInterceptor constructors accept a Boolean parameter named useFormThread. Passing false to the useFormThread parameter causes the MessageInterceptor class to monitor for arriving messages on a separate thread and therefore executes your MessageReceived event handler on this same thread. To simplify the discussion, the remainder of this paper will refer to the thread handling the message processing as the "message-interceptor" thread.

Even when you handle the MessageReceived event on the separate message-interceptor thread, you should avoid performing any long-running tasks in the event handler. All MessageInterceptor instances share a single message-interceptor thread. As a result only one MessageInterceptor event handler can run at a time. Therefore, a long-running event handler in one MessageInterceptor instance prevents not only that instance from processing incoming messages but all MessageInterceptor instances from processing incoming messages until the long-running event handler exits. In this case, your event handler should pass the message processing to a thread separate from the message-interceptor thread. By using a thread separate from the message-interceptor thread to process the message, your event handler can exit quickly and make the message-interceptor thread available to receive additional message notifications.

Note:

The MessageInterceptor class' thread handling is very much like the thread handling of the SystemState and RegistryState classes. If you would like to read a detailed discussion of the threading behavior of these classes, please see the "Threading and Notification Handling" section of The State and Notifications Broker API Part 3. For guidelines on how to decide between using the Thread and ThreadPool classes, you may want to read the "Threading" section of the .NET Compact Framework version 2.0 Performance and Working Set FAQ blog post.

The MessageInterceptor instance's threading choice is not stored as part of a persistent notification. If you would like the MessageInterceptor instance associated with a persistent notification to run on a background thread, you must specify the desired threading behavior when you call the MessageInterceptor constructor.

Just as is the case with any application code running on a non-UI thread, your event handler must not attempt to interact directly with the application user interface. Your event handler must instead use the Control.Invoke and Control.BeginInvoke methods to interact with the user interface; failure to do so will cause your application to throw an exception.

The MessageInterceptor implements the IDisposable interface which, of course, indicates that you should call the MessageInterceptor.Dispose method when you no longer need the MessageInterceptor instance. Many classes in the .NET Compact Framework are very forgiving if you forget to call the Dispose method; however, that is not the case for the MessageInterceptor class. Forgetting to call the MessageInterceptor.Dispose method can cause your application to hang indefinitely at application shutdown.

In the .NET Compact Framework, an application does not fully exit until all of the application threads terminate. In the case of the MessageInterceptor class, the message-interceptor thread does not terminate until you call the Dispose method; therefore, your application will hang during the exit process if you forget to call the Dispose method. As mentioned earlier in this paper, all MessageInterceptor instances share a single message-interceptor thread. The MessageInterceptor class tracks the number of MessageInterceptor instances that are using the message-interceptor thread and does not terminate the thread until you call the Dispose method on all of them.

Note:
In some cases, a .NET Compact Framework application will automatically terminate running threads as part of the application shutdown process but this not the case with the MessageInterceptor class. If you would like to learn more about affects of threads on an application's lifecycle, see Foreground and Background Threads in the .NET Framework Developers Guide.

This example demonstrates how to create a MessageInterceptor instance that receives a copy of all SMS messages from a person named John Smith. To check the sender by name, the sender must be in the device's Contacts list. The MessageInterceptor instance is handling the message notifications on the main application thread.

C#

MessageInterceptor _smsInterceptor = null;

private void Form1_Load(object sender, EventArgs e)
{
    // Default constructor indicates that message handling should occur
    // on the main application thread, and message should be passed
    // to other message interceptors and to the SMS message reader
    _smsInterceptor = new MessageInterceptor();
    // The name is reported in the form of the Contact's File As field
    // Therefore must check for "Smith, John", not "John Smith"
    _smsInterceptor.MessageCondition = 
        new MessageCondition(MessageProperty.Sender, 
        MessagePropertyComparisonType.Contains, "Smith, John", false);
    _smsInterceptor.MessageReceived += SmsInterceptor_MessageReceived;
}

void SmsInterceptor_MessageReceived(object sender, MessageInterceptorEventArgs e)
{
    // Cast to SmsMessage to access message body
    // Not expecting to receive any non-SMS messages but use "as" to
    // cast to be extra safe
    SmsMessage newMessage = e.Message as SmsMessage;
    if (newMessage != null)
    {
        statusBar1.Text = "From:" + newMessage.From.Address;
        Debug.WriteLine(string.Format("Sender:{0} - Body:{1}", _
          newMessage.From.Address, newMessage.Body));
    }
}

private void Form1_Closed(object sender, EventArgs e)
{
    if (_smsInterceptor != null)
    {
        // Remove event handler to assure proper registry cleanup
        _smsInterceptor.MessageReceived -= SmsInterceptor_MessageReceived;
        _smsInterceptor.Dispose();
    } 
}

Visual Basic .NET

' Do not use WithEvents or cannot associate a MessageCondition
Private _smsInterceptor As MessageInterceptor = Nothing

Private Sub Form1_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Load
    ' Default constructor indicates that message handling should occur
    ' on the main application thread, and message should be passed
    ' to other message interceptors and to the SMS message reader
    _smsInterceptor = New MessageInterceptor()
    _smsInterceptor.MessageCondition = New MessageCondition(MessageProperty.Sender, _
        MessagePropertyComparisonType.Contains, "Smith, John", False)
    ' Explicitly attach the event handler rather than use WithEvents on the decleration 
    AddHandler _smsInterceptor.MessageReceived, AddressOf SmsInterceptor_MessageReceived
End Sub

Private Sub SmsInterceptor_MessageReceived(ByVal sender As Object, ByVal e As MessageInterceptorEventArgs)
    ' Cast to SmsMessage to access message body
    ' Not expecting to receive any non-SMS messages but use "as" to
    ' cast to be extra safe
    Dim newMessage As SmsMessage = TryCast(e.Message, SmsMessage)
    If Not newMessage Is Nothing Then
        StatusBar1.Text = "From:" & newMessage.From.Address
        Debug.WriteLine(String.Format("Sender:{0} - Body:{1}", newMessage.From.Address, newMessage.Body))
    End If
End Sub

Private Sub Form1_Closed(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Closed
    If Not _smsInterceptor Is Nothing Then
        RemoveHandler _smsInterceptor.MessageReceived, AddressOf SmsInterceptor_MessageReceived
        _smsInterceptor.Dispose()
    End If 
End Sub

This example demonstrates how to create a MessageInterceptor instance that receives a copy of all SMS messages sent from the phone number 425.555.1212. The MessageInterceptor instance handles the message notifications on a thread separate from the main application thread and prevents any further message interceptors, including the SMS message reader, from receiving the message.

C#

MessageInterceptor _smsInterceptor = null;

private void Form1_Load(object sender, EventArgs e)
{
    // Construct interceptor so that the message does not propagate
    // any further than this application which prevents the message
    // from appearing in the message reader. 
    // Handle message notifications on background thread
    _smsInterceptor = new MessageInterceptor(InterceptionAction.NotifyAndDelete, false);
    // When filtering by phone number, do not include any special
    // characters such as ().- 
    // Can filter by phone number for all senders - whether the sender
    // is in the Contact list does not affect this.
    _smsInterceptor.MessageCondition =
        new MessageCondition(MessageProperty.Sender,
        MessagePropertyComparisonType.Contains, "4255551212");
    _smsInterceptor.MessageReceived += SmsInterceptor_MessageReceived_OnThread;
}

// Notification runs on the message-interceptor thread, not the main
// application thread
void SmsInterceptor_MessageReceived_OnThread(object sender, MessageInterceptorEventArgs e)
{
    SmsMessage newMessage = e.Message as SmsMessage;
    if (newMessage != null)
    {
        // Cannot interact directly with user interface - in this case
        // using an anonymous delegate with the BeginInvoke method to
        // to transfer control to the main application thread to update
        // the status bar
        statusBar1.BeginInvoke(
            (MethodInvoker)delegate { 
                statusBar1.Text = "From:" + newMessage.From.Address; 
            });
        Debug.WriteLine(string.Format("Sender:{0} - Body:{1}", newMessage.From.Address, newMessage.Body));
    }
}

private void Form1_Closed(object sender, EventArgs e)
{
    if (_smsInterceptor != null)
    {
        // Remove event handler to assure proper registry cleanup
        _smsInterceptor.MessageReceived -= SmsInterceptor_MessageReceived;
        _smsInterceptor.Dispose();
    } 
}

#if PocketPC || Smartphone
        // MethodInvoker is a delegate with no arguments and no return value
        // MethodInvoker is part of the full .NET Framework but not the
        // .NET Compact Framework so must declare explicitly
        delegate void MethodInvoker();
#endif

Visual Basic .NET

Private _smsInterceptor As MessageInterceptor = Nothing

Private Sub Form1_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Load
    ' Construct interceptor so that the message does not propagate
    ' any further than this application which prevents the message
    ' from appearing in the message reader. 
    ' Handle message notifications on background thread
    _smsInterceptor = New MessageInterceptor(InterceptionAction.NotifyAndDelete, False)
    ' When filtering by phone number, do not include any special
    ' characters such as ().- 
    ' Can filter by phone number for all senders - whether the sender
    ' is in the Contact list does not affect this.
    _smsInterceptor.MessageCondition = New MessageCondition(MessageProperty.Sender, _
        MessagePropertyComparisonType.Contains, "4255551212")
    AddHandler _smsInterceptor.MessageReceived, AddressOf SmsInterceptor_MessageReceived_OnThread
End Sub

' Notification runs on the message-interceptor thread, not the main
' application thread
Private Sub SmsInterceptor_MessageReceived_OnThread(ByVal sender As Object, ByVal e As MessageInterceptorEventArgs)
    Dim newMessage As SmsMessage = TryCast(e.Message, SmsMessage)
    If Not newMessage Is Nothing Then
        ' Cannot interact directly with user interface 
        ' using a custom delegate with the BeginInvoke method 
        ' to transfer control to the main application thread to update
        ' the status bar
        Dim updateDelegate As New UpdateStatusBarDelegate(AddressOf UpdateStatusBar)
        StatusBar1.BeginInvoke(updateDelegate, New Object() {"From:" & newMessage.From.Address})
        Debug.WriteLine(String.Format("Sender:{0} - Body:{1}", newMessage.From.Address, newMessage.Body))
    End If
End Sub

' This method is run on the main application thread by the call to
' StatusBar1.Invoke. Running on the main application thread, this method
' can safely update the user interface
Sub UpdateStatusBar(ByVal text As String)
    StatusBar1.Text = text
End Sub

Private Sub Form1_Closed(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Closed
    If Not _smsInterceptor Is Nothing Then
        RemoveHandler _smsInterceptor.MessageReceived, AddressOf SmsInterceptor_MessageReceived
        _smsInterceptor.Dispose()
    End If 
End Sub

' Custom delegate used when StatusBar1.BeginInvoke calls UpdateStatusBar
Delegate Sub UpdateStatusBarDelegate(ByVal text As String)

This example demonstrates how to create a MessageInterceptor instance that is associated with a persistent notification. The program checks to see if the persistent notification was previously created and constructs the MessageInterceptor appropriately. The MessageInterceptor receives only those messages where the message body begins with the text "Contoso Data:". The MessageInterceptor instance handles the message notifications on a thread separate from the main application thread and prevents any further message interceptors, including the SMS message reader, from receiving the message.

This example also includes a menu handler that disables the persistent notification.

Note:
The SmsInterceptor_MessageReceived_OnThread and Form1_OnClosed methods are the same as those in Example 2 and are therefore not repeated.

C#

MessageInterceptor _smsInterceptor = null;
const string _persistentIdentifier = "Contoso.Pharmaceuticals.MessageHandlerApp";

private void Form1_Load(object sender, EventArgs e)
{
    if ( ! MessageInterceptor.IsApplicationLauncherEnabled(_persistentIdentifier))
    {
        // Persistent notification does not yet exist - must explicitly create
        _smsInterceptor = new MessageInterceptor(InterceptionAction.NotifyAndDelete, false);
        _smsInterceptor.MessageCondition = new MessageCondition(MessageProperty.Body, 
            MessagePropertyComparisonType.StartsWith, "Contoso Data:", false);
        // Make the interceptor persistent
        _smsInterceptor.EnableApplicationLauncher(_persistentIdentifier);
    }
    else
    {
        // Persistent notification already defined - create this instance using the
        // same characteristics
        _smsInterceptor = new MessageInterceptor(_persistentIdentifier, false);
    }

    // Once the interceptor is created, add event handler. Whether the interceptor is constructed
    // explicitly or constructed from the persistent notification identifier, 
    // the event handling behavior is the same.
    _smsInterceptor.MessageReceived += SmsInterceptor_MessageReceived_OnThread;

}

// Remove persistent notification 
private void menuDisablePersistentNotification_Click(object sender, EventArgs e)
{
    // Confirm that _smsInterceptor is a valid reference, that the current 
    // _smsInterceptor instance is associated with the correct persistent 
    // notification identifier, and that a persistent notification exists
    // that has the specified identifier
    if (_smsInterceptor != null &&
        _smsInterceptor.ApplicationLaunchId == _persistentIdentifier &&
        MessageInterceptor.IsApplicationLauncherEnabled(_persistentIdentifier))
    {
        _smsInterceptor.DisableApplicationLauncher();
    }
}

Visual Basic .NET

Private _smsInterceptor As MessageInterceptor = Nothing

Private Sub Form1_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Load
    If Not MessageInterceptor.IsApplicationLauncherEnabled(_persistentIdentifier) Then
        ' Persistent notification does not yet exist - must explicitly create
        _smsInterceptor = New
 MessageInterceptor(InterceptionAction.NotifyAndDelete, False)
        _smsInterceptor.MessageCondition = New MessageCondition(MessageProperty.Body, _
                MessagePropertyComparisonType.StartsWith, "Contoso Data:", False)
        ' Make the interceptor persistent
        _smsInterceptor.EnableApplicationLauncher(_persistentIdentifier)
    Else
        ' Persistent notification already defined - create this instance using the
        ' same characteristics
        _smsInterceptor = New MessageInterceptor(_persistentIdentifier, False)
    End If

    ' Once the interceptor is created, add event handler. Whether the interceptor is constructed 
    ' explicitly or constructed from the persistent notification identifier, the event
    ' handling behavior is the same.
    AddHandler _smsInterceptor.MessageReceived, AddressOf SmsInterceptor_MessageReceived_OnThread
End Sub

' Remove persistent notification 
Private Sub MenuEx3Disable_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MenuEx3Disable.Click
    If Not _smsInterceptor Is Nothing Then
        If _smsInterceptor.ApplicationLaunchId = _persistentIdentifier And _
            MessageInterceptor.IsApplicationLauncherEnabled(_persistentIdentifier) Then
            _smsInterceptor.DisableApplicationLauncher()
        End If
    End If
End Sub