Coding4Fun : productivity

Coding 4 Fun - Windows 7 Taskbar

Coding4Fun — Tue, 25 Aug 2009 19:47:00 GMT

Looking to take advantage of some new Windows 7 goodness? Learn how to work with some of the great new taskbar features to create a more streamlined user interface.

Arian T. Kulp
http://www.ariankulp.com

Project site: Codeplex link
Source code and precompiled: Downloads
Difficulty: Intermediate
Time Required: 3 hours
Cost: Free!
Software Needed: Visual Basic or Visual C# Express, Windows API Code Pack, Windows 7 (RC or greater)

Introduction

Windows 7 brings with it a large number of new features that will be available to developers from day one. These are really nice additions that will make applications more natural to work with. One of the new areas of enhancements is the taskbar. The taskbar has always been a pretty simple way to see what's running and switch between tasks. Moving from XP to Vista, we got cool previews, but that's about it. With Windows 7, now we can drag-and-drop minimized app icons to change their order, we can pin apps there even if they aren't running (replacing Quick Launch functionality). You can also right-click the icons to restore or close the window. Better still, many apps give you additional information upon right-click, such as Recent lists, or actions like changing your Live Messenger status:

Image 1: Jump list for Windows Live Messenger

In this article, I would like to dig into the following notable new features:

Customizable preview
Icon overlays
Progress indication
Toolbar buttons

None of these features are very difficult to use due to the Windows API Code Pack. This download is a free (but unsupported) package from Microsoft on the MSDN Code Gallery. Version 1.0 was released on August 6, after a number of earlier pre-releases. Since many of the new features are specific to Windows 7, they are not in the .NET Base Class Libraries. This package exposes them for .NET so you don't have to do any of your own interop.

This sample is written for Windows Forms, but it works equally well with WPF. These four features are easy to integrate into any application that you write.

Customizable Previews

To start with, we'll dig into customizable previews. This refers to the ability to change the Aero Peek preview that shows up in the task bar when you hover over a minimized application.

Image 2: Aero Peek preview for Windows Live Writer

If you create any basic application and launch it (F5), the taskbar preview will be an exact copy of the application's main window. In fact, Windows gets this from the DWM, or Desktop Window Manager. This is cached already so it makes sense to use it here. Overriding it though is fairly easy. In a photo editing application, it might be better to have the preview show the current image by itself -- without all of the toolbars and menus. You can also choose to take the cached thumbnail from the DWM and just crop a portion of it - like to remove a ribbon UI from the top.

The TaskbarManager class is responsible for exposing progress state, thumbnail, overlay icons, and other similar properties. These functions would otherwise be scattered across various Win32 API calls, but the Windows API Code Pack simplifies this immensely. The first step is to create a reference to it and obtain the static reference:

Visual Basic

Private windowsTaskbar As TaskbarManager = TaskbarManager.Instance

Visual C#

private TaskbarManager windowsTaskbar = TaskbarManager.Instance;

You'll use this reference throughout your application for any taskbar manipulation. In order to clip your preview, just specify the window handle and the region. An easy way is to specify the Location and Size properties of a control. In this sample, it's a GroupBox, but in another application it might make more sense to clip to a PictureBox or other control:

Visual Basic

windowsTaskbar.TabbedThumbnail.SetThumbnailClip(Me.Handle, New Rectangle(groupBox2.Location, groupBox2.Size))

Visual C#

windowsTaskbar.TabbedThumbnail.SetThumbnailClip(this.Handle, new Rectangle(groupBox2.Location, groupBox2.Size));

Icon Overlays

Icon overlays allow you to display a visual representation of your program's state. This has been possible for some time using icons in the notification area (battery level low, anti-virus disabled), but until now it hasn't been possible as part of your taskbar icon. Now you can choose any icon (from an ICO file or extracted from an executable or DLL) and the taskbar manager will display it directly in the task bar overlaid on your application icon. This is used in Windows Live Messenger to show your login status (offline, busy, available, etc.):

Image 3: Windows Live Messenger with overlay for offline status

This is great for providing information at a glance. Especially as more and more users are hiding their cluttered notification tray icons and wouldn't see the indicator otherwise.

The beautiful thing is that the TaskbarManager class allows you to set this with one line of code:

Visual Basic

windowsTaskbar.SetOverlayIcon(me.Handle, My.Resources.Green, "Green")

Visual C#

windowsTaskbar.SetOverlayIcon(this.Handle, TaskbarDemo.Properties.Resources.Green, "Green");

The same API call can also lets you clear an overlay:

Visual Basic

windowsTaskbar.SetOverlayIcon(Me.Handle, Nothing, Nothing)

Visual C#

windowsTaskbar.SetOverlayIcon(this.Handle, null, null);

Progress Indication

As your application works through something, such as file copying, downloading, or processing a data set, you might be tempted to display a progress bar in a popup dialog. If you're really diabolical you might even make this a modal dialog! In our brave new world of Windows 7 though, we no longer need to subject our users to this. Instead of cluttering up the screen, we can reflect the current progress of any single operation by displaying a progress bar behind our application icon, such as Windows Explorer during a file copy:

Image 4: Windows Explorer with file copy progress indication

It's faint, but you should be able to see the bar at around the 15-20% point behind the folder. There are actually a number of states that you can instruct the taskbar to display, then you just provide progress value updates as needed.

In this sample application, we display the various TaskbarProgressBarState enumerated values in a ComboBox:

Visual Basic

comboBoxProgressState.DataSource = System.Enum.GetNames(GetType(TaskbarProgressBarState))

Visual C#

comboBoxProgressState.DataSource = Enum.GetNames(typeof(TaskbarProgressBarState));

When changes are made, we update the state using the SetProgressState call:

Visual Basic

windowsTaskbar.SetProgressState(CType(System.Enum.Parse(GetType(TaskbarProgressBarState), comboBoxProgressState.Text), TaskbarProgressBarState))

Visual C#

windowsTaskbar.SetProgressState((TaskbarProgressBarState)Enum.Parse(typeof(TaskbarProgressBarState), comboBoxProgressState.Text));

Then, we use a TrackerBar to select the current value which gets posted using the SetProgressState call:

Visual Basic

windowsTaskbar.SetProgressValue(trackProgress.Value, 100)

Visual C#

windowsTaskbar.SetProgressValue(trackProgress.Value, 100);

Toolbar Buttons

One of the new features that really has me excited is the ability to add buttons to the preview image. This is a very underutilized feature so far, though it's visible in Windows Media Player:

Image 5: Windows Media Player preview with toolbar buttons for media control

Notice the Pause, Previous, and Next buttons under the Aero Peek. Those are fully-functional. The great thing is that you can add them to your application easily, and bind event handlers to them like any other buttons. You don't get design-time support like for forms and menus, but you really don't need it.

Start by decaring a ThumbnailToolbarButton:

Visual Basic

Private WithEvents buttonFirst As ThumbnailToolbarButton

Visual C#

private ThumbnailToolbarButton buttonFirst;

You can set the image, a label (shown on hover), enabled or not, and other common Button properties. Here I will create the button and point it to an image stored as a resource, and a label:

Visual Basic

buttonFirst = New ThumbnailToolbarButton(My.Resources.search, "Search")

Visual C#

buttonFirst = new ThumbnailToolbarButton(Properties.Resources.first, "First Image");

Next, I need to attach an event handler to it. In Visual Basic, since buttonFirst was declared using WithEvents, you can use the Handles keyword in the declaration of the event handler. In C#, you can type "buttonFirst.Click +=" and then press the TAB key twice. This will fill out the rest of the line *and* create an event handler stub:

Visual Basic

Private Sub buttonFirst_Click(ByVal sender As Object, ByVal e As ThumbnailButtonClickedEventArgs) Handles buttonFirst.Click

Visual C#

buttonFirst.Click += new EventHandler<ThumbnailButtonClickedEventArgs>(buttonFirst_Click);

Finally, add the buttons using the TaskbarManager instance. The AddButtons call takes a list of parameters, so you can just add other buttons by separating them with commas:

Visual Basic

windowsTaskbar.ThumbnailToolbars.AddButtons(Me.Handle, buttonFirst)

Visual C#

windowsTaskbar.ThumbnailToolbars.AddButtons(this.Handle, buttonFirst);

Just fill in something for your event handler to do (a simple MessageBox in the sample application), and you're done! It's super-easy and it adds a new dimension of interactivity with your application. This could replace menu commands in a notification icon, or simply present common actions. It doesn't make sense in every application, but it's easy to add when you need it.

Next Steps

The next step is to evaluate your own applications to see what makes to add. While custom previews and toolbar buttons don't make sense for every application, progress indication and custom overlays can often be a good fit. Of course, remember that if you implement any of this, it won't be visible in Windows Vista or earlier. Be sure to have a secondary way to access these same functions. Toolbar buttons and overlays can be accomplished in the notification icon, and progress can always be displayed in a popup dialog as a fallback.

Conclusion

Windows 7 makes it easier to create very user-friendly applications. You may be able to augment existing applications to take advantage of these features, or at least keep them in mind when designing new applications. Pretty quickly, these will be considered common place and you'll want your application to play well on the desktop.

If you haven't yet, download Visual Studio 2008 Express Edition (Visual Basic or Visual C#), and then download the Windows API Code Pack so you can get started! Of course you'll need at least the Windows 7 RC build in order to actually test any of this, but the final release is in just a few months. Get ready for it now!

TwitterDrive – Author Interview

Coding4Fun — Wed, 01 Apr 2009 10:10:00 GMT

In case you haven’t heard, TwitterDrive is going to revolutionize the way files are stored and shared on the Internet. Today, we had the rare privilege of sitting down and talking with Brian Peek, creator of this cutting edge product.

Q: Thanks for taking the time to speak with us today. Why don’t you tell us a little bit about yourself?

A: I’m surprised I even considered this. I’m so above you people now. But anyway, my name is Brian Peek, and until I developed this app, I was working, like you people, at a job that was pointless. Now, I’m on the cusp of owning people like you. Once this takes off, I can finally pursue my life’s other passion: hip-hop music.

Q: I don’t doubt it. So why don’t you tell us a little bit about TwitterDrive and how you came up with the idea?

A: TwitterDrive is the next “big thing” in cloud storage. There are a ton of cloud storage providers out there now, most of which cost money or have limited disk space available. But why should we live with limitations like these? Twitter provides their users with unlimited storage for sending and saving their “tweets”. My amazingly brilliant idea was to take this service to the next level: using it to store and share files. That is, free cloud storage. Bet you wish you thought of that.

Q: I sure do. So how does TwitterDrive work?

A: It works perfectly. Simply run the TwitterDrive application, provide your Twitter user credentials, and then start uploading and downloading files. Files are compressed, base64 encoded, and then uploaded to Twitter 140 bytes at a time, fully maximizing the amount of space allowed per tweet.

Imagine…uploading 14 thousand bytes of data per hour! Or downloading two megabytes per hour! Match that, SkyDrive.

Q: That sounds amazing. Unlimited storage for free.

It is amazing. Which is why I thought of it and you didn’t. Welcome to the future.

Q: So are there any limitations?

Only if you consider uploading 14 thousand bytes per hour a limitation. But really, who has that much data? 14k should be enough for everybody.

Q: What about data protection? Is the file data protected in any way?

The data is compressed, encoded and chunked up into bits. Who needs more security than that? Besides, users would need to know your TwitterDrive account username to get at the data. Security through obscurity is a win for everyone!

Q: Do you have any new features planned for TwitterDrive?

New features? No. It’s already the most complete, useful and bug free application ever developed. It doesn’t require any additional features.

Now if you’ll excuse me, I have to start planning which jet I want to buy.

Well there you have it, folks. We are at the cusp of a revolution. Are you ready?

Download TwitterDrive here. Want to learn more? Learn how it was made!

TwitterDrive – The Revolution in Cloud Storage

Coding4Fun — Wed, 01 Apr 2009 10:05:00 GMT

	In this article, Brian Peek will provide a technical overview of TwitterDrive, an application used to store and retrieve files via the Twitter messaging service.
Brian Peek ASPSOFT, Inc. Difficulty: Intermediate Time Required: 2-3 hours Cost: Free Software: Visual C# Express 2008 SP1, Visual Basic Express 2008 SP1, or Visual Studio 2008 SP1, .NET Framework 3.5 SP1 Hardware: None Download: Application, Source Code Discussion Forum: Forum

Introduction

As you’ve probably guessed by now, TwitterDrive is my April Fool’s Day application for Coding4Fun this year. While the application does actually work, the limitations of Twitter make it functionally useless. That said, I’ll still take you through the important parts as there is some value in the code with regard to the Twitter API, LINQ to XML, threading, and a couple other things.

How It Works

Not very well, actually. The concept is we take a file, compress it, uuencode/base64 encode it (that is, make a text representation of the binary contents), and then upload it 140 characters at a time to Twitter as status messages. When the file upload is complete, an index is written of every file that is currently stored on Twitter with some information that can be used to later retrieve the file.

Twitter

Let’s start with the Twitter API. Full documentation on this API can be found at:

http://apiwiki.twitter.com/

TwitterDrive only requires a very small subset of this functionality to work. We need the ability to post a new status message, download a user timeline, destroy a status, and verify the user’s credentials. All of these things are handled in the TwitterService class.

The heart of this class consists of two methods: GetTwitter and PostTwitter. GetTwitter will make a GET request to Twitter of the specified URL, and PostTwitter will make a POST request to Twitter of the specified URL with the supplied data.

private XDocument GetTwitter(string url)
{
    WebClient wc = new WebClient();

    // only authenticate if we have a password
    if(!string.IsNullOrEmpty(Password))
        wc.Credentials = new NetworkCredential(Username, Password);

    Stream s = wc.OpenRead(url);

    // return an XDocument for LINQ
    XmlTextReader xmlReader = new XmlTextReader(s);
    XDocument xdoc = XDocument.Load(xmlReader);
    xmlReader.Close();
    return xdoc;
}

private XDocument PostTwitter(string url, string data)
{
    byte[] bytes = Encoding.ASCII.GetBytes(data);

    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
    request.Method = "POST";

    // if we're writing, we need to authenticate
    request.Credentials = new NetworkCredential(Username, Password);

    // if this is 'true', Twitter breaks
    request.ServicePoint.Expect100Continue = false;
    request.ContentType = "application/x-www-form-urlencoded";
    request.ContentLength = bytes.Length;

    Stream reqStream = request.GetRequestStream();
    reqStream.Write(bytes, 0, bytes.Length);

    // turn the response into an XDocument for use with LINQ
    HttpWebResponse resp = (HttpWebResponse)request.GetResponse();
    XmlReader xmlReader = XmlReader.Create(resp.GetResponseStream());
    XDocument xdoc = XDocument.Load(xmlReader);
    xmlReader.Close();
    return xdoc;
}

Private Function GetTwitter(ByVal url As String) As XDocument
    Dim wc As New WebClient()

    ' only authenticate if we have a password
    If (Not String.IsNullOrEmpty(Password)) Then
        wc.Credentials = New NetworkCredential(Username, Password)
    End If

    Dim s As Stream = wc.OpenRead(url)

    ' return an XDocument for LINQ
    Dim xmlReader As New XmlTextReader(s)
    Dim xdoc As XDocument = XDocument.Load(xmlReader)
    xmlReader.Close()
    Return xdoc
End Function

Private Function PostTwitter(ByVal url As String, ByVal data As String) As XDocument
    Dim bytes() As Byte = Encoding.ASCII.GetBytes(data)

    Dim request As HttpWebRequest = CType(WebRequest.Create(url), HttpWebRequest)
    request.Method = "POST"

    ' if we're writing, we need to authenticate
    request.Credentials = New NetworkCredential(Username, Password)

    ' if this is 'true', Twitter breaks
    request.ServicePoint.Expect100Continue = False
    request.ContentType = "application/x-www-form-urlencoded"
    request.ContentLength = bytes.Length

    Dim reqStream As Stream = request.GetRequestStream()
    reqStream.Write(bytes, 0, bytes.Length)

    ' turn the response into an XDocument for use with LINQ
    Dim resp As HttpWebResponse = CType(request.GetResponse(), HttpWebResponse)
    Dim xmlReader As XmlReader = XmlReader.Create(resp.GetResponseStream())
    Dim xdoc As XDocument = XDocument.Load(xmlReader)
    xmlReader.Close()
    Return xdoc
End Function

Each of these methods will use the NetworkCredentials object to authenticate to Twitter for reading or writing, as required. Twitter API methods return simple XML objects. Both GetTwitter and PostTwitter take these XML documents and turn them into XDocument objects that can be easily queried with LINQ to XML later.

We only need to call two Twitter “get” methods: user_timeline and verify_credentials. There are two overloaded methods which call the user_timeline API:

public IList<Status> GetUserTimeline(int page, int count)
{
    XDocument xdoc = GetTwitter(string.Format("http://twitter.com/statuses/user_timeline.xml?count={0}&page={1}&id={2}", count, page, Username));
    IList<Status> statuses = ParseStatuses(xdoc);
    return statuses;
}

public IList<Status> GetUserTimeline(int since_id, int max_id, int page, int count)
{
    XDocument xdoc = GetTwitter(string.Format("http://twitter.com/statuses/user_timeline.xml?since_id={0}&max_id={1}&count={2}&page={3}&id={4}", since_id, max_id, count, page, Username));
    IList<Status> statuses = ParseStatuses(xdoc);
    return statuses;
}

Public Function GetUserTimeline(ByVal page As Integer, ByVal count As Integer) As IList(Of Status)
    Dim xdoc As XDocument = GetTwitter(String.Format("http://twitter.com/statuses/user_timeline.xml?count={0}&page={1}&id={2}", count, page, Username))
    Dim statuses As IList(Of Status) = ParseStatuses(xdoc)
    Return statuses
End Function

Public Function GetUserTimeline(ByVal since_id As Integer, ByVal max_id As Integer, ByVal page As Integer, ByVal count As Integer) As IList(Of Status)
    Dim xdoc As XDocument = GetTwitter(String.Format("http://twitter.com/statuses/user_timeline.xml?since_id={0}&max_id={1}&count={2}&page={3}&id={4}", since_id, max_id, count, page, Username))
    Dim statuses As IList(Of Status) = ParseStatuses(xdoc)
    Return statuses
End Function

Each of these methods creates a URL with the appropriate query string arguments (see the Twitter API docs for the full list) and then calls our ParseStatuses method with the returned XDocument, which will give us a List of Status objects. The Twitter-returned status contains a variety of data, such as:

<status>
<created_at>Mon Mar 30 07:20:57 +0000 2009</created_at>
<id>1234567123</id>
<text>Status text</text>
<source>web</source>
<truncated>false</truncated>
<in_reply_to_status_id/>
<in_reply_to_user_id/>
<favorited>false</favorited>

<user>
<id>12345678</id>
<name>Some Person</name>
<screen_name>myscreenname</screen_name>
<description/>
<location/>

<profile_image_url>
http://static.twitter.com/images/default_profile_normal.png
</profile_image_url>
<url/>
<protected>false</protected>
<followers_count>1</followers_count>
</user>
</status>

We only care about a few elements and only parse those, namely id, text, user (which is in itself an XML chunk), and created_at.

private IList<Status> ParseStatuses(XContainer container)
{
    // return a list of Status objects
    var query = from status in container.Descendants("statuses").Descendants("status")
                select ParseStatus(status);
    return query.ToList();
}

private Status ParseStatus(XDocument xdoc)
{
    // create a Status object from the returned XML
    var query = from status in xdoc.Descendants("status")
                select ParseStatus(status);

    return query.SingleOrDefault();
}

private Status ParseStatus(XElement xelement)
{
    Status s = new Status()
                {
                    ID = (int)xelement.Element("id"),
                    Text = (string)xelement.Element("text"),
                    UserInformation = ParseUserInformation(xelement.Element("user")),
                    // HTTP-formatted date
                    CreatedAt = DateTime.ParseExact(xelement.Element("created_at").Value,
                            "ddd MMM dd HH:mm:ss zzzz yyyy",
                            CultureInfo.GetCultureInfoByIetfLanguageTag("en-us"),
                            DateTimeStyles.AllowWhiteSpaces)
                };

    return s;
}

Private Function ParseStatuses(ByVal container As XContainer) As IList(Of Status)
    ' return a list of Status objects
    Dim query = _
        From status In container.Descendants("statuses").Descendants("status") _
        Select ParseStatus(status)
    Return query.ToList()
End Function

Private Function ParseStatus(ByVal xdoc As XDocument) As Status
    ' create a Status object from the returned XML
    Dim query = _
        From status In xdoc.Descendants("status") _
        Select ParseStatus(status)

    Return query.SingleOrDefault()
End Function

Private Function ParseStatus(ByVal xelement As XElement) As Status
    Dim s As New Status() With { _
        .ID = CInt(xelement.Element("id")), _
        .Text = CStr(xelement.Element("text")), _
        .UserInformation = ParseUserInformation(xelement.Element("user")), _
        .CreatedAt = DateTime.ParseExact(xelement.Element("created_at").Value, _
                    "ddd MMM dd HH:mm:ss zzzz yyyy", CultureInfo.GetCultureInfoByIetfLanguageTag("en-us"), DateTimeStyles.AllowWhiteSpaces) }
    Return s
End Function

These methods use LINQ to XML to drill down into the XML document to parse out individual status objects and return them as a list. You will notice the user element contains a user_information XML chunk, and the ParseUserInformation method parses that data

private UserInformation ParseUserInformation(XContainer container)
{
    // parse and return a UserInformation object
    return new UserInformation
    {
        ID = (int)container.Element("id"),
        Name = (string)container.Element("name"),
        ScreenName = (string)container.Element("screen_name")
    };
}

Private Function ParseUserInformation(ByVal container As XContainer) As UserInformation
    ' parse and return a UserInformation object
    Dim ui As New UserInformation() With { _
        .ID = CInt(container.Element("id")), _
        .Name = CStr(container.Element("name")), _
        .ScreenName = CStr(container.Element("screen_name")) }

    Return ui
End Function

The verify_credentials API is called in a similar manner, but in this case we will “listen” for a 401 (Unauthorized) exception and return true or false appropriately:

public bool VerifyTwitterCredentials(string username, string password)
{
    try
    {
        WebClient wc = new WebClient();
        wc.Credentials = new NetworkCredential(username, password);
        Stream s = wc.OpenRead("http://twitter.com/account/verify_credentials.xml");
        s.Close();
    }
    catch(WebException we)
    {
        if((we.Response as HttpWebResponse).StatusCode == HttpStatusCode.Unauthorized)
            return false;
        throw;
    }

    return true;
}

With the “get” methods out of the way, we can write our “post” methods. We only need two methods here as well: update and destroy. Update is used to write a new tweet to Twitter, and destroy is used to remove an existing tweet.

public Status UpdateStatus(string status)
{
    XDocument doc = PostTwitter("http://twitter.com/statuses/update.xml", "status=" + status);
    Status s =  ParseStatus(doc);

    // if we don't get the text we sent, we hit the rate limit...
    if(s.Text != HttpUtility.UrlDecode(status))
        throw new TwitterRateLimitException("Twitter upload limit reached.");
    return s;
}

public Status Destroy(int status)
{
    XDocument doc = PostTwitter("http://twitter.com/statuses/destroy/" + status + ".xml", "id=" + status);
    return ParseStatus(doc);
}

Public Function VerifyTwitterCredentials(ByVal username As String, ByVal password As String) As Boolean
    Try
        Dim wc As New WebClient()
        wc.Credentials = New NetworkCredential(username, password)
        Dim s As Stream = wc.OpenRead("http://twitter.com/account/verify_credentials.xml")
        s.Close()
    Catch we As WebException
        If (TryCast(we.Response, HttpWebResponse)).StatusCode = HttpStatusCode.Unauthorized Then
            Return False
        End If
        Throw
    End Try

    Return True
End Function

The UpdateStatus method has a bit of code to determine whether we hit Twitter’s upload rate limit. Twitter will limit you to about 100 tweets per hour. The only way to determine if you’ve hit the upload limit (that I found at least) is to compare the text from status element returned from the update to the text that was sent. If the upload limit is hit, the last valid status element will be returned, and therefore the text blocks will not match. If this happens, we throw our own custom TwitterRateLimitException up the stack for the UI to handle.

TwitterDrive

Now that we can talk to Twitter, the next step is to write the code that uses these methods to store and retrieve our file data. This code is located in the TwitterDrive class.

One of the goals I had was to make this application thread-happy to provide a responsive UI while files are uploaded and downloaded. Therefore, this class sets up three events which can be hooked by the UI to receive periodic status information:

public class ChunkEventArgs : EventArgs
{
    public Status Status;
    public int ChunkLength;
    public int Total;

    public ChunkEventArgs(Status status, int length, int total)
    {
        Status = status;
        ChunkLength = length;
        Total = total;
    }
}

...

// event handlers for async file transfer
public event EventHandler<ChunkEventArgs> ChunkUpload;
public event EventHandler<ChunkEventArgs> ChunkDownload;
public event EventHandler<EventArgs> TransferComplete;

Public Class ChunkEventArgs
    Inherits EventArgs
    Public Status As Status
    Public ChunkLength As Integer
    Public Total As Integer

    Public Sub New(ByVal status As Status, ByVal length As Integer, ByVal total As Integer)
        Status = status
        ChunkLength = length
        Me.Total = total
    End Sub
End Class

These events will be called at the appropriate times and provide information to allow the UI to draw a progress bar and other status information.

The UploadFile method does exactly what you think: it uploads the file specified. The file contents are loaded into memory, compressed, base64 encoded, and finally URL encoded. Then, this large string is cut into 140 character chunks and sent to Twitter, one chunk at a time. After each chunk is uploaded, the ChunkUpload event is called. Finally, when all chunks are uploaded, a new FileEntry object is created, added to the in-memory file index, and that index is finally written to the top of the Twitter status list.

public void UploadFile(string path)
{
    Status s = null;
    int startID = 0;
    int length = 0;
    int chunkLength = 140;

    // encode the file
    string file = EncodeFile(path);

    // upload the chunks
    for(int i = 0; i < file.Length; i+= chunkLength)
    {
        // get the proper length (i.e. don't get full 140 if we're at the end)
        string chunk = file.Substring(i, Math.Min(chunkLength, file.Length-i));

        // handle the case where we chopped a chunk in the middle of an encoded character
        // in this case, chop off the encoded data and reset the counter
        if(chunk.EndsWith("%2"))
        {
            chunk = chunk.Substring(0, chunk.Length-2);
            i -= 2;
        }

        if(chunk.EndsWith("%"))
        {
            chunk = chunk.Substring(0, chunk.Length-1);
            i -= 1;
        }

        try
        {
            // upload the chunk
            s = _twitter.UpdateStatus(chunk);

            // notify listeners that we uploaded
            if(ChunkUpload != null)
                ChunkUpload(this, new ChunkEventArgs(s, chunk.Length, file.Length));
        }
        catch(TwitterRateLimitException)
        {
            throw new TwitterDriveException("Twitter upload limit reached.  Please try again later.");
        }

        if(i == 0)
            startID = s.ID;

        length++;
    }

    // create a new FileEntry for this file
    FileEntry fe = new FileEntry()
    {
        Filename = Path.GetFileName(path),
        StartStatus = startID,
        EndStatus = s.ID,
        Length = length,
        FileIndex = GetNextIndex()
    };

    // update the index
    UpdateFileIndex(fe);

    // notify we're done
    if(TransferComplete != null)
        TransferComplete(this, null);
}

Public Function UploadFile(ByVal filepath As String)
    Dim s As Status = Nothing
    Dim startID As Integer = 0
    Dim length As Integer = 0
    Dim chunkLength As Integer = 140

    ' encode the file
    Dim file As String = EncodeFile(filepath)

    ' upload the chunks
    For i As Integer = 0 To file.Length - 1 Step chunkLength
        ' get the proper length (i.e. don't get full 140 if we're at the end)
        Dim chunk As String = file.Substring(i, Math.Min(chunkLength, file.Length-i))

        ' handle the case where we chopped a chunk in the middle of an encoded character
        ' in this case, chop off the encoded data and reset the counter
        If chunk.EndsWith("%2") Then
            chunk = chunk.Substring(0, chunk.Length-2)
            i -= 2
        End If

        If chunk.EndsWith("%") Then
            chunk = chunk.Substring(0, chunk.Length-1)
            i -= 1
        End If

        Try
            ' upload the chunk
            s = _twitter.UpdateStatus(chunk)

            ' notify listeners that we uploaded
            RaiseEvent ChunkUpload(Me, New ChunkEventArgs(s, chunk.Length, file.Length))
        Catch e1 As TwitterRateLimitException
            Throw New TwitterDriveException("Twitter upload limit reached.  Please try again later.")
        End Try

        If i = 0 Then
            startID = s.ID
        End If

        length += 1
    Next i

    ' create a new FileEntry for this file
    Dim fe As New FileEntry() With {.Filename = Path.GetFileName(filepath), .StartStatus = startID, .EndStatus = s.ID, .Length = length, .FileIndex = GetNextIndex()}

    ' update the index
    UpdateFileIndex(fe)

    ' notify we're done
    RaiseEvent TransferComplete(Me, Nothing)
End Function

Let’s take a closer look at the EncodeFile method:

private string EncodeFile(string path)
{
    // load the file
    byte[] buff = File.ReadAllBytes(path);

    // compress
    MemoryStream ms = new MemoryStream();
    GZipStream gs = new GZipStream(ms, CompressionMode.Compress);
    gs.Write(buff, 0, buff.Length);
    gs.Close();

    byte[] buffCompressed = ms.ToArray();

    // base64, urlencode
    return HttpUtility.UrlEncode(Convert.ToBase64String(buffCompressed));
}

Private Function EncodeFile(ByVal path As String) As String
    ' load the file
    Dim buff() As Byte = File.ReadAllBytes(path)

    ' compress
    Dim ms As New MemoryStream()
    Dim gs As New GZipStream(ms, CompressionMode.Compress)
    gs.Write(buff, 0, buff.Length)
    gs.Close()

    Dim buffCompressed() As Byte = ms.ToArray()

    ' base64, urlencode
    Return HttpUtility.UrlEncode(Convert.ToBase64String(buffCompressed))
End Function

The code here reads the bytes of a file into a byte array. Then, a MemoryStream object is created and tied to a GZipStream (compression) object. Next, the byte array is written to the stream which will compress the data on the fly. Once the stream is closed, calling ToArray on the MemoryStream will return a byte array of the compressed data. The byte array is base64 encoded (turned into text) and finally URL encoded so it can be sent to Twitter.

The file index is written at the end of each file upload. The index is comprised of a delimited string which contains the data in the FileEntry object. Each file is uploaded as one tweet, with an end marker to denote where the file index ends.

private void WriteFileEntries()
{
    // write an end marker (write this first since they come out in reverse order later)
    _twitter.UpdateStatus(FileEntryEnd);

    for(int i = 0; i < _fileEntries.Count; i++)
        WriteFileEntry(_fileEntries[i]);
}

private void WriteFileEntry(FileEntry fe)
{
    // simple delimited list of data
    string entry = string.Format(FileEntryHeader +
                                "{0}" + FileEntrySeparator + 
                                "{1}" + FileEntrySeparator +
                                "{2}" + FileEntrySeparator +
                                "{3}" + FileEntrySeparator +
                                "{4}", 
                                fe.Filename, fe.StartStatus, fe.EndStatus, fe.Length, fe.FileIndex);
    _twitter.UpdateStatus(entry);
}

Private Sub WriteFileEntries()
    ' write an end marker (write this first since they come out in reverse order later)
    _twitter.UpdateStatus(FileEntryEnd)

    Dim i As Integer = 0
    Do While i < _fileEntries.Count
        WriteFileEntry(_fileEntries(i))
        i += 1
    Loop
End Sub

Private Sub WriteFileEntry(ByVal fe As FileEntry)
    ' simple delimited list of data
    Dim entry As String = String.Format(FileEntryHeader & "{0}" & FileEntrySeparator & "{1}" & FileEntrySeparator & "{2}" & FileEntrySeparator & "{3}" & FileEntrySeparator & "{4}", fe.Filename, fe.StartStatus, fe.EndStatus, fe.Length, fe.FileIndex)
    _twitter.UpdateStatus(entry)
End Sub

A file list can be retrieved and parsed out with the following code:

public IList<FileEntry> GetFileIndex()
{
    bool end = false;
    int page = 1;

    // the index should be the last things tweeted, but if we have a failed upload, it may not be
    while(!end && page < 5)
    {
        IList<Status> indexes = _twitter.GetUserTimeline(page, 200);

        _fileEntries.Clear();

        // parase out the file entries
        foreach(Status index in indexes)
        {
            FileEntry fe = ParseFileIndexString(index.Text);
            if(fe != null)
            {
                fe.IndexStatusId = index.ID;
                _fileEntries.Add(fe);
            }

            if(index.Text.StartsWith(FileEntryEnd))
            {
                end = true;
                break;
            }
        }
        page++;
    }
    return _fileEntries;
}

private FileEntry ParseFileIndexString(string index)
{
    if(!index.StartsWith(FileEntryHeader))
        return null;

    string[] fileEntry = index.Split(Convert.ToChar(FileEntrySeparator));
    FileEntry fe = new FileEntry()
                    {
                        Filename = fileEntry[0].Replace(FileEntryHeader, string.Empty),
                        StartStatus = int.Parse(fileEntry[1]),
                        EndStatus = int.Parse(fileEntry[2]),
                        Length = int.Parse(fileEntry[3]),
                        FileIndex = int.Parse(fileEntry[4])
                    };
    return fe;
}

Public Function GetFileIndex() As IList(Of FileEntry)
    Dim [end] As Boolean = False
    Dim page As Integer = 1

    ' the index should be the last things tweeted, but if we have a failed upload, it may not be
    Do While (Not [end]) AndAlso page < 5
        Dim indexes As IList(Of Status) = _twitter.GetUserTimeline(page, 200)

        _fileEntries.Clear()

        ' parase out the file entries
        For Each index As Status In indexes
            Dim fe As FileEntry = ParseFileIndexString(index.Text)
            If fe IsNot Nothing Then
                fe.IndexStatusId = index.ID
                _fileEntries.Add(fe)
            End If

            If index.Text.StartsWith(FileEntryEnd) Then
                [end] = True
                Exit For
            End If
        Next index
        page += 1
    Loop
    Return _fileEntries
End Function

Private Function ParseFileIndexString(ByVal index As String) As FileEntry
    If (Not index.StartsWith(FileEntryHeader)) Then
        Return Nothing
    End If

    Dim fileEntry() As String = index.Split(Convert.ToChar(FileEntrySeparator))
    Dim fe As New FileEntry() With {.Filename = fileEntry(0).Replace(FileEntryHeader, String.Empty), .StartStatus = Integer.Parse(fileEntry(1)), .EndStatus = Integer.Parse(fileEntry(2)), .Length = Integer.Parse(fileEntry(3)), .FileIndex = Integer.Parse(fileEntry(4))}
    Return fe
End Function

This code will retrieve the user’s timeline, loop through the tweets, looking for file index entries (those that start with the proper delimiter). When one is found, the data is parsed back into a FileEntry object and added to the in-memory cache. You will note that the GetFileIndex method will read up to 1000 tweets looking for the end marker before giving up.

Now that we can upload files and build the index, we need to be able to download, decode and save a file. This is done in the obviously named DownloadFile method:

public void DownloadFile(FileEntry fe, string path)
{
    StringBuilder sb = new StringBuilder(fe.Length * 140);

    // get statuses for this user starting/ending at the IDs for this file
    IList<Status> chunks = _twitter.GetUserTimeline(fe.StartStatus-1, fe.EndStatus, 1, 200);

    // order them from oldest to newest
    var orderedChunks = from chunk in chunks
                        orderby chunk.ID ascending
                        select chunk;

    foreach(Status chunk in orderedChunks)
    {
        // trim off any extra characters
        string newChunk = chunk.Text.TrimEnd('.').Trim();
        sb.Append(newChunk);

        // notify listeners that we downloaded a chunk
        if(ChunkDownload != null)
            ChunkDownload(this, new ChunkEventArgs(chunk, newChunk.Length, fe.Length * 140));
    }

    // decode and write the file
    byte[] buff = DecodeFile(sb.ToString());
    File.WriteAllBytes(Path.Combine(path, fe.Filename), buff);

    // notify that we're done
    if(TransferComplete != null)
        TransferComplete(this, null);
}

Public Function DownloadFile(ByVal fe As FileEntry, ByVal filepath As String)
    Dim sb As New StringBuilder(fe.Length * 140)

    ' get statuses for this user starting/ending at the IDs for this file
    Dim chunks As IList(Of Status) = _twitter.GetUserTimeline(fe.StartStatus-1, fe.EndStatus, 1, 200)

    ' order them from oldest to newest
    Dim orderedChunks = _
        From chunk In chunks _
        Order By chunk.ID Ascending _
        Select chunk

    For Each chunk As Status In orderedChunks
        ' trim off any extra characters
        Dim newChunk As String = chunk.Text.TrimEnd("."c).Trim()
        sb.Append(newChunk)

        ' notify listeners that we downloaded a chunk
        RaiseEvent ChunkDownload(Me, New ChunkEventArgs(chunk, newChunk.Length, fe.Length * 140))
    Next chunk

    ' decode and write the file
    Dim buff() As Byte = DecodeFile(sb.ToString())
    File.WriteAllBytes(Path.Combine(filepath, fe.Filename), buff)

    ' notify that we're done
    RaiseEvent TransferComplete(Me, Nothing)
End Function

This method returns the user’s timeline starting and ending at the tweets specified in the FileEntry object. The status list is ordered in ascending order (i.e. oldest to newest). Each status is appended to the previous using a StringBuilder object. When all chunks are processed, the file is decoded and saved to the chosen location.

public byte[] DecodeFile(string data)
{
    // base64 to binary
    byte[] buff = Convert.FromBase64String(data);

    // decompress
    MemoryStream ms = new MemoryStream(buff);
    GZipStream gs = new GZipStream(ms, CompressionMode.Decompress, false);

    // original
    byte[] decompressed = ReadAllBytes(gs);
    return decompressed;
}

Public Function DecodeFile(ByVal data As String) As Byte()
    ' base64 to binary
    Dim buff() As Byte = Convert.FromBase64String(data)

    ' decompress
    Dim ms As New MemoryStream(buff)
    Dim gs As New GZipStream(ms, CompressionMode.Decompress, False)

    ' original
    Dim decompressed() As Byte = ReadAllBytes(gs)
    Return decompressed
End Function

To decode the file, we do the opposite of what we did before: the file is converted to bytes from the base64 encoded string, a GZipStream is used to decompress the data, and the final, uncompressed file contents are returned to the caller to be saved to the disk.

Be sure to look through the entire TwitterDrive.cs/vb file for the full picture, but these are the important parts.

User Interface

The final piece is the user interface.

A very simple UI for uploading, downloading and deleting files. At the start of the application, the three TwitterDrive events are hooked: ChunkUpload, ChunkDownload, and TransferComplete. These three event handlers are used to update the progress bar on a dialog box that pops up during the file transfer.

When upload or download is selected, the file is selected, and a new thread is created to start the actual process. Here is what the download process looks like:

// start a new thread to grab the file
Thread t = new Thread(() => _twitterDrive.DownloadFile(fe, fbd.SelectedPath));
t.Start();

if(_progress.ShowDialog() == DialogResult.Cancel)
    t.Abort();
else
    MessageBox.Show("File download complete.", "TwitterDrive", MessageBoxButtons.OK, MessageBoxIcon.Information);

' start a new thread to grab the file
Dim t As New Thread(CType(Function() _twitterDrive.DownloadFile(fe, fbd.SelectedPath), ThreadStart))
t.Start()

If _progress.ShowDialog() = System.Windows.Forms.DialogResult.Cancel Then
    t.Abort()
Else
    MessageBox.Show("File download complete.", "TwitterDrive", MessageBoxButtons.OK, MessageBoxIcon.Information)
End If

A new thread is created, whose ThreadStart parameter is the DownloadFile method of the TwitterDrive class. The thread is started, and the progress dialog box is shown. If the progress box is cancelled, the thread is aborted, otherwise the dialog box is closed in response to the TransferComplete event sent by the TwitterDrive class.

Using the Application

Create a new Twitter account for use in TwitterDrive.
Enter the credentials for this new account in the provided textboxes and click Refresh. Or, if you want to download files from someone else, enter just the username and click Refresh.
Upload and download data at will.

Conclusion

And there we have it. A functionally useless application that actually works. Give it a try and find out what the limitations are. Just be sure to use a Twitter account that isn’t your main feed otherwise you’ll have some pretty angry followers.

Thanks

A special thanks to Mark Zaugg, Dan Fernandez, and Giovanni Montrone for helping me test this application. Giovanni is also partly responsible for this horrible idea after joking that I should Twitter him a file. So blame him.

Also thanks to Clint Rutkas for throwing together the icon (it’s a combo of the SkyDrive icon + the Twitter icon).

Bio

Brian is a Microsoft C# MVP who has been actively developing in .NET since its early betas in 2000, and who has been developing solutions using Microsoft technologies and platforms for even longer. Along with .NET, Brian is particularly skilled in the languages of C, C++ and assembly language for a variety of CPUs. He is also well-versed in a wide variety of technologies including web development, document imaging, GIS, graphics, game development, and hardware interfacing. Brian has a strong background in developing applications for the health-care industry, as well as developing solutions for portable devices, such as tablet PCs and PDAs. Additionally, Brian has co-authored the book "Coding4Fun: 10 .NET Programming Projects for Wiimote, YouTube, World of Warcraft, and More" published O'Reilly. He previously co-authored the book "Debugging ASP.NET" published by New Riders. Brian is also an author for MSDN's Coding4Fun website.

Inherited Message Distributing

Coding4Fun — Fri, 12 Sep 2008 00:35:05 GMT

Given a week off of school I found the time to start designing a system that had been thought up in a school class. The idea was simple, a webapp that lets a user reach the widest possible audience by distributing messages across many mediums. One message could be delivered to each recipient as an email, text message, instant message, or phone call to name a few possibilities. With this system, an already overworked teacher could take 30 seconds to send one message that was delivered to each student and parent instantly across multiple mediums. A sports coach could finally reach everyone on the team, without trying to post news on a site that was rarely checked and poorly maintained.

Robert Witoff

http://www.chalk2me.com/

Difficulty: Intermediate

Time Required: 3-6 hours

Cost: Free

Software: Visual Basic or Visual C# Express Editions

Hardware:

Download: Download

Disclaimer: Currently this article is C# only. If you want it in Visual Basic.Net, please comment and tell us so we can transcode it to VB.

Starting Out:

We thought we had come up with a cool concept, and I knew it wouldn’t be that difficult to build. After calling our dev-team into the office I started on it, by myself in my apartment. My goal was to have a single method to send any type of message that would then be picked up by an appropriate thread to deliver the message. As the whole idea here was to create and deliver messages, a logical place to start was a struct to hold our message fields. It’s always good to keep other services in mind while you’re building your own. I started off with the first 4 fields in any email. This covered message content and we only needed a bit more info to deliver the message. The medium type, along with an identifier field for your address (or screen name etc.), would cover this. Just in case a service we end up using needs a second identifier, I added one more. Check it out:

public struct ctMessage
{
    public ctMessage(string sendToUser, string fromUser, string subj, string msg, string

    mediumType, string mediumArg1, string mediumArg)
    {
        this.toUser = sendToUser;
        this.fromUser = fromUser;
        this.subject = subj;
        this.message = msg;
        this.mediumType = mediumType;
        this.mediumArg1 = mediumArg1;
        this.mediumArg2 = mediumArg2;
    }

    public string toUser; //name of recipient
    public string fromUser; //name of sender
    public string subject;
    public string message;
    public string mediumType; //which node should deliver this
    public string mediumArg1; //varies, to identify the recipient
    public string mediumArg2; //varies, to identify the recipient
}

Once we had a message designed I, of course, wanted to be able to send one! Eventually I wanted a bunch of different types of messages being sent, so a solid base class would save a ton of time later. Although all of the messaging services, or ‘nodes’ would undoubtedly send the messages completely different, they would all need to run in a similar thread that sent messages coming from a single location. By doing a good job writing an abstract base class, we could add new services by only overriding the 'send' method later.

This abstract class would have a field identifying the type of messages it will handle, and call an external send method whenever messages of that type existed. A continuous loop to poll for messages, given a modest polling frequency would do the trick. Notice the protected methods and fields that we'll want to override.

public abstract class ctNode
{
    public ctNode()
    {
        this.maxQueueSize = 100; //Set the size according to how long it will take to reach the Nth message
        this.msgQueue = new Queue(maxQueueSize);
        this.msPauseAfterRun = 10000; //If using a DB, polling it with no pause b/w queries is an unnecessary load
        this.runnerThread = new Thread(new ThreadStart(this.run));
    }

    private Thread runnerThread;
    protected int msPauseAfterRun;
    protected Queue msgQueue;
    public int maxQueueSize;

    void run()
    {
        while (true)
        {
            while (this.msgQueue.Count > 0)
            {
                //pop a message and send it
                ctMessage ctm = (ctMessage)msgQueue.Dequeue();

                try
                {
                    sendSingleMessage(ctm);
                }
                catch (Exception e)
                {
                    //Write a more detailed error log here
                    Console.writeLine("the message could not be sent!" + e.toString());
                }
            }

            //get new messages
            ctNode ctn = this;
            ctMessage[] newMessages = messageSender.getMessages(ref ctn, getRoomInQueue());

            //Wait some time before checking for more messages!
            if (newMessages.Length == 0)
                Thread.Sleep(msPauseAfterRun);
            else
                this.EnqueueMessages(newMessages);
        }
    }

    public virtual void EnqueueMessages(ctMessage[] messagesToSend)
    {
        int roomInQueue = maxQueueSize - msgQueue.Count;

        if (messagesToSend.Length > roomInQueue)
            throw new Exception("Too many Messages have been inserted");

        for (int i = 0; i < messagesToSend.Length; i++)
        {
            msgQueue.Enqueue(messagesToSend[i]);
        }
    }

    public virtual void EnqueueMessages(ctMessage messageToSend)
    {
        ctMessage[] ctm = new ctMessage[1];
        ctm[0] = messageToSend;
        this.EnqueueMessages(ctm);
    }

    protected virtual void sendSingleMessage(ctMessage ctm)
    {
        //code to send an individual message
    }

    public void startThread()
    {
        runnerThread.Name = this.nodeType;
        runnerThread.Start();
    }

    protected string nodeType;

    public string getNodeType()
    {
        return this.nodeType;
    }
}

You might have noticed the big thing missing from these classes, a place to store, and retrieve messages! I initially put our message storage into an external static class. This made them centralized, easily accessible from any other objects that might need to access them, simple to ensure thread safety, and gave us room to move to a smarter mechanism later (or database. Notice the simplicity:

public static class messageSender
{
    private static List<ctMessage> messagesToSend = new List<ctMessage>();

    public static ctMessage[] getMessages(ref ctNode nodeRef, int numberOfMessages)
    {
        //We'll do this in a database later, but for now this works similarly
        List<ctMessage> returnMessages = new List<ctMessage>();

        lock (messagesToSend)
            for (int i = 0; i < messagesToSend.Count; i++)
                if (messagesToSend[i].mediumArgs == nodeRef.getNodeType())
                {
                    returnMessages.Add(messagesToSend[i]);
                    messagesToSend.RemoveAt(i);
                    i--;
                }

        return returnMessages.ToArray();
    }

    public static void sendMessage(ctMessage message)
    {
        lock (messagesToSend)
            messagesToSend.Add(message);
    }
}

Now that the groundwork was done, I grabbed some eye drops and an energy drink to refresh for the best part, function! I started simple with an email node, and if you’ve played with email before in .net, you’ve definitely seen and loved the SmtpClient class in the System.Net.Mail Namespace. If you don’t already have a local SMTP client set up, you can easily use a Gmail account as an SMTP server. Check out the following implementation, notice we only had to set the node type, initialize the SmtpClient and override the send method. Send a message through our message sender, and watch the node pick up the message and deliver it. Inheritance rocks!

ctMessage ctm = new ctMessge("Friend", "Developer", "testing", "My first message", "email", "yourEmail@yourDomain.com", "");
messageSender.sendMessage(ctm);

public class ctNodeEmail : ctNode
{
    public ctNodeEmail() : base()
    {
        this.nodeType = "email";

        //
        //SET UP SMTP CLIENT
        //

        //GMAIL SERVER
        this.mSmtpClient = new SmtpClient("gmail.com/mail", 25);
        this.mSmtpClient.Host = "smtp.gmail.com";
        this.mSmtpClient.Port = 25;
        this.mSmtpClient.EnableSsl = true;
        this.mSmtpClient.Credentials = new System.Net.NetworkCredential("YOURADDRESS@gmail.com", "YOUR_PASSWORD");

        //LOCAL SERVER
        //this.mSmtpClient = new SmtpClient("localhost", 25);
    }

    SmtpClient mSmtpClient;

    protected override void sendSingleMessage(ctMessage ctm)
    {
        MailMessage msgMail = new MailMessage(new MailAddress(ctm.fromUser + "@ChalkTalkNow.com"), new MailAddress(ctm.mediumArgs));
        msgMail.Subject = ctm.subject;
        string msg = ctm.message;
        msgMail.Body = msg;

        // Send the mail message
        mSmtpClient.Send(msgMail);
    }
}

After writing this so quickly I wanted something a bit more than email, and knew text messages were only a step away. It’s no secret that all major cell companies give your phone an email address, you just need to append the proper domain to your number. Building off of our email node, we used the first mediumArg to hold a phone number, and put the carrier into the second mediumArg.

public class ctNodeTextMessage : ctNode
{
    public ctNodeTextMessage() : base()
    {
        this.nodeType = "textmessage";

        //
        //SET UP SMTP CLIENT
        //
        this.mSmtpClient = new SmtpClient("gmail.com/mail", 25);
        this.mSmtpClient.Host = "smtp.gmail.com";
        this.mSmtpClient.Port = 25;
        this.mSmtpClient.EnableSsl = true;
        this.mSmtpClient.Credentials = new System.Net.NetworkCredential("GMAIL@gmail.com", "PASSWORD");

    }
    SmtpClient mSmtpClient;

    private string getEmailAddress(string phoneNumber, string provider)
    {
        switch (provider)
        {
            case "t-mobile":
                return phoneNumber + "@tmomail.net";
            case "virginmobile":
                return phoneNumber + "@vmobl.com";
            case "cingular":
                return phoneNumber + "@cingularme.com";
            case "att":
                return phoneNumber + "@cingularme.com";
            case "sprint":
                return phoneNumber + "@messaging.sprintpcs.com";
            case "verizon":
                return phoneNumber + "@vtext.com";
            case "nextel":
                return phoneNumber + "@messaging.nextel.com";
            default:
                //assume cingular/att is the most popular
                return phoneNumber + "@cingularme.com";
        }
    }

    protected override void sendSingleMessage(ctMessage ctm)
    {
        //send a single message
        string emailAddress = getEmailAddress(ctm.mediumArg1, ctm.mediumArg2);

        MailMessage msgMail = new MailMessage(new MailAddress(ctm.fromUser + "@chalktalk.net", ctm.fromUser), new MailAddress(emailAddress));
        msgMail.Subject = ctm.subject;
        msgMail.Body = ctm.message;
        sendEmail(msgMail);
    }

    private void sendEmail(MailMessage msgMail)
    {
        // Send the mail message
        this.mSmtpClient.Send(msgMail);
    }
}

Now to test this out, just like we sent the email we’ll send a text. Cool!

ctMessage ctm = new ctMessge("Friend", "Developer", "testing", "hello world via text", "textmessage", "#########", "verizon");
messageSender.sendMessage(ctm);

Conclusion:

When you’re working on a project with a small team, it’s especially important to build a good foundation like this so you can focus on easily added functionality without getting bogged down in complexity. This portion of the project was written over the course of a week and later on allowed us to focus almost exclusively on adding new services like Instant Messengers and interactive phone calling. Having functionality so quickly was crucial, along with a UI built by my brother, in getting the attention and support of others to build a business around this.

Next Steps:

Build a UI to manage content and run your messaging!
Rewrite your messageSender class to store messages in a database. This will make your app much more extensible, and you can save a record of the messages sent in an ‘outbox’.
Strongly type all textual identifiers in enumerations to avoid any frustrating mistakes.
Find an SDK for your favorite messenger, and build a node for it
Join our team and continue to build with us!

BlueBoss - Bluetooth Proximity Detection

Coding4Fun — Fri, 27 Jun 2008 01:09:42 GMT

Summary:

Bluetooth is now found in a variety of devices and enable the user to use wireless accessories. The Bluetooth protocol allows a user to “discover” any device that is in proximity to your Bluetooth radio. Why not see who is in proximity to you? Why not have the presence of a device execute programs or alert you?

Andy Konkol – http://copyandwaste.com

Hardware:

Bluetooth radio (USB dongle)
SMA Female Jack
SMA male to N-male pigtail
2.4 GHz antenna (with N-female connector)

Software:

Download:

Source / Binary Download

Bluetooth and Hardware:

Bluetooth was designed for devices to communicate wirelessly over short distances. However, with a very simple hardware modification you can extend the range of your Bluetooth radio with standard 2.4ghz antennas used in wireless networking (802.11 a/b/g).

Modifying Bluetooth dongles to accept external antennas is documented all over the Internet. In principle it is very easy: find the antenna lead and solder on a connector/antenna. I purchased a very cheap Bluetooth USB dongle on eBay and opened the casing. After finding the antenna trace on the circuit board I soldered on a SMA Female connector to it. After soldering the antenna jack in place I slipped a 3 inch chunk of heatshrink and heated it to cover the exposed circuit board. Now I had a Bluetooth radio that accepts external antennas. Adding an antenna simply increases the range of your radio, allowing you to “see” devices from a farther distance.

To connect an external antenna to the dongle I needed to use a connector converter called a pigtail. I used a SMA male to N-male pigtail. I connected one end of the pigtail to my dongle and the other to an omni-directional 9dbi panel antenna that had an N-female connector.

Software:

To take advantage of my newly modified hardware I needed to download the Coding4Fun Toolkit. Included in the toolkit is an API for Bluetooth devices. This API allows you to do a wide variety of things with your Bluetooth radio but I focused on two methods from the ServiceAndDeviceDiscovery library: DiscoverAllDevices and DiscoverDeviceByName.

DiscoverAllDevices allows you to “scan” the airwaves on the 2.4 GHz band and report back what devices your radio sees.

DiscoverDeviceByName allows you to scan for a particular device with a specified name and report back if it is present or not.

private bool DevicePresent()
{
    BluetoothDeviceServicesManager workerBTMgr = new BluetoothDeviceServicesManager();
    Device workerDevice = workerBTMgr.DiscoverDeviceByName(_watchItem.DeviceName);

    return (workerDevice != null);
}

public void Run(String Operation)
{
    switch (Operation)
    {
        case "SingleDevice":
            if (DevicePresent())
            {
                _parentForm.Invoke(_parentForm.AddToDeviceSeenList, new object[] { _watchItem });
            }
            else
            {
                _parentForm.Invoke(_parentForm.RemoveFromDeviceSeenList, new object[] { _watchItem });
            }
            break;
        case "AllDevices":
            BluetoothDeviceServicesManager workerBTMgr = new BluetoothDeviceServicesManager();
            List<Device> Devices = workerBTMgr.DiscoverAllDevices();
            _parentForm.Invoke(_parentForm.ThreadUpdateDiscoverBox, new object[] { Devices });
            break;
    }
}

Both of these methods require that the device you are scanning for is in discoverable mode (which most manufacturers enable by default). Using the two methods described above I was able to tell if a device is in proximity. And ultimately enabling me create alerts and execute programs based on what device is present.

To perform device discovery and not have my UI lag I had to create two worker threads. One worker thread to discover all devices and display it under my devices listbox, and another to discover devices by name specified in the “watchlist.” I am not an expert at multi-threaded programs but I managed to implement them without any major headaches.

User Interface:

Since the “Add to watchlist” and “Edit” buttons essentially do the same thing, I decided to overload a windows form. I also wanted to keep track of the parent form and disable it when the WatchItemForm was shown.

The second overload allows me to fill in the form control's text based on the data that is already set for the WatchItem that has been selected (the Edit button).

public WatchItemForm(Form1 f, String DeviceName)
{
    InitializeComponent();
    this._parentForm = f;
    lblDeviceName.Text = DeviceName;
}

public WatchItemForm(Form1 f, WatchItem item)
{
    InitializeComponent();
    this._parentForm = f;

    lblDeviceName.Text = item.DeviceName;
    tbxPicturePath.Text = item.ImagePath;
    tbxProgramPath.Text = item.ProgramPath;
    this._parentForm.Enabled = true;
}

I wanted to have a pop up notify window similar to outlook and was able to find Robert Misiak's NotifyWindow. This is a very simple library which allows you to create pop up notify windows very easily. I edited NotifyWindow to include a “picturepath” variable as well as picturebox on the form. As you can see creating a NotifyWindow is quite easy:

public void NotifyDeviceWindow(WatchItem x)
{
    NotifyWindow nw;
    nw = new NotifyWindow();
    //validate Alert Message
    if (x.AlertMessage == null)
    {
        nw.Text = x.DeviceName;
    }
    else
    {
        nw.Text = x.AlertMessage;
    }
    //validate picture
    if (x.ImagePath != null)
    {
        FileInfo imgfile = new FileInfo(x.ImagePath);
        if (imgfile.Exists)
        {
            nw.PicturePath = x.ImagePath;
        }
        else
        {
            MessageBox.Show("Image does not exist");
        }
    }
    nw.Notify();

    if (x.ProgramPath != null)
    {
        RunProcess(x.ProgramPath);
    }
}

Process Flow/Software Operation:

User clicks the “Discover” button, a thread is spawned which enumerates all Bluetooth devices in proximity
Thread finishes and updates the Devices listbox
User selects a discovered device and clicks “Add to watchlist” A watch item form is spawned and asks you for an alert message, a picture path, and an executable path
User clicks save , a WatchItem object is created and added to the watchList object
A timer starts and every 10 seconds a thread is spawned to discover that device by name
If the device is discovered, it is added to the “deviceSeenList” and a notify alert is sent and the executable is executed.
If that device is still present after the next timer click, no notification is sent, If that device is not present it is removed from the “deviceSeenList”

Screenshots:

A Better Startup Experience

Coding4Fun — Mon, 17 Mar 2008 18:55:47 GMT

	Does Windows take too long starting up before you can get to work? Wouldn't it better if things could startup at a lower priority? Learn how to launch processes, use performance counters, monitor files, and run tasks in the background.
Arian Kulp Arian's Blog Difficulty: Intermediate Time Required: 1-3 hours Cost: Free Software: Visual Basic or Visual C# Express Editions Hardware: None Download: C# Download VB Download

Introduction

Starting up Windows usually takes longer than I'd like it to. It seems like the system is churning away for ages. I've often thought that it would make more sense to wait as each item starts up before starting the next item. The problem is Windows has no idea how long an application takes to initialize itself. After launching it, it's just another running process. It would be nice to be able to configure a delay after each application so it can perform its potentially expensive startup before another application starts. I decided to put this idea into action.

This application requires Visual Studio 2005 Express Editions (C# or Visual Basic) or higher. This will be my last Coding 4 Fun article targeting Visual Studio 2005. If you haven't downloaded a Visual Studio 2008 Express Edition yet, definitely check them out. The upgrade is very much worth it!

Starting Up

The basic idea of the program is very simple: launch each startup item with a configurable delay between each one. Beyond a simple delay though, it might be good to see how active the system is. If the CPU is working hard, maybe it would be good to wait until it settles down before launching something else.

In case you've never looked closely, there are a few ways that Windows knows what to startup with the system. The three most common ways to start things are by using the Registry, the Startup folder, or by configuring services. The Registry and Startup folder methods are pretty similar. Of course Services are background processes that run even if a user isn't logged in.

Once a user logs in, the Registry and Startup folders take effect. The system Registry is a collection of keys, values, and data that applications (and Windows itself) use for configuration. One such use is to contain a list of programs to launch with Windows. There is a system-level and user-level list. System-level programs are started up for every user that logs in, while user-level programs are started only for the specific user.

The Startup folder works the same way. As part of each user's profile folder there is a Startup folder. There is also one at the Default User level. These folders contain shortcuts to applications. Whenever a user logs in, all of these shortcuts are launched. We just need to take over this process. To do this though, we'll need to take the shortcuts out of the system Startup folders.

The Basics

The Startup Optimizer works by scanning the user's Startup folder looking for shortcuts. As a new shortcut is found, a StartupEntry object is created. This object holds the filename, a display name and a few flags. The key flag is Managed. An object with Managed set to True is launched by the application and moved to a new ManagedStartup folder in the user's profile.

When a file or shortcut is detected in the Startup folder, a popup will occur to let a user decide if the program should manage it or not. If so, it moves the shortcut to its ManagedStartup folder. If not, it leaves it alone but sets the Managed flag to False. Next time it notices the same shortcut, it will just now to ignore it and let Windows handle it.

Figure 1: The dialog shown when a startup item is found

If you click the button to show the advanced options, you can specify a display name, the low CPU flag, and how to long to wait before launching the next application.

Figure 2: The dialog with advanced settings shown

Notice the icon. There's no included support for extracting the icon from a file, but you can use the Win32 SHGetFileInfo function in the shell32.dll library like so:

Visual Basic

<DllImport("shell32.dll")> _
Public Shared Function SHGetFileInfo(ByVal pszPath As String, ByVal dwFileAttributes As UInteger, ByRef psfi As SHFILEINFO, ByVal cbSizeFileInfo As UInteger, ByVal uFlags As UInteger) As IntPtr
End Function

Visual C#

[DllImport("shell32.dll")] 
public static extern IntPtr SHGetFileInfo(string pszPath, uint dwFileAttributes,
       ref SHFILEINFO psfi, uint cbSizeFileInfo, uint uFlags);

All StartupEntry objects are added to the StartupEntryList collection which is a subclass of List<StartupEntry>. Creating a subclass like this allows you to add helper methods for finding or removing objects or other useful functions. This collection is what is saved to disk to retain the properties of each item. The basic .NET binary serialization method is used due to its simplicity in code. Note that any class to be serialized must be decorated with the Serializable attribute.

Visual Basic

Public Shared Function FromDisk() As StartupEntryList
    If Not File.Exists("StartupEntryList.ser") Then
        Return New StartupEntryList()
    End If

    Dim c As StartupEntryList
    Dim s As Stream = File.Open("StartupEntryList.ser", FileMode.Open)
    Dim b As New BinaryFormatter()
    c = DirectCast(b.Deserialize(s), StartupEntryList)

    s.Close()

    Return c
End Function

Public Sub SaveToDisk()
    Dim s As Stream = File.Open("StartupEntryList.ser", FileMode.Create)
    Dim b As New BinaryFormatter()
    b.Serialize(s, Me)
    s.Close()
End Sub

Visual C#

public static StartupEntryList FromDisk() 
{ 
    if (!File.Exists("StartupEntryList.ser")) return new StartupEntryList(); 

    StartupEntryList c; 
    Stream s = File.Open("StartupEntryList.ser", FileMode.Open); 
    BinaryFormatter b = new BinaryFormatter(); 
    c = (StartupEntryList)b.Deserialize(s); 

    s.Close(); 

    return c; 
} 

public void SaveToDisk() 
{ 
    Stream s = File.Open("StartupEntryList.ser", FileMode.Create); 
    BinaryFormatter b = new BinaryFormatter(); 
    b.Serialize(s, this); 
    s.Close(); 
}

Notice how the FromDisk() method is static. This works as a factory method on the StartupEntryList class itself. Subclassing that simple generic list has made it easy to encapsulate all related functionality into the same place.

Working in the Background

Of course at some point the application needs to perform its startup magic. Obviously the main work is just launching each shortcut. This is done using the Process.Start() method in the System.Diagnostics namespace. If we were just launching the shortcuts one after another, it would be over quickly, but it would defeat the purpose of the program! With delays and waiting for the CPU to go idle, this startup process could potentially take a few minutes. This is important because it means that we can't just start the sequence in the Form_Load event handler on startup. The application would be unresponsive and there would be no way to abort.

Enter the BackgroundWorker class. I've used this in articles before and they make it really easy to run things in the background. It's much easier than creating threads -- especially if you need to update the user interface. You get to avoid the Invoke calls that are otherwise required and you even get Form Designer support.

Similar to the StartupEntryList, subclassing is a good idea in order to keep things nicely encapsulated. There's actually only one method that matters in this case: the event handler for the DoWork event. This is where work is done. You never call it directly (it's marked private) -- it's invoked when the RunWorkerAsync method is called. Anything that happens in the event handler is automatically on a thread other than the UI thread. It couldn't be simpler! In order to cause the UI to be updated (you can't ever directly reference it due to cross-threading concerns) call the ReportProgress method. Periodically check the CancellationPending flag to see if you need to exit.

The StartupBackgroundWorker_DoWork event handler method basically just iterates over the entries that have Managed set to true, waits for an idle CPU if necessary, and waits the specified delay time if set before moving to the next one. At several points it checks to see if a cancellation has been requested. The best thing though, is regardless of how long the sequence takes the UI will run smoothly.

Visual Basic

    Private Sub StartupBackgroundWorker_DoWork(ByVal sender As Object, ByVal e As DoWorkEventArgs)
        Dim entries As List(Of StartupEntry) = TryCast(e.Argument, List(Of StartupEntry))

        If entries Is Nothing OrElse entries.Count = 0 Then
            e.Cancel = True
            Throw New Exception("No entries passed in")
        End If

        Try
            ' Don't bother if there aren't any entries!
            If entries.Count > 0 Then
                Me.ReportProgress(0, "Startup Optimizer will begin in five seconds.  Click to cancel.")
                Dim i As Integer = 0
                While i < 5 AndAlso Not Me.CancellationPending
                    Thread.Sleep(1000)
                    i += 1
                End While

                If Me.CancellationPending Then
                    e.Cancel = True
                    Return
                End If
            End If

            systemIdleComponent1.Enabled = True

            ' Process entries to perform startup
            For Each entry As StartupEntry In entries
                If entry.Managed Then
                    If entry.WaitForLowCPU Then
                        Me.ReportProgress(0, "Waiting for idle CPU to launch: " + entry.DisplayName)

                        ' CPU wait routine...
                        ' TODO: Give up if we never go idle?  This would be the place..!
                        While Not systemIdleComponent1.WaitForIdle(1000)
                            If Me.CancellationPending Then
                                e.Cancel = True
                                Return
                            End If
                        End While
                    End If

                    Me.ReportProgress(0, "Starting: " + entry.DisplayName)

                    ' Don't actually start if we are debugging
                    If Not Debugger.IsAttached Then
                        Process.Start(Path.Combine(My.Settings.ManagedStartupPath, entry.FileName))
                    Else
                        'SIMULATE STARTUP DELAY
                        Thread.Sleep(2000)
                    End If

                    Me.ReportProgress(0, "Started: " + entry.DisplayName)

                    If entry.DelayTime > 0 Then
                        Me.ReportProgress(0, "Waiting: " + entry.DelayTime + " seconds until next item")
                        For x As Integer = 0 To entry.DelayTime - 1

                            ' Wait the number of seconds but check for cancel flag each second
                            If Me.CancellationPending Then
                                e.Cancel = True
                                Return
                            End If

                            Thread.Sleep(1000)
                        Next
                    End If
                End If
            Next
        Catch
            e.Cancel = True
        Finally
            systemIdleComponent1.Enabled = False
        End Try

    End Sub

Visual C#

private void StartupBackgroundWorker_DoWork(object sender, DoWorkEventArgs e)
{
    List<StartupEntry> entries = e.Argument as List<StartupEntry>;

    if (entries == null || entries.Count == 0 )
    {
        e.Cancel = true;
        throw new Exception("No entries passed in");
    }

    try
    {
        // Don't bother if there aren't any entries!
        if (entries.Count > 0)
        {
            this.ReportProgress(0, "Startup Optimizer will begin in five seconds.  Click to cancel.");
            for (int i = 0; i < 5 && !this.CancellationPending; i++)
                Thread.Sleep(1000);

            if (this.CancellationPending)
            {
                e.Cancel = true;
                return;
            }
        }

        systemIdleComponent1.Enabled = true;

        // Process entries to perform startup
        foreach (StartupEntry entry in entries)
        {
            if (entry.Managed)
            {
                if (entry.WaitForLowCPU)
                {
                    this.ReportProgress(0, "Waiting for idle CPU to launch: " + entry.DisplayName);

                    // CPU wait routine...
                    // TODO: Give up if we never go idle?  This would be the place..!
                    while( !systemIdleComponent1.WaitForIdle(1000) )
                    {
                        if (this.CancellationPending)
                        {
                            e.Cancel = true;
                            return;
                        }
                    }
                }

                this.ReportProgress(0, "Starting: " + entry.DisplayName);

                // Don't actually start if we are debugging
                if( !Debugger.IsAttached)
                    Process.Start(Path.Combine(Properties.Settings.Default.ManagedStartupPath, entry.FileName));
                else
                    Thread.Sleep(2000); //SIMULATE STARTUP DELAY

                this.ReportProgress(0, "Started: " + entry.DisplayName);

                if (entry.DelayTime > 0)
                {
                    this.ReportProgress(0, "Waiting: " + entry.DelayTime + " seconds until next item");

                    // Wait the number of seconds but check for cancel flag each second
                    for (int x = 0; x < entry.DelayTime; x++)
                    {
                        if (this.CancellationPending)
                        {
                            e.Cancel = true;
                            return;
                        }

                        Thread.Sleep(1000);
                    }
                }
            }
        }
    }
    catch
    {
        e.Cancel = true;
    }
    finally
    {
        systemIdleComponent1.Enabled = false;
    }

}

There are a few things to callout in this block. I have a few sanity checks in there to be sure that the list isn't NULL or empty. Defensive programming is always a good idea! Notice also that I have pauses built in with the Thread.Sleep() command. Where it would be convenient to pause for several seconds, it would render the thread unresponsive if a cancellation was requested. Note that cancellation is completely passive. The framework doesn't ever abort your BackgroundWorker. It's up to your code to catch it if cancellation is requested. So for pauses, I wait a second, check the flag, and repeat for the number of seconds. The code is slightly bulky but it works well.

Notice also how I don't launch the startup applications if System.Diagnostics.Debugger.IsAttached is true. When I'm troubleshooting/testing, I don't really want the applications launching every time! It's a simple check to see if the application is currently being debugged (as in Visual Studio).

Detecting Idleness

In addition to the simple time-based delays, I also wanted the option to wait for the system to be idle before launching applications. There's no direct way to see this though, so I created the SystemIdleComponent. This is completely modular and could be plugged into other applications easily. It all comes down to system Performance Counters. If you've never worked with these before, don't let them intimidate you. They're actually very easy to work with. From the Visual Studio Toolbox you can easily drag a counter and set its properties (category, counter,and instance), but unfortunately there's no support for events when the value changes. A pretty big deal I think!

My component builds on the PerformanceCounter object and creates a System.Threading.Timer object behind the scenes to monitor the state of the counter periodically. If a change is measured and it falls outside of the tolerance limits, it raises an event. It also raises an event when it returns to the tolerance. This allows you to receive an event both when the system becomes idle and when it returns to non-idle.

Visual Basic

    Private Sub timerCpu_Tick(ByVal state As Object)
        Dim currentValue As Integer = 100 - CInt(performanceCounterProcessorIdle.NextValue())

        ' If we are below the threshold, start counting...
        If currentValue <= _thresholdIdlePercent Then
            idleTimer.Start()
        Else
            idleTimer.[Stop]()
            idleTimer.Reset()
        End If


        ' See if we've been idle long enough
        If idleTimer.ElapsedMilliseconds / 1000 > _thresholdIdleTime Then
            ' We've just gone idle
            RaiseIdleEvent()
        Else
            ' We are not idle
            LowerIdleEvent()
        End If

        _lastCpuValue = CInt(currentValue)
    End Sub

Visual C#

private void timerCpu_Tick(object state)
{
    int currentValue = 100 - (int)performanceCounterProcessorIdle.NextValue();

    // If we are below the threshold, start counting...
    if (currentValue <= _thresholdIdlePercent)
        idleTimer.Start();
    else
    {
        idleTimer.Stop();
        idleTimer.Reset();
    };

    // See if we've been idle long enough
    if (idleTimer.ElapsedMilliseconds / 1000 > _thresholdIdleTime)
    {
        // We've just gone idle
        RaiseIdleEvent();
    }
    else
    {
        // We are not idle
        LowerIdleEvent();
    }

    _lastCpuValue = (int)currentValue;
}

What is idle? This is defined by properties ThresholdIdlePercent and ThresholdIdleTime. The statement is "the system is idle when it has been at {ThresholdIdlePercent}% for {ThresholdIdleTime} seconds." A consuming application just sets the properties and subscribes to events. Alternately, you can check the SystemIdle property when you need to. A final way is to call WaitForIdle with our without a timeout value. The call will not return until the system is idle.

This works by using an System.Threading.EventWaitHandle object. This very cool construct (system-based, not just .NET) lets two threads coordinate via a shared semaphore. The BackgroundWorker thread goes to sleep until the SystemIdleComponent's timer fires and detects an idle state. It can be dangerous to wait too long locked like this, so the worker will only call it for a second at a time in-between checking for a cancellation request. I've added additional attributes to this object to make it easier to reuse and for a good design-time experience. Drag it to your form and work with it like any other object.

Usage

It currently reads the user's Startup folder upon startup and shows the dialog to take action. There's no Cancel button since it wouldn't make sense. If you want to cancel, chances are you really just don't want the application to manage that shortcut. It won't know that next time unless it creates an entry for it though.

Something to think about is that some applications are going to check the Startup folder every time they launch and add their shortcut if it isn't there. Once that StartupEntry is in the StartupEntryList collection, the application will know what to do with it and you won't be prompted again.

A FileSystemWatcher object enables the application to see new shortcuts added. It then takes action only on shortcuts for which no StartupEntry is found. You can modify the display name, delay, wait-for-idle flag, or the managed property at any time. Unless you're debugging, you won't have any way to execute the launch sequence except when it's initially started with the "/startup" command line flag. If you launch it without the flag it won't launch anything so it's safer that way.

There's not much else to worry about. Tell it which startup entries to manage, then let it do it's thing upon restarts. It could really exit after the list is complete, except that it wouldn't see new entries that way.

Conclusion

The application ended up taking considerably longer than I ever imagined it would! I tried to create a good experience while demonstrating some good concepts. I was surprised at some of the subtleties I ran into to make this work as well as it does. It's not perfect by any means, but it's a good start and it should be useable as-is.

I tried to keep things out of MainForm where it made sense, though there is still room for more encapsulation. Individual classes should always be fairly light-weight. It's the way that they interact with each other that provides their power.

Next Steps

For this article, you can use Visual Studio 2005 Express, or make the upgrade to Visual Studio 2008 Express. As I mentioned at the beginning, I'll be upgrading to VS2008 for future articles, and with the Express products being free, there's no reason not to upgrade today at http://www.microsoft.com/express/.

I left a number of TODO comments in the code. These were cool things that I just didn't have time to implement. For one thing, it would be good to be able to just drag an application to the main window to add it to the Managed Startup list. Even more useful would be scanning the Registry Current User (HKCU) Run list. Probably more entries end up there than the Startup folder. I'd also like to extend my SystemIdleComponent to be a generalized PerformanceCounter event broker. That would make it easy to add code to wait for low disk I/O in addition to CPU load. Finally, I really wanted to add entry reordering to specify which applications should have the higher priority of starting first. Not difficult, so give it a try! If you end up adding any interesting features, let me know. I'd love to see where it goes!

Arian Kulp is an independent software developer and writer working in the Midwest. He has been coding since the fifth grade on various platforms, and also enjoys photography, nature, and spending time with his family. Arian can be reached through his web site at http://www.ariankulp.com.

Going Paperless

Coding4Fun — Tue, 25 Sep 2007 17:42:43 GMT

	Are you tired of battling piles of papers at home? From work, to your kid's school, to old bills and receipts, it can be too much to keep up with! In this article, learn about how to scan, crop, and set metadata for your documents.
Arian Kulp Arian's Blog Difficulty: Intermediate Time Required: 1-3 hours Cost: $50 and up (depending on hardware choice) Software: Visual Basic or Visual C# Express Editions, DSOFile: Developer Support OLE File Property Reader 2.1 Sample (KB 224351) Hardware: Any WIA-compliant document scanner Download: C# Download VB Download

Introduction

In my last article, I worked with GPS. I decided to try another device, so this time I'm working with an image scanner. For a long time, I've been wanting to try to go (more) paperless around the house. Too many piles of papers, and no way to really find them later when I need to. Scanning is the way to go, though it's time-consuming enough just feeding documents in, but then home scanners are rarely full-duplex (two-sided), and then the tools aren't so great.

The simple things that I wanted were: easy-scan, metadata, and auto-cropping of the images. More than that, I wanted standard image formats with standard metadata. Too many document scanning solutions use proprietary ways to get around limitations such as using database instead of files, or using sidecar files for metadata. This sample will create plain ol' image files with metadata. Use any application (such as Windows Desktop Search or Picasa) to manage and search for documents.

I've included source code for Visual Basic and C#. Both versions are identical. You'll need to download the appropriate version of Visual Studio 2005 Express Edition to open the source code, and you will need to download the DSOFile MSDN sample referenced in the article header. The dsofile.dll must be registered before the project will startup. Presumably the application will work on any supported operating system for DSOFile (2000/XP/Vista).

A User Interface You Can Live With

User interfaces are always challenging. You want to capture all of your functionality, yet make everything accessible without being overwhelming or confusing. One design goal of mine is to always create windows that will resize well. This interface consists of two splitters. A vertical splitter separates the commands and options on the left from the properties and image on the right. A horizontal splitter then separates the properties from the image region.

Image 1: The user interface

The Scan New Document button initiates the scan, using standard Windows scanning dialogs. Once the image is transferred to the application, it appears in the Source tab. You can crop away any borders automatically by clicking Crop. It will look for the color in Crop Color, based on the specified Threshold. You can click on the image to choose the crop color, or use the value that it auto-selects from the bottom of the image. Use the Properties region to enter metadata. The From field becomes the Author field in metadata, and Type becomes Subject. The rest are direct mappings. Finally, select the image format (codec), destination folder, and compression level and click Save. Not that not all formats can hold metadata (such as BMP).

Talking to the Scanner

Working with scanners with .NET isn't as smooth as it could be, but the COM-interop works well enough. It would be nice to be able to use Image.FromScanner, but it's not an option!

The first step is to create a reference to Microsoft Windows Image Acquisition 1.01 Type Library. This creates wrappers in the WiaLib namespace. Then, you need to create a WiaClass instance. With that object, you can enumerate the scanners using the Devices property, or create an instance of a particular scanner. If you call the Create method without a scanner DeviceInfoClass object and there are more than one scanner attached, the standard "Select Device" dialog is shown.

Image 2: The Select Device dialog

Once this returns, you have a ItemClass object. You might think that this would allow you to easily determine the selected scanner, but in fact, none of the properties are definitive. The best option if you wanted to retain the choice of scanner would be to present your own "Select Device" dialog from the DeviceInfoClass collection, the remember the selection.

Now you can invoke the GetItemsFromUI method. This isn't required for unattended scanning, but if you want to present the scanner dialog (to choose Color, Greyscale, etc), this is a good choice. From there, enumerate the scans (plural if multiple pages were scanned) and call Transfer on each one to save them to file. I originally used Image.FromFile to load from that file, but it turns out there's a bug that leaves files open when you do that. The simple solution was to create a FileStream, call Image.FromStream, then close the stream. This allowed me to delete the temporary file afterwards. I should note, that for some strange reason, I had to wrap the Image.FromStream call with creating a new Bitmap. This should not be necessary, but if I don't, I get an unexplained OutOfMemoryException later when I convert it to black-and-white. I hate kludges!

Visual Basic

Public Function ScanDocument() As List(Of Bitmap)
    Dim docs As New List(Of Bitmap)()
    Dim currFilename As String

    ' Create a scanner instance (the user can select if more than one)
    Dim scanner As ItemClass = DirectCast(wiaManager.Create(missing), ItemClass)

    ' Show the standard scanning dialog (this is not a required step...)
    Dim scans As CollectionClass = TryCast( _
        scanner.GetItemsFromUI(WiaFlag.SingleImage, WiaIntent.ImageTypeText), _
        CollectionClass)

    ' If the user clicks Cancel, collection is Nothing
    If scans IsNot Nothing AndAlso scans.Count > 0 Then
        ' Transfer any scanned pictures to disk
        Dim scan As ItemClass
        For Each wiaObj As Object In scans
            scan = DirectCast( _
                Marshal.CreateWrapperOfType(wiaObj, GetType(ItemClass)), _ 
                ItemClass)

            ' create temporary file for image
            currFilename = Path.GetTempFileName()

            ' transfer picture to our temporary file
            scan.Transfer(currFilename, False)

            ' Create a Bitmap from the loaded file (Image/Bitmap.FromFile locks the file...)
            Using fs As New FileStream( _
                currFilename, FileMode.Open, FileAccess.Read)

                docs.Add(New Bitmap(Bitmap.FromStream(fs)))
                fs.Close()

            End Using

            ' Don't leave junk behind!
            File.Delete(currFilename)
        Next
    End If

    Return docs
End Function

Visual C#

public List<Bitmap> ScanDocument()
{
    List<Bitmap> docs = new List<Bitmap>();
    string currFilename;
    
    // Create a scanner instance (the user can select if more than one)
    ItemClass scanner = (ItemClass)wiaManager.Create(ref missing);

    // Show the standard scanning dialog (this is not a required step...)
    CollectionClass scans = scanner.GetItemsFromUI(
        WiaFlag.SingleImage, WiaIntent.ImageTypeText)
        as CollectionClass;

    // If the user clicks Cancel, collection is NULL
    if (scans != null && scans.Count > 0)
    {
        // Transfer any scanned pictures to disk
        ItemClass scan;
        foreach (object wiaObj in scans)
        {
            scan = (ItemClass)Marshal.CreateWrapperOfType(wiaObj, typeof(ItemClass));

            // create temporary file for image
            currFilename = Path.GetTempFileName();

            // transfer picture to our temporary file
            scan.Transfer(currFilename, false);

            // Create a Bitmap from the loaded file (Image/Bitmap.FromFile locks the file...)
            using (FileStream fs = new FileStream(currFilename, FileMode.Open, FileAccess.Read))
            {

                docs.Add(new Bitmap(Bitmap.FromStream(fs)));
                fs.Close();
            } 
            // Don't leave junk behind!
            File.Delete(currFilename);
        }
    }

    return docs;
}

Once the new image is scanned, it's displayed in the Source tab in the user interface.

Image 3: Displaying a scanned image

Cropping Your Way to Success

The standard scanning dialog lets you crop an image using the handles, but only in preview mode (you need to scan it a second time after selecting the crop region). I own two scanners. One is a standard flatbed, but the other is a compact travel scanner that pulls the sheet through (the Ambir TravelScan 600). The TravelScan doesn't work so well in that mode since scanning a second time will always be slightly different due to the feed mechanism. I'd love to know why I can't just crop final my image in the scanner dialog, but, oh well!

My solution was to add cropping to the application after it's scanned. It takes longer to do a low-quality preview along with a full-quality scan on a full sheet of paper than just doing one full-quality scan. Since my primary design goal was to be able to scan and catalog sheets of paper (not business cards, photos, etc), this made sense.

Once the image is scanned, it automatically grabs a pixel from the bottom row. It assumes that this is an unimportant edge. You can choose a different edge color by clicking in the picture. Then, use the LockBits method of the Bitmap object to get access to the raw bits. These bits are then cycled through row-by-row to the bottom. Each pixel is compared to the crop color based on the supplied threshold. Border matches are compared to the known top/left/right/bottom border locations and moved as necessary. If a crop doesn't come out right, you can just change the threshold value and try again.

Think of it as starting on the four edges with straight-edges. Drag those straight-edges toward the middle until you encounter a color that's more than the defined threshold different from the specified "border color." Note that this won't work so well for you if your scanner adds a little band around the edges of the images. One of my scanners is a little bit extra bright around the edges. If the border is overall black, that throws it off. I found that just dragging the crop region slightly in the scanning dialog helped. If it's not a full sheet document, you won't lose anything. It's a fairly simple and brute force way of cropping. A real imaging application would have some super-slick way to do it in a millisecond or two with more accuracy I'm sure!

Visual Basic

For y As Integer = 0 To img.Image.Height - 1

    'loop through pixels on Y axis until end of image height
    For x As Integer = 0 To img.Image.Width - 1
        'loop through pixels on X axis until end of image width
        ' Scans won't have perfect background... (only need one channel if b&w)
        If Math.Abs(img.RawBits(bufferLoc + 0) - cropColor.B) > threshold Then
            'Determine if pixel is further left than the value we already have
            If leftEdge = -1 OrElse x < leftEdge Then
                leftEdge = x
            End If

            'Determine if pixel is further to the top than the value we already have
            If topEdge = -1 Then
                topEdge = y
            End If

            'Determine if pixel is further right than the value we already have
            If (rightEdge = -1) OrElse x > rightEdge Then
                rightEdge = x
            End If

            'Determine if pixel is further to the bottom than the value we already have
            If (bottomEdge = -1) OrElse y > bottomEdge Then
                bottomEdge = y
            End If
        End If

        ' LEARNED: Could be 32-bit, 24-bit, 16-bit, etc.
        bufferLoc += img.PixelWidth
    Next

    ' LEARNED: Extra byte(s) per line for 4-byte boundary...
    bufferLoc += img.RowPadding
Next

Visual C#

//loop through pixels on Y axis until end of image height
for (int y = 0; y < img.Image.Height; y++)
{
    //loop through pixels on X axis until end of image width
    for (int x = 0; x < img.Image.Width; x++)
    {
        // Scans won't have perfect background... (only need one channel if b&w)
        if (Math.Abs(img.RawBits[bufferLoc + 0] - cropColor.B) > threshold)
        {
            //Determine if pixel is further left than the value we already have
            if (leftEdge == -1 || x < leftEdge) leftEdge = x;

            //Determine if pixel is further to the top than the value we already have
            if (topEdge == -1) topEdge = y;

            //Determine if pixel is further right than the value we already have
            if ((rightEdge == -1) || x > rightEdge) rightEdge = x;

            //Determine if pixel is further to the bottom than the value we already have
            if ((bottomEdge == -1) || y > bottomEdge)
            {
                bottomEdge = y;
            }
        }

        // LEARNED: Could be 32-bit, 24-bit, 16-bit, etc.
        bufferLoc += img.PixelWidth;
    }

    // LEARNED: Extra byte(s) per line for 4-byte boundary...
    bufferLoc += img.RowPadding;
}

Image 4 : The same image, auto-cropped (threshold=82)

I learned a few things in all of this. Bitmaps have many ways that they can be stored. Pixels can be anywhere from 1-bit up to 12-bit, with and without an additional alpha component (for transparency). This makes it impossible to just copy the bitmap to a byte array and just look at each byte as a pixel. To make it worse, in some pixel formats, the RGB order may not be the same, and some index the colors rather than using RGB at all. Phew!

Even once you know the pixel width, you can't assume that [pixel width * width] is equal to size of a row. This is due to the fact that bytes are packed for optimum efficiency based on maintaining a 4-byte boundary. In other words, the actual width of bytes in a row will always be divisible by four. The actual width of bytes is called the "stride."

You can obtain all of the numbers when you grab the bitmap's bits, but it still complicates things when you cycle through the pixels. My solution (*ahem* cheat) was to convert the image to a fixed 32-bit RGB structure (no Alpha component). That way I always knew the pixel width and row padding.

I did two more things to simplify my routine. Before grabbing the bits, I converted the image to black-and-white and shrunk to 1/4th its size. This gave me significantly fewer bytes to compare, and being black-and-white, I didn't need to compare all three channels for detecting the border. In order to perform the black-and-white conversion, I used a ColorMatrix object to transform the color values. I used code from this blog entry to figure out the values to use.

Now you might be wondering why I didn't go with a simple 8-bit greyscale image format. The bottom line is I'm probably not smart enough! The 8-bit formats were indexed (you'd expect a simple intensity value for each byte...), and if you try to grab the Graphics object for drawing a cropped image, you get a GDI+ exception every time. Maybe with more effort I could have figured it out (and maybe I still will!), but it works well enough for now. My speed tests from cropping the original versus the shrunken black-and-white are pretty conclusive so I stuck with it.

Will Someone Save Me

With the image scanned and (optionally) cropped, the final step is to key in the metadata and save the file. I've been searching for a way to work with metadata from .NET for too long. The Image class has methods (Get/SetPropertyItem) for dealing with metadata properties, but they are mostly suited for reading the fields, and if you use them on an existing file you end up re-encoding the bitmap (recompressing...).

The best solution turned out to be the Microsoft DSO OLE Document Properties Reader 2.1 (often referred to as simply DSOFile). This wraps the IPropertyStrorage COM class which is typically used for reading properties in OLE-based Office documents, and also adds the ability to read from the new XML-based Office formats, and many other files. Using this sample object, you can access the Title, Subject, Author, Category, Keywords, and Comments field that you see in the Summary tab of all files in Windows. This does vary a bit depending on file type, but it's very easy to use.

Once a scan has taken place, the user can choose to crop it. When Save is clicked, the method saves the file (choosing the cropped version, if present). This happens by setting the compression level and codec, and calling Save. The drop-down box for choosing codec is actually populated by the System.Imaging.ImageCodecInfo collection.

Once the file is saved, the metadata can be set. It's possible to use the built-in Image methods to do this prior to saving, but the DSOFile code is just so convenient for working with metadata. Data need not be converted to byte arrays, and fields are set using standard properties, not numeric ID's.

Visual Basic

' Grab file info if it exists
Dim fi As New FileInfo(filename)
If Not fi.Exists Then
    Return False
End If

' Update the file creation date based on the supplied date
If creationDate.HasValue Then
    fi.CreationTime = creationDate.Value
End If

' Create and open the properties object
oleDocument = New OleDocumentPropertiesClass()
oleDocument.Open(fi.FullName, False, dsoFileOpenOptions.dsoOptionDefault)

If Not oleDocument.IsReadOnly Then
    ' Keywords should be semicolon-separated, not carriage returns or commas
    Dim keywordsSeparated As String = keywords.Replace(Chr(10), ";"c).Replace(","c, ";"c)

    oleDocument.SummaryProperties.Author = docSource
    oleDocument.SummaryProperties.Comments = comments
    oleDocument.SummaryProperties.Keywords = keywordsSeparated
    oleDocument.SummaryProperties.Subject = docType
    oleDocument.SummaryProperties.Title = title

    If oleDocument.IsDirty Then
        oleDocument.Save()
    End If

    Return True
End If

Visual C#

// Grab file info if it exists
FileInfo fi = new FileInfo(filename);
if (!fi.Exists) return false;

// Update the file creation date based on the supplied date
if (creationDate.HasValue) fi.CreationTime = creationDate.Value;

// Create and open the properties object
oleDocument = new OleDocumentPropertiesClass();
oleDocument.Open(fi.FullName, false, dsoFileOpenOptions.dsoOptionDefault);

if (!oleDocument.IsReadOnly)
{
    // Keywords should be semicolon-separated, not carriage returns or commas
    string keywordsSeparated = keywords.Replace('\n', ';').Replace(',', ';');

    oleDocument.SummaryProperties.Author = docSource;
    oleDocument.SummaryProperties.Comments = comments;
    oleDocument.SummaryProperties.Keywords = keywordsSeparated;
    oleDocument.SummaryProperties.Subject = docType;
    oleDocument.SummaryProperties.Title = title;

    if (oleDocument.IsDirty) oleDocument.Save();

    return true;
}

Both reading and writing properties is easy, though keep in mind that only JPEG and TIFF support properties well (no warnings or errors will occur with other containers/formats).

Image 5: Showing the saved metadata

The Received date picker doesn't actually update metadata. It works using the FileInfo object, updating the CreationTime property which directly updates the file. This is only done if the date field's checkbox is checked.

Next Steps

There are so many things to add to this start! Faster cropping would be a start... I also had wanted to add deskewing (straightening), but I quickly realized that I wouldn't be able to do that feature justice. With enough time maybe!

The UI itself could use some better design, multi-part documents would be good (for TIFF or GIF formats). I had also planned on integrating Windows contacts with the From ComboBox, but I didn't get to it. Image rotation can be useful and isn't terribly difficult.

Once you get into the document imaging world, there are so many possibilities and expectations. I'm afraid that this just scratches the surface, but I'm pleased with it as a starting point. If anyone's interested in taking it further, let me know!

Conclusion

In this article, we've learned more about scanning image manipulation, and working with file metadata. The application is useable, but definitely not commercial-grade! For any comments, questions, or suggestions, contact me through my blog. Happy scanning!

Outlook Webmail Add-in for Windows Home Server

Coding4Fun — Fri, 10 Aug 2007 14:33:56 GMT

In this article, Brian Peek will demonstrate how to create an add-in for Windows Home Server that will allow users to view their Outlook mail from a web browser.

Brian Peek

ASPSOFT, Inc.

Difficulty: Intermediate

Time Required: 2-3 hours

Cost: Free

Software: Windows Home Server, Microsoft Outlook 2000/XP/2003/2007 (not Outlook Express/Windows Mail), Visual Basic or Visual C# Express Editions, Visual Web Developer Express Edition, Microsoft .NET Framework 3.0 runtime, Outlook/Office Primary Interop Assemblies (more on this below), Windows SDK (Vista or later, which includes the .NET 3.0 bits. Note that this installs and works just fine under Windows XP. The SDK can build applications for Windows XP and greater.)

Hardware: None

Download: CodePlex Project

Introduction

Windows Home Server is a new product from Microsoft which allows home users to manage and share data, including photos, documents, videos, music, etc. It also provides a very easy way to backup all computers on your home network to a central storage server.

Windows Home Server can also be extended via add-ins to enhance the experience and provide new and interesting functionality other than what comes in the box.

One feature not present in WHS that I would find useful is the ability to view my Outlook mail box from the web at any time. I have 6 or 7 email accounts that are all setup to retrieve via POP3 to Outlook. Most of these accounts do not support IMAP or have a web-based interface. Therefore, Outlook is generally open all day and checking messages. When I'm away from home for work or pleasure, it's very often inconvenient to have to remote desktop into the machine with Outlook running to read my email, so it would be nice to have a web-based version of my current Outlook folders so I can view all email (old and new) at any time simply by browsing to a web server at home. Windows Home Server comes with Internet Information Services 6 (IIS6) and one can easily add a new web application to IIS on the server.

So, this article will attempt to show how to build a new web site using ASP.NET that can be added to your Windows Home Server installation that will allow one to view the Outlook folders running on whatever computer contains your current Outlook installation and message store.

If you wish to just use the application, download the sample from above and skip down to the deployment section for installation instructions.

NOTE: This application will only work with Microsoft Outlook. It will not work with Outlook Express, Windows Mail, or any other mail client.

Setup

Setup can be a bit tricky. Office/Outlook will need to be installed on your development machine. It does not need to be the same machine which contains your store at this point, but that too would help. Once Office/Outlook is installed, the Primary Interop Assemblies for the version of Office you are using need to be installed. For Office 2003/2007, this can be done choosing .NET Programming Support from the list of sub-items in the Microsoft Office Outlook section of the setup program.

Unfortunately I do not have an earlier copy of Office with which to check, but the procedure should be the same. If anyone happens to try this with Office XP/2000, please let me know if/how it works.

If you will be developing on an OS earlier than Vista, install the .NET Framework 3.0 runtime.

Finally, install the Windows SDK linked above accepting all defaults.

Architecture

The architecture we will be using is very similar that to an N-tier application. The machine running Outlook with the message store to be viewed is, in essence, the server machine. That machine will run a host process that we will develop which will expose several methods via Windows Communication Foundation. These methods will be consumed by an ASP.NET application running on the Windows Home Server.

The Host

Let's start by building the host application. This will run on the computer where Outlook is installed and the messages are stored. The application will be written to run in the notification area next to the Windows system clock.

To start, create a new Windows Application project named WHSMailHost. Rename the default Form1.cs/.vb file to frmMain.cs/.vb. Double-click on the file in the Solution Explorer to bring up the design surface.

In order to get the application to run in the notification area, drag and drop a NotifyIcon control from the Toolbox to the design surface, name it niIcon. Also, drag over a ContextMenuStrip to the design surface and name it cmsMenu. This will be used to pop up a context menu when the icon in the notification area is clicked. Finally, set the following properties on the niIcon control:

Text	WHS Mail Host
ContextMenuStrip	cmsMenu
Visible	True

Select the cmsMenu control and add a single menu item named Exit to the list. Double-click on that menu item to create a default Click event. In the code for the Click event, simply close the form as follows:

private void mnuExit_Click(object sender, EventArgs e)
{
    // exit the application
    this.Close();
}

Private Sub mnuExit_Click(ByVal sender As Object, ByVal e As EventArgs) Handles mnuExit.Click
    ' exit the application
    Me.Close()
End Sub

Finally, add the following events to frmMain by selecting them from the Event Property window and implementing them with the following code:

private void frmMain_Resize(object sender, EventArgs e)
{
    // hide the form
    this.Hide();
}

private void frmMain_Load(object sender, EventArgs e)
{
    // start the WCF service
    MyServiceHost.StartService();
}

private void frmMain_FormClosing(object sender, FormClosingEventArgs e)
{
    // stop the WCF service
    MyServiceHost.StopService();
}

Private Sub frmMain_Resize(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Resize
    ' hide the form
    Me.Hide()
End Sub

Private Sub frmMain_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load
    ' start the WCF service
    MyServiceHost.StartService()
End Sub

Private Sub frmMain_FormClosing(ByVal sender As Object, ByVal e As FormClosingEventArgs) Handles MyBase.FormClosing
    ' stop the WCF service
    MyServiceHost.StopService()
End Sub

The code above references a class named MyServiceHost. This is what starts the WCF host and will be discussed next.

Windows Communication Foundation (WCF)

Windows Communication Foundation (formerly known as Indigo) is a feature of the .NET Framework 3.0 that allows one to build and run connected systems. The simplest definition that fits with what we will be doing here is that it allows an application running on one machine (the client, in this case, the ASP.NET application) to execute a method on another machine (the host, in this case, the application we're currently building).

First, add a reference to the System.ServiceModel assembly. Then, add a class to the project named WHSMailService. Open the class and add the following code beneath the generated WHSMailService class implementation:

internal class MyServiceHost
{
    internal static ServiceHost myServiceHost = null;

    internal static void StartService()
    {
        // Instantiate new ServiceHost 
        myServiceHost = new ServiceHost(typeof(WHSMailService));
        myServiceHost.Open();
    }

    internal static void StopService()
    {
        // Call StopService from your shutdown logic (i.e. dispose method)
        if (myServiceHost.State != CommunicationState.Closed)
            myServiceHost.Close();
    }
}

Friend Class MyServiceHost
    Friend Shared myServiceHost As ServiceHost = Nothing

    Friend Shared Sub StartService()
        ' Instantiate new ServiceHost 
        myServiceHost = New ServiceHost(GetType(WHSMailService))
        myServiceHost.Open()
    End Sub

    Friend Shared Sub StopService()
        ' Call StopService from your shutdown logic (i.e. dispose method)
        If myServiceHost.State <> CommunicationState.Closed Then
            myServiceHost.Close()
        End If
    End Sub
End Class

This code simply creates a new WCF ServiceHost of the type WHSMailService (which we will implement next) and then opens that host so that it may receive incoming connections. We will look at how this connections are configured later in the article.

Remember that the code in the form above above called the StartService and StopService methods located here when the main form loads and closes. This very easily allows to immediately start the service host when the application starts and closes the service host when the application exits.

Contracts and Entities

A contract is an interface that defines which methods are exposed by the service host that can be consumed by the client application. Both the client application and the server application will need to know what is in this interface, so we will need to create a second project that will contain the interface definition. Additionally, we will need a way to pass folder and email information to and from each application, so we will define some custom classes to encapsulate those objects.

Create a new Class Library project in the current solution named WHSMailCommon. In this new project, create a directory named Contracts and a directory named Entities.

Inside the Entities directory, create a new class named Folder. This will represent an Outlook message folder. The class should look like the following:

using System;
using System.Collections.Generic;

namespace WHSMailCommon.Entities
{
    // entity object representing an Folder
    [Serializable]
    public class Folder : IComparable
    {
        private string _entryID;
        private string _name;
        private List<Folder> _folders;
        private int _unreadMessages;
        private int _totalMessages;

        public Folder(string entryID, string name, int unreadMessages, int totalMessages)
        {
            _entryID = entryID;
            _name = name;
            _unreadMessages = unreadMessages;
            _totalMessages = totalMessages;
        }

        // MAPI unique identifier
        public string EntryID
        {
            get { return _entryID; }
            set { _entryID = value; }
        }

        // subfolders of this folder
        public List<Folder> Folders
        {
            get { return _folders; }
            set { _folders = value; }
        }

        public string Name
        {
            get { return _name; }
            set { _name = value; }
        }

        public int UnreadMessages
        {
            get { return this._unreadMessages; }
            set { this._unreadMessages = value; }
        }

        public int TotalMessages
        {
            get { return this._totalMessages; }
            set { this._totalMessages = value; }
        }

        // used so we can sort the folders alphabetically later on
        public int CompareTo(object obj)
        {
            return string.Compare(this.Name, ((Folder)obj).Name);
        }
    }
}

Imports Microsoft.VisualBasic
Imports System
Imports System.Collections.Generic

Namespace WHSMailCommon.Entities
    ' entity object representing an Folder
    <Serializable> _
    Public Class Folder
        Implements IComparable
        Private _entryID As String
        Private _name As String
        Private _folders As List(Of Folder)
        Private _unreadMessages As Integer
        Private _totalMessages As Integer

        Public Sub New(ByVal entryID As String, ByVal name As String, ByVal unreadMessages As Integer, ByVal totalMessages As Integer)
            _entryID = entryID
            _name = name
            _unreadMessages = unreadMessages
            _totalMessages = totalMessages
        End Sub

        ' MAPI unique identifier
        Public Property EntryID() As String
            Get
                Return _entryID
            End Get
            Set(ByVal value As String)
                _entryID = value
            End Set
        End Property

        ' subfolders of this folder
        Public Property Folders() As List(Of Folder)
            Get
                Return _folders
            End Get
            Set(ByVal value As List(Of Folder))
                _folders = value
            End Set
        End Property

        Public Property Name() As String
            Get
                Return _name
            End Get
            Set(ByVal value As String)
                _name = value
            End Set
        End Property

        Public Property UnreadMessages() As Integer
            Get
                Return Me._unreadMessages
            End Get
            Set(ByVal value As Integer)
                Me._unreadMessages = value
            End Set
        End Property

        Public Property TotalMessages() As Integer
            Get
                Return Me._totalMessages
            End Get
            Set(ByVal value As Integer)
                Me._totalMessages = value
            End Set
        End Property

        ' used so we can sort the folders alphabetically later on
        Public Function CompareTo(ByVal obj As Object) As Integer Implements IComparable.CompareTo
            Return String.Compare(Me.Name, (CType(obj, Folder)).Name)
        End Function
    End Class
End Namespace

This class defines several properties to describe the folder (EntryID, Name, etc.) and additionally implements the IComparable interface's CompareTo method so that we can easily sort the folders alphabetically later on.

Next, create a class named Email. The code for this class looks like the following:

using System;
using System.Collections.Generic;
using System.Text;

namespace WHSMailCommon.Entities
{
    // entity object representing an Email
    [Serializable]
    public class Email
    {
        private string _entryID;
        private string _from;
        private string _fromName;
        private string _subject;
        private DateTime _received;
        private int _size;
        private string _body;

        public Email(string entryID, string from, string fromName, string subject, DateTime received, int size)
        {
            _entryID = entryID;
            _from = from;
            _fromName = fromName;
            _subject = string.IsNullOrEmpty(subject) ? "(no subject)" : subject;
            _received = received;
            _size = size;
        }

        public Email(string entryID, string from, string fromName, string subject, DateTime received, int size, string body) :
            this(entryID, from, fromName, subject, received, size)
        {
            _body = body;
        }

        // MAPI unique ID
        public string EntryID
        {
            get { return _entryID; }
            set { _entryID = value; }
        }

        // email address of sender
        public string From
        {
            get { return _from; }
            set { _from = value; }
        }

        // name of sender
        public string FromName
        {
            get { return _fromName; }
            set { _fromName = value; }
        }

        public string Subject
        {
            get { return _subject; }
            set { _subject = value; }
        }

        public string Body
        {
            get { return _body; }
            set { _body = value; }
        }

        public DateTime Received
        {
            get { return _received; }
            set { _received = value; }
        }

        public int Size
        {
            get { return _size; }
            set { _size = value; }
        }
    }
}

Imports Microsoft.VisualBasic
Imports System
Imports System.Collections.Generic
Imports System.Text

Namespace WHSMailCommon.Entities
    ' entity object representing an Email
    <Serializable> _
    Public Class Email
        Private _entryID As String
        Private _from As String
        Private _fromName As String
        Private _subject As String
        Private _received As DateTime
        Private _size As Integer
        Private _body As String

        Public Sub New(ByVal entryID As String, ByVal From As String, ByVal fromName As String, ByVal subject As String, ByVal received As DateTime, ByVal size As Integer)
            _entryID = entryID
            _from = From
            _fromName = fromName
            If String.IsNullOrEmpty(subject) Then
                _subject = "(no subject)"
            Else
                _subject = subject
            End If
            _received = received
            _size = size
        End Sub

        Public Sub New(ByVal entryID As String, ByVal From As String, ByVal fromName As String, ByVal subject As String, ByVal received As DateTime, ByVal size As Integer, ByVal body As String)
            Me.New(entryID, From, fromName, subject, received, size)
            _body = body
        End Sub

        ' MAPI unique ID
        Public Property EntryID() As String
            Get
                Return _entryID
            End Get
            Set(ByVal value As String)
                _entryID = value
            End Set
        End Property

        ' email address of sender
        Public Property From() As String
            Get
                Return _from
            End Get
            Set(ByVal value As String)
                _from = value
            End Set
        End Property

        ' name of sender
        Public Property FromName() As String
            Get
                Return _fromName
            End Get
            Set(ByVal value As String)
                _fromName = value
            End Set
        End Property

        Public Property Subject() As String
            Get
                Return _subject
            End Get
            Set(ByVal value As String)
                _subject = value
            End Set
        End Property

        Public Property Body() As String
            Get
                Return _body
            End Get
            Set(ByVal value As String)
                _body = value
            End Set
        End Property

        Public Property Received() As DateTime
            Get
                Return _received
            End Get
            Set(ByVal value As DateTime)
                _received = value
            End Set
        End Property

        Public Property Size() As Integer
            Get
                Return _size
            End Get
            Set(ByVal value As Integer)
                _size = value
            End Set
        End Property
    End Class
End Namespace

This class simply contains properties to describe an email message.

You will note that both of these classes have the [Serializable] attribute attached to them. When objects are passed through WCF, they are serialized at the source and deserialized at the destination. By marking the objects with the [Serializable] attribute, the .NET CLR can do this for us automatically since we are not using any complex data types in our entities.

With our entities out of the way, we can define our contract. Inside the Contracts directory, create a new Interface file named IWHSMailService.

This interface/contract will define three methods: one method to return a tree of objects which represent the folder tree in Outlook (GetFolders), one method to return a list of messages inside that folder (GetMessages), and one method to return the contents of a specific message (GetMessages). The interface will look like the following:

using System.Collections.Generic;
using System.ServiceModel;
using WHSMailCommon.Entities;

namespace WHSMailCommon.Contracts
{
    // list of methods of the WHSMailService service
    [ServiceContract()]
    public interface IWHSMailService
    {
        [OperationContract]
        List<Folder> GetFolders();

        [OperationContract]
        List<Email> GetMessages(string entryID, int numPerPage, int pageNum);

        [OperationContract]
        Email GetMessage(string entryID);
    }
}

Imports Microsoft.VisualBasic
Imports System.Collections.Generic
Imports System.ServiceModel
Imports WHSMailCommon.Entities

Namespace WHSMailCommon.Contracts
    ' list of methods of the WHSMailService service
    <ServiceContract()> _
    Public Interface IWHSMailService
        <OperationContract> _
        Function GetFolders() As List(Of Folder)

        <OperationContract> _
        Function GetMessages(ByVal entryID As String, ByVal numPerPage As Integer, ByVal pageNum As Integer) As List(Of Email)

        <OperationContract> _
        Function GetMessage(ByVal entryID As String) As Email
    End Interface
End Namespace

As with the entities, this interface is also decorated with several attributes. First, any WCF contract interface must be tagged with the [ServiceContract()] attribute to define it as a contract to WCF. Additionally, all methods which will be exposed for consumption by a client must be marked with the [OperationContract] attribute.

The implementation and description of these methods will come later when we write the contract implementation.

Configuration

The final thing to setup on the WCF server is the configuration file. The service can very easily be configured using an application configuration file. Add an Application Configuration file to the project named App.config. Set the contents of the file to the following:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.serviceModel>
        <bindings>
            <netTcpBinding>
                <binding name="NewBinding0">
                    <security mode="None" />
                </binding>
            </netTcpBinding>
        </bindings>
        <services>
            <service name="WHSMailHost.WHSMailService">
                <endpoint address="net.tcp://localhost:12345/IWHSMailService"
                    binding="netTcpBinding" bindingConfiguration="NewBinding0"
                    contract="WHSMailCommon.Contracts.IWHSMailService" />
            </service>
        </services>
    </system.serviceModel>
</configuration>

The <services> section defines the services that the WCF host will enable. This creates a single <service> named WHSMailHost.WHSMailService, which is the full name of the service class that we will implement shortly. Inside the <service> tag an endpoint is defined. And endpoint is essentially the "port" on which the client connects. The endpoint defined here is using the net.tcp protocol and is set to listen on the localhost on port 12345 at the name IWHSMailService. The next thing defined is a binding. This sets protocol by which the service will communicate, its configuration, and the contract it implements. The binding configuration named NewBinding0 (a default name) can be found above inside the <bindings> tag. The only configuration item that is specified is that security will be turned off for communication between the client and server. Given that these two machines will be connecting to each other on your own local network, security is not a great concern. If you were to use this over a real internet connection where the client and server were open to the outside world, you would definitely not want to do this.

There are around several billion other options, protocols, bindings, etc. etc. etc. that can be configured here. At the end of the article you will find several links to WCF documentation that you can explore to learn more about the WCF internals. Also note that you can configure WCF with a windows UI by selecting the Service Configuration Editor application installed with the Windows SDK. You'll find this in the Microsoft Windows SDK program group off your Start menu.

Outlook and MAPI

MAPI (Messaging Application Programming Interface) is what allows one to develop applications and plugins for Microsoft Outlook and other messaging applications which support it (Exchange, Windows Messaging, etc.). We will be using MAPI to get the data we require from Outlook for our application.

Earlier we created a contract named IWHSMailService. This contract will be implemented by the WHSMailService class that was also created earlier. To do this, set a reference to the project's WHSMailCommon assembly. Then, bring the Contracts and Entities namespaces into the WHSMailService class with the following:

using WHSMailCommon.Contracts;
using WHSMailCommon.Entities;

Imports WHSMailCommon.Contracts
Imports WHSMailCommon.Entities

Then, setup the class to implement the interface as follows:

public class WHSMailService : IWHSMailService

Public Class WHSMailService
    Implements IWHSMailService

Visual Studio will then create the 3 methods that must be implemented according to the interface (GetFolders, GetMessages, GetMessage). We will fill those in shortly. But first, we must implement our constructor. When WCF calls the service, a new instance of the object will be created on each call. Therefore, it is easy to setup any initialization code for the service in the default constructor method. In this case, we will initialize the MAPI layer and logon to the default instance.

First, set a reference to the Microsoft Outlook XX.0 Object Library which you will find under the COM tab assuming Outlook is installed as per the instructions above. Note that the version will depend on what version of Outlook you have installed on your local machine. I'm using Outlook 2007, so version 12 is what the sample code above is referencing. If you are using a different version, reference the appropriate version before continuing.

Once the reference is set, bring the namespace into the WHSMailService class with the following line which will import the namespace and setup an alias named Outlook to save some typing:

using Outlook = Microsoft.Office.Interop.Outlook;

Imports Outlook = Microsoft.Office.Interop.Outlook

Now the constructor can be implemented. We need to get an instance of the Outlook ApplicationClass. From there we can get an instance of the MAPI namespace. All methods that we will be using hang off that namespace object. The code for the constructor follows:

private readonly Outlook.NameSpace _nameSpace = null;

public WHSMailService()
{
    // get an instance of the MAPI namespace and login
    Outlook.Application app = new Outlook.ApplicationClass();
    _nameSpace = app.GetNamespace("MAPI");
    _nameSpace.Logon(null, null, false, false);
}

Private ReadOnly _nameSpace As Outlook.NameSpace = Nothing

Public Sub New()
    ' get an instance of the MAPI namespace and login
    Dim app As Outlook.Application = New Outlook.ApplicationClass()
    _nameSpace = app.GetNamespace("MAPI")
    _nameSpace.Logon(Nothing, Nothing, False, False)
End Sub

With a handle to the namespace, we can write our GetFolders method. This method will get the default Inbox folder in the default Outlook message store, look at the parent node, recursively enumerate from there, pulling out only folders that contain mail items, and finally sort them alphabetically (recall the CompareTo method of the IComparable interface we implemented earlier).

public List<Folder> GetFolders()
{
    List<Folder> list = new List<Folder>();

    // get the inbox and then go up one level...that *should* be the root of the default store
    Outlook.MAPIFolder root = (Outlook.MAPIFolder)_nameSpace.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox).Parent;

    // add root folder
    Folder folder = new Folder(root.EntryID, root.Name, root.UnReadItemCount, root.Items.Count);
    list.Add(folder);

    // Enumerate the sub-folders
    EnumerateFolders(root.Folders, folder);

    return list;
}

private void EnumerateFolders(Outlook.Folders folders, Folder rootFolder)
{
    foreach(Outlook.MAPIFolder f in folders)
    {
        // ensure it's a folder that contains mail messages (i.e. no contacts, appointments, etc.)
        if(f.DefaultItemType == Outlook.OlItemType.olMailItem)
        {
            if(rootFolder.Folders == null)
                rootFolder.Folders = new List<Folder>();

            // add the current folder and enumerate all sub-folders
            Folder subFolder = new Folder(f.EntryID, f.Name, f.UnReadItemCount, f.Items.Count);
            rootFolder.Folders.Add(subFolder);
            if(f.Folders.Count > 0)
                this.EnumerateFolders(f.Folders, subFolder);
        }
    }

    // alphabetize the list (Folder implements IComparable)
    rootFolder.Folders.Sort();
}

Public Function GetFolders() As List(Of Folder) Implements IWHSMailService.GetFolders
    Dim list As List(Of Folder) = New List(Of Folder)()

    ' get the inbox and then go up one level...that *should* be the root of the default store
    Dim root As Outlook.MAPIFolder = CType(_nameSpace.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox).Parent, Outlook.MAPIFolder)

    ' add root folder
    Dim folder As Folder = New Folder(root.EntryID, root.Name, root.UnReadItemCount, root.Items.Count)
    list.Add(folder)

    ' Enumerate the sub-folders
    EnumerateFolders(root.Folders, folder)

    Return list
End Function

Private Sub EnumerateFolders(ByVal folders As Outlook.Folders, ByVal rootFolder As Folder)
    For Each f As Outlook.MAPIFolder In folders
        ' ensure it's a folder that contains mail messages (i.e. no contacts, appointments, etc.)
        If f.DefaultItemType = Outlook.OlItemType.olMailItem Then
            If rootFolder.Folders Is Nothing Then
                rootFolder.Folders = New List(Of Folder)()
            End If

            ' add the current folder and enumerate all sub-folders
            Dim subFolder As Folder = New Folder(f.EntryID, f.Name, f.UnReadItemCount, f.Items.Count)
            rootFolder.Folders.Add(subFolder)
            If f.Folders.Count > 0 Then
                Me.EnumerateFolders(f.Folders, subFolder)
            End If
        End If
    Next f

    ' alphabetize the list (Folder implements IComparable)
    rootFolder.Folders.Sort()
End Sub

This code will return a generic hierarchal list of our Folder entity objects which will be displayed in the web application. Note that one of the items assigned to the Folder entity is the EntryID property from the MAPIFolder object. All MAPI items, be they email messages, folders, appointments, etc. have a unique identifier which is stored in the EntryID field. We will need this unique value later on to retrieve messages from that folder.

Next, let's implement the GetMessages method. This method will return a list of messages (minus the bodies) from the folder specified using the GetFolderFromID method, sorted by the received date with the most current first. It will also handle paging so that the entire folder is not returned at once.

public List<Email> GetMessages(string entryID, int numPerPage, int pageNum)
{
    List<Email> list = new List<Email>();

    Outlook.MAPIFolder f;

    // if no ID specified, open the inbox
    if(string.IsNullOrEmpty(entryID))
        f = _nameSpace.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox);
    else
        f = _nameSpace.GetFolderFromID(entryID, "");

    // to handle the sorting, one needs to cache their own instance of the items object
    Outlook.Items items = f.Items;

    // sort descending by received time
    items.Sort("[ReceivedTime]", true);

    // pull in the correct number of items based on number of items per page and current page number
    for(int i = (numPerPage*pageNum)+1; i <= (numPerPage*pageNum)+numPerPage && i <= items.Count; i++)
    {
        // ensure it's a mail message
        Outlook.MailItem mi = (items[i] as Outlook.MailItem);
        if(mi != null)
            list.Add(new Email(mi.EntryID, mi.SenderEmailAddress, mi.SenderName, mi.Subject, mi.ReceivedTime, mi.Size));
    }

    return list;
}

Public Function GetMessages(ByVal entryID As String, ByVal numPerPage As Integer, ByVal pageNum As Integer) As List(Of Email) Implements IWHSMailService.GetMessages
    Dim list As List(Of Email) = New List(Of Email)()

    Dim f As Outlook.MAPIFolder

    ' if no ID specified, open the inbox
    If String.IsNullOrEmpty(entryID) Then
        f = _nameSpace.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox)
    Else
        f = _nameSpace.GetFolderFromID(entryID, "")
    End If

    ' to handle the sorting, one needs to cache their own instance of the items object
    Dim items As Outlook.Items = f.Items

    ' sort descending by received time
    items.Sort("[ReceivedTime]", True)

    ' pull in the correct number of items based on number of items per page and current page number
    Dim i As Integer = (numPerPage*pageNum)+1
    Do While i <= (numPerPage*pageNum)+numPerPage AndAlso i <= items.Count
        ' ensure it's a mail message
        Dim mi As Outlook.MailItem = (TryCast(items(i), Outlook.MailItem))
        If Not mi Is Nothing Then
            list.Add(New Email(mi.EntryID, mi.SenderEmailAddress, mi.SenderName, mi.Subject, mi.ReceivedTime, mi.Size))
        End If
        i += 1
    Loop

    Return list
End Function

The method takes a string parameter named entryID which is the unique identifier of the folder (from the code above) from which to return the messages. If no ID is specified, messages are returned from the Inbox. This code also handles paging by indexing into the array of Items of the MAPIFolder object at the specified position and counting out numPerPage records to be returned. A list of Email entity objects is returned from this method to be displayed on the web interface.

Finally, let's implement the GetMessage method. This will return a specific message based on the MAPI EntryID using the GetItemFromID method and format the body for plain text or HTML display.

public Email GetMessage(string entryID)
{
    // pull the message
    Outlook.MailItem mi = (_nameSpace.GetItemFromID(entryID, "") as Outlook.MailItem);

    if (mi != null)
    {
        string body;

        // if it's a plain format message, wrap it in <pre> tags for nice output
        if(mi.BodyFormat == Outlook.OlBodyFormat.olFormatPlain)
            body = "<pre>" + mi.Body + "</pre>";
        else
            body = mi.HTMLBody;

        return new Email(mi.EntryID, mi.SenderEmailAddress, mi.SenderName, mi.Subject, mi.ReceivedTime, mi.Size, body);
    }
    else
        return null;
}

Public Function GetMessage(ByVal entryID As String) As Email Implements IWHSMailService.GetMessage
    ' pull the message
    Dim mi As Outlook.MailItem = (TryCast(_nameSpace.GetItemFromID(entryID, ""), Outlook.MailItem))

    If Not mi Is Nothing Then
        Dim body As String

        ' if it's a plain format message, wrap it in <pre> tags for nice output
        If mi.BodyFormat = Outlook.OlBodyFormat.olFormatPlain Then
            body = "<pre>" & mi.Body & "</pre>"
        Else
            body = mi.HTMLBody
        End If

        Return New Email(mi.EntryID, mi.SenderEmailAddress, mi.SenderName, mi.Subject, mi.ReceivedTime, mi.Size, body)
    Else
        Return Nothing
    End If
End Function

With these three methods in place, we can get our folders, get messages in those folders, and get a specific message from a folder. Now we can switch our attention to the web-based "client" application which will plug into WHS.

ASP.NET "Client"

The client we are going to produce is going to be a very simple 3-paned screen much like Outlook with folders on the left, messages on the top right, and message text on the bottom right.

Create a new ASP.NET Web Application named WHSMailWeb (if you are using the Express editions of Visual Studio, you will need to do this in Visual Web Developer Express). Set a reference to the WHSMailCommon assembly along with the System.ServiceModel assembly. Again, if you are in Express, you will have to set the reference to WHSMailCommon in the other project's bin directory.

First, let's configure the ASP.NET application so it can properly call our WCF service running on the host machine. Open the web.config file and add the following after the end </system.web> tag and before the end </configuration> tab:

<system.serviceModel>
    <bindings>
        <netTcpBinding>
            <binding name="NewBinding0" maxReceivedMessageSize="1048576">
                <readerQuotas maxStringContentLength="1048576" />
                <security mode="None" />
            </binding>
        </netTcpBinding>
    </bindings>
    <client>
        <endpoint address="net.tcp://SERVERNAME:12345/IWHSMailService"
            binding="netTcpBinding" bindingConfiguration="NewBinding0"
            contract="WHSMailCommon.Contracts.IWHSMailService" name="WHSMailService" />
    </client>
</system.serviceModel>

This looks very similar to the configuration information from our host service. An endpoint is defined which points to the host server. YOU WILL NEED TO CHANGE THE "SERVERNAME" HOST TO THE NAME OR IP ADDRESS OF THE MACHINE THAT WILL RUN THE HOST SERVICE WE CREATED ABOVE!

You will see the same setup for the binding and contract. The name parameter will be used by the code a bit later so WCF knows how to contact the host to instantiate the remote object.

The one thing that is different here is the netTcpBinding configuration. The security mode is set to none as it was before, but we have the addition of the maxReceivedMessageSize and maxStringContentLength. Both of these are set at 1 megabyte to allow that much data to be transferred from the host to the client. The default is only 64K which is not enough to return most of the data we need to serialize and transmit between the two machines.

Next, add a page to the project named BasePage. This page will be inherited by all pages in the project to easily startup and shutdown the WCF channel required to retrieve the message data.

Open the code-behind file for BasePage and add the following code:

using System;
using System.ServiceModel;
using WHSMailCommon.Contracts;

namespace WHSMailWeb
{
    public partial class BasePage : System.Web.UI.Page
    {
        ChannelFactory<IWHSMailService> _factory = null;
        private IWHSMailService _channel = null;

        protected void Page_Init(object sender, EventArgs e)
        {
            // create a channel factory and then instantiate a proxy channel
            _factory = new ChannelFactory<IWHSMailService>("WHSMailService");
            _channel = _factory.CreateChannel();
        }

        protected void Page_Unload(object sender, EventArgs e)
        {
            try
            {
                _factory.Close();
            }
            catch
            {
                // for the moment, we don't really care what happens here...if it fails, so be it
            }
        }

        public IWHSMailService WHSMailService
        {
            get { return _channel; }
        }
    
    }
}

Imports Microsoft.VisualBasic
Imports System
Imports System.ServiceModel
Imports WHSMailCommon.Contracts

Namespace WHSMailWeb
    Public Partial Class BasePage
        Inherits System.Web.UI.Page
        Private _factory As ChannelFactory(Of IWHSMailService) = Nothing
        Private _channel As IWHSMailService = Nothing

        Protected Sub Page_Init(ByVal sender As Object, ByVal e As EventArgs)
            ' create a channel factory and then instantiate a proxy channel
            _factory = New ChannelFactory(Of IWHSMailService)("WHSMailService")
            _channel = _factory.CreateChannel()
        End Sub

        Protected Sub Page_Unload(ByVal sender As Object, ByVal e As EventArgs)
            Try
                _factory.Close()
            Catch
                ' for the moment, we don't really care what happens here...if it fails, so be it
            End Try
        End Sub

        Public ReadOnly Property WHSMailService() As IWHSMailService
            Get
                Return _channel
            End Get
        End Property

    End Class
End Namespace

This code overrides the page's Init and Unload methods. Page_Init is called at the beginning of a page request and Page_Unload is called just before the request completes.

The Page_Init method here uses WCF to create a ChannelFactory object factory that will return proxy objects of type IWHSMailService. Recall that this is the interface which defines the contract of our service. The name passed as a parameter to the ChannelFactory constructor must match the name of the service in the configuration file, as discussed earlier.

Next, a channel object is created by calling CreateChannel from the ChannelFactory. This is what returns the fake, proxy object defined by our contract. A property named WHSMailService at the bottom of the class exposes this so that the inherited pages can easily use the object to call the host service. We'll see this a bit later.

The Page_Unload method simply closes the factory object and very poorly handles any exceptions that may occur when doing so. An error on close isn't critical to this application, but that is certainly not always the case.

Now we will implement the default page. I'm not going to repeat the entire HTML of the page itself here, and I'm certainly not a HTML/CSS designer, so I wouldn't recommend learning from that anyhow. It does, however, get the job done.

What you do need to know is that the page contains 4 <DIV> tags: one contains an ASP.NET TreeView object (the left-most pane), one contains an ASP.NET GridView object (the top-right pane), one contains 2 ASP.NET LinkButton's which implement a Next/Back paging scheme (the middle-right pane), and the last contains a table to display some header information, and a <DIV> to display the message contents.

After that poor description, here's what the application looks like in an instance of Internet Explorer with my instance of Outlook (with some blurring over the (not really) sensitive data):

Now let's implement the actual logic for the page. Open the Default.aspx page's code behind file. Bring in the WHSMailCommon.Entities namespace as follows:

using WHSMailCommon.Entities;

Imports WHSMailCommon.Entities

Next, change the _Default class to inherit from BasePage instead of System.Web.UI.Page:

public partial class _Default : BasePage

Public Partial Class _Default
    Inherits BasePage

Then, implement the Page_Load method. This method will be called after the Page_Init method which is implemented in our parent object and will be called automatically.

private string _folderEntryID = string.Empty;
private int _pageNum = 0;

protected void Page_Load(object sender, EventArgs e)
{
    // first time in (tvFolders has viewstate enabled
    if(tvFolders.Nodes.Count == 0)
    {
        // get the folder tree
        List<Folder> folderList = this.WHSMailService.GetFolders();

        // add the root node and expand it
        TreeNode node = new TreeNode(folderList[0].Name, folderList[0].EntryID);
        node.Expanded = true;
        tvFolders.Nodes.Add(node);

        // load up the sub-folders
        LoadNode(folderList[0].Folders, node);

        // get the inbox list and bind it to the grid
        List<Email> list = GetMessages();
        BindMessages(list);

        // save off the default page number and folder ID
        ViewState["PageNum"] = _pageNum;
        ViewState["FolderID"] = _folderEntryID;
    }

    _pageNum = int.Parse(ViewState["PageNum"].ToString());
    _folderEntryID = ViewState["FolderID"].ToString();
}

private void LoadNode(List<Folder> folders, TreeNode node)
{
    foreach(Folder f in folders)
    {
        // add the node with the format of Folder (Unread/Total)
        TreeNode subNode = new TreeNode(f.Name + " (" + f.UnreadMessages + "/" + f.TotalMessages + ")", f.EntryID);

        // expand and select the inbox
        subNode.Expanded = subNode.Selected = (f.Name == "Inbox");
        node.ChildNodes.Add(subNode);

        // load the subfolders
        if(f.Folders != null)
            LoadNode(f.Folders, subNode);
    }
}

private List<Email> GetMessages()
{
    // get a group of messages based on the current page number and size
    return this.WHSMailService.GetMessages(_folderEntryID, GridView1.PageSize, _pageNum);
}

private void BindMessages(List<Email> list)
{
    // load the grid
    GridView1.DataSource = list;
    GridView1.DataBind();

    // save off the new page number
    ViewState["PageNum"] = _pageNum;
}

Private _folderEntryID As String = String.Empty
Private _pageNum As Integer = 0

Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
    ' first time in (tvFolders has viewstate enabled
    If tvFolders.Nodes.Count = 0 Then
        ' get the folder tree
        Dim folderList As List(Of Folder) = Me.WHSMailService.GetFolders()

        ' add the root node and expand it
        Dim node As TreeNode = New TreeNode(folderList(0).Name, folderList(0).EntryID)
        node.Expanded = True
        tvFolders.Nodes.Add(node)

        ' load up the sub-folders
        LoadNode(folderList(0).Folders, node)

        ' get the inbox list and bind it to the grid
        Dim list As List(Of Email) = GetMessages()
        BindMessages(list)

        ' save off the default page number and folder ID
        ViewState("PageNum") = _pageNum
        ViewState("FolderID") = _folderEntryID
    End If

    _pageNum = Integer.Parse(ViewState("PageNum").ToString())
    _folderEntryID = ViewState("FolderID").ToString()
End Sub

Private Sub LoadNode(ByVal folders As List(Of Folder), ByVal node As TreeNode)
    For Each f As Folder In folders
        ' add the node with the format of Folder (Unread/Total)
        Dim subNode As TreeNode = New TreeNode(f.Name & " (" & f.UnreadMessages & "/" & f.TotalMessages & ")", f.EntryID)

        ' expand and select the inbox
        subNode.Selected = (f.Name = "Inbox")
        subNode.Expanded = subNode.Selected
        node.ChildNodes.Add(subNode)

        ' load the subfolders
        If Not f.Folders Is Nothing Then
            LoadNode(f.Folders, subNode)
        End If
    Next f
End Sub

Private Function GetMessages() As List(Of Email)
    ' get a group of messages based on the current page number and size
    Return Me.WHSMailService.GetMessages(_folderEntryID, GridView1.PageSize, _pageNum)
End Function

Private Sub BindMessages(ByVal list As List(Of Email))
    ' load the grid
    GridView1.DataSource = list
    GridView1.DataBind()

    ' save off the new page number
    ViewState("PageNum") = _pageNum
End Sub

If the tvFolders tree-view has not been filled in, we call our host service's GetFolders method from the WHSMailService property as defined above. The method then enumerates through the hierarchical list of folders returned, building the same tree structure that exists in Outlook. The Text property of each TreeNode is set to the folder name with a count of messages unread and total count of messages. The Value property of the node is set to the unique MAPI-defined EntryID so that we can later grab that value to return the list of messages from that specific folder.

Next, we call our service's GetMessages method to return messages from the Inbox. We pass in the value from the grid view's PageSize property and a member variable named _pageNum. This will handle our paging scheme as we discussed earlier. Once that list of messages is returned, is it bound to the data grid for display.

Finally, the default page number and folder entry ID (0 and "" respectively) are stored in the ViewState so they can be assigned back to our member variables on each page request.

If you were to run the application right now, you would see the same page that you do above, minus the message text at the bottom.

Next, we will implement what occurs when a user clicks on a folder in the tree view. We simply pull out the MAPI unique EntryID which is stored in the Value field of the selected node, assign it to the local member variable and view state, and then call the GetMessages method from our service to return a list of messages from that folder, just as we did with the inbox above. The code below shows the process:

protected void tvFolders_SelectedNodeChanged(object sender, EventArgs e)
{
    // new folder, so reset the view
    _pageNum = 0;
    _folderEntryID = this.tvFolders.SelectedNode.Value;
    ViewState["FolderID"] = _folderEntryID;

    List<Email> list = GetMessages();
    BindMessages(list);
}

Protected Sub tvFolders_SelectedNodeChanged(ByVal sender As Object, ByVal e As EventArgs)
    ' new folder, so reset the view
    _pageNum = 0
    _folderEntryID = Me.tvFolders.SelectedNode.Value
    ViewState("FolderID") = _folderEntryID

    Dim list As List(Of Email) = GetMessages()
    BindMessages(list)
End Sub

Next, we can implement the Next/Back link buttons. These methods simply increment or decrement the current page number, assign it to the view state for use on the next request, and then, just as before, gets the list of messages specific to the currently selected folder, using the unique ID stored in the view state.

protected void btnPrev_Click(object sender, EventArgs e)
{
    // first page
    if(_pageNum > 0)
        _pageNum--;

    List<Email> list = GetMessages();
    BindMessages(list);
}

protected void btnNext_Click(object sender, EventArgs e)
{
    // next page
    _pageNum++;
    List<Email> list = GetMessages();

    // if we're out of messages, go back to the previous page
    if(list == null || list.Count == 0)
    {
        _pageNum--;
        list = GetMessages();
    }
    BindMessages(list);
}

Protected Sub btnPrev_Click(ByVal sender As Object, ByVal e As EventArgs)
    ' first page
    If _pageNum > 0 Then
        _pageNum -= 1
    End If

    Dim list As List(Of Email) = GetMessages()
    BindMessages(list)
End Sub

Protected Sub btnNext_Click(ByVal sender As Object, ByVal e As EventArgs)
    ' next page
    _pageNum += 1
    Dim list As List(Of Email) = GetMessages()

    ' if we're out of messages, go back to the previous page
    If list Is Nothing OrElse list.Count = 0 Then
        _pageNum -= 1
        list = GetMessages()
    End If
    BindMessages(list)
End Sub

And finally, we need to implement what happens when the user selects a message from the top pane. If you look at the HTML for the Default page, you will see that the Subject field is bound to a LinkButton control in the grid view via a TemplateField (the rest of the fields are standard BoundFields. The LinkButton sets the CommandArgument property to the unique EntryID of that message as defined by MAPI. So, all we need to do is listen on the server for the LinkButton's Command event, grab the unique ID and call our service's GetMessage method with that ID to return the message itself.

protected void btnLink_Command(object sender, CommandEventArgs e)
{
    Email email = this.WHSMailService.GetMessage(e.CommandArgument.ToString());

    // fill out the header with some basic info
    lblFrom.Text = email.FromName + "&nbsp;(" + email.From + ")";
    lblSubject.Text = email.Subject;
    lblReceived.Text = email.Received.ToString();

    // when a message is selected, write out the content
    msgContent.InnerHtml = email.Body;
}

Protected Sub btnLink_Command(ByVal sender As Object, ByVal e As CommandEventArgs)
    Dim email As Email = Me.WHSMailService.GetMessage(e.CommandArgument.ToString())

    ' fill out the header with some basic info
    lblFrom.Text = email.FromName & "&nbsp;(" & email.From & ")"
    lblSubject.Text = email.Subject
    lblReceived.Text = email.Received.ToString()

    ' when a message is selected, write out the content
    msgContent.InnerHtml = email.Body
End Sub

The Email entity is retrieved, its properties are set to the labels in the header, and the message content is assigned to the InnerHtml property of the content holding <DIV>.

Voila! A very simple mail reader.

That's it for code. Now we need to deploy the applications and configure Windows Home Server.

Deployment

WHSMailHost

If you are deploying to a machine that is not your development machine, install the .NET Framework 3.0 runtime on the machine to which you will be running the host service. Then, copy the WHSMailHost.exe, WHSMailHost.exe.config, and WHSMailCommon.dll files to the machine running Outlook that will be connected to by the web application. You may want to create a shortcut in the Startup group so it will launch when you log into Windows.

Next, open Outlook and select Trust Center from the Tools menu. Choose Programmatic Access and set the option to Never warn me about suspicious activity. Unfortunately this must be disabled, otherwise Outlook will prompt you every time the host process attempts to retrieve any data. There is no way to bypass this on an application-by-application basis, so we have to turn it off for all applications.

If you are running firewall software on the PC, ensure that port 12345 will allow traffic to pass through. You may also change port 12345 to a different port, but you must change it in the configuration files for both applications.

Finally, note that Outlook does not need to remain open to use this application. You do, however, need to be logged into the machine with the host running.

WHSMailWeb

On your Windows Home Server machine, install the .NET Framework 3.0 Runtime. This is needed to use WCF. Next, create a new directory named mail (or anything you wish, but it is assumed it is named mail) in the c:\inetpub directory. Copy all .aspx pages, web.config, icon.png and the bin directory to the mail directory. You could also share out the mail directory and use Visual Studio's Publish command to automatically copy the files to that share. Then, open the Internet Information Services (IIS) Manager application from the Administrative Tools group on the Start menu. Open Web Sites and then Default Web Site in the left pane. Right-click on Default Web Site and select New -> Virtual Directory... from the context menu. When prompted, use the following values:

Alias	mail
Path	c:\inetpub\mail
Permissions	Read, Run Scripts

The next part is a bit tricky. We want to integrate with the security already provided by Windows Home Server. The WHS remote website uses Forms security from ASP.NET. Ideally, you should be able to log into the main page of the WHS remote website and then open the webmail link without having to log in again. Additionally, if the mail URL is used directly, you should be prompted for your login credentials.

To achieve this, open the web.config file from c:\inetpub\remote in Notepad. In the XML, between the start and end <system.web> tags you will find the configuration for the Forms-based authentication used by WHS. In order to use the cookie that is created by this authentication method, we need to have the same key values in our web.config file. The easiest way to achieve this is to copy all of the the text between the two <system.web> tags. Next, open the web.config file from the mail directory that you just copied over and paste the text between the two lines informing you to do so. Finally, we need to update the loginUrl and defaultRedirect paths in the forms and customErrors keys. Add /remote/ to the beginning of each to make them /remote/login.aspx and /remote/error.aspx. Be sure that the SERVERNAME item in the endpoint configuration is updated to the name/IP address of the machine running the host process.

With the files copied and edited, ensure that permissions on the file are propagated from the root mail directory to the files inside.

Finally, open the websites.xml file in the /remote directory and add the following XML before the end </WebSites> tag:

<WebSite name="Outlook Webmail" uri="/mail" imageUrl="/mail/icon.png" absolute="false"></WebSite>

With the configuration done, we need to enable web site connectivity in WHS. Double-click the Windows Home Server Console icon on the desktop. When it loads, click the Settings button in the top right corner. When the Settings dialog appears, select Remote Access in the left pane and then click the Turn On button in the right pane, assuming web site connectivity is off. If it already enabled, skip this step.

With all that done, create a user account for yourself in WHS so that you can login remotely. That's it!

Running the Application

Ensure the WHSMailHost application is running on the PC with Outlook installed. Then, browse to your Windows Home Server's default website. After logging in, you should see a link on the right side of the screen named Outlook Webmail.

Click that to start our application and if everything is working, you should see the web page as shown above.

Troubleshooting

If the web page displays an error message, open the web.config file in the mail directory on your Windows Home Server. Look for the <customErrors> tag and change the mode parameter to Off. This should allow you to see the actual error that is occurring and provide more information as to the status of the application.

Conclusion

Phew! Two applications and one shared assembly later, we have a web-based add-in for Windows Home Server that allows one to remotely access their Outlook message store. Currently the application is read-only and provides only minimal functionality. It's a great starting point to create a full-fledged webmail client interface. The project is hosted on CodePlex so I'm hoping to see you readers implement additional features and functionality that you find useful.

Additional Information

Here are a few links with additional information on the items discussed here:

Bio

Brian is a Microsoft C# MVP and a recognized .NET expert with over 6 years experience developing .NET solutions, and over 9 years of professional experience architecting and developing solutions using Microsoft technologies and platforms, although he has been "coding for fun" for as long as he can remember. Outside the world of .NET and business applications, Brian enjoys developing both hardware and software projects in the areas of gaming, robotics, and whatever else strikes his fancy for the next ten minutes. He rarely passes up an opportunity to dive into a C/C++ or assembly language project. You can reach Brian via his blog at http://www.brianpeek.com/.

Collecting Outlook 2007 Statistics Using VSTO 2005 SE

Coding4Fun — Tue, 21 Nov 2006 01:08:00 GMT

	This article demonstrates how you can create an Outlook add-in using VSTO 2005 SE to listen to outlook events, store data about outlook usage, and produce reports on that usage in a custom form and a form region.
Kevin Marshall, Clarity Consulting, Inc. Clarity Blogs Difficulty: Intermediate Time Required: 1-3 hours Cost: Free Software: Office 2007 Visual Studio Express VSTO 2005 SE Outlook Add-in Templates Hardware: Download: Download

Outlook is used by many people everyday, but few people probably realize the wealth of data that can be learned from how they use Outlook. How long does it take you to respond to emails on average? How many hours do you spend in meetings per week? Using Visual Studio Tools for Office Second Edition (VSTO 2005 SE) and Office 2007, you can easily find the answers to these questions and more by building an add-in for Outlook. This article demonstrates how you can listen to outlook events, store data about outlook usage, and produce reports on that usage in a custom form and new to VSTO 2005 SE, a form region.

What is VSTO 2005 SE?

VSTO 2005 SE is a free add-on to Visual Studio 2005 that enables developers to build applications targeting the 2007 Office system. Developers can create Office-based solutions using the professional development environment of Visual Studio 2005 and the new programming model features of Office 2007 like the ribbon bar and custom form regions.

Creating an Outlook Add-in Project

After installing VSTO 2005 SE and the Outlook Add-in template, you can begin creating an Outlook 2007 add-in. Create a new project, then select Office Outlook 2007 Add-in from the My Templates group and click OK.

The newly created project will have several files. Connect.cs is the main file which contains two methods, InitializeAddin and ShutdownAddin which provide you a starting point for interfacing with Outlook.

Initializing the Add-in

The InitializeAddin method is called whenever your add-in is loaded into memory. For our add-in, we will do three things during start up:

Create an instance of our EventTracker class. This is the main class that handles all of the logic for processing incoming appointment and mail items.
Load existing Outlook data via the EventTracker.
Add a menu item to the Outlook toolbar. The menu item is used to pop up the report window.

Visual C#

private void InitalizeAddin()
{
   //Initialize report menu item
   this.InitializeMenu();

   // Initialize the event tracker object.
   _eventTracker = new EventTracker(this.Application);

   ListenToEvents(true);

   _eventTracker.LoadData();
}

Visual Basic

Private Sub InitalizeAddin()

    '//Initialize report menu item
   InitializeMenu()

    '// Initialize the event tracker object.
   _eventTracker = New EventTracker(Me.Application)

    ListenToEvents(True)

   _eventTracker.LoadData()
End Sub

Top-level menu items can be created the same way in office application. For this add-in, we’ll create a new menu “Reports”, with a single menu item to launch the report popup window.

Visual C#

// Get the Outlook menu bar.
_menuBar = this.Application.ActiveExplorer().CommandBars.ActiveMenuBar;

// Get the index of the Help menu item on the Outlook menu bar.
_helpMenuIndex = _menuBar.Controls[_MENU_BEFORE].Index;
// Add the top-level menu right before the Help menu.
_topMenu =

(Office.CommandBarPopup)_menuBar.Controls.Add(Office.MsoControlType.msoControlPopup,
   Type.Missing, Type.Missing, _helpMenuIndex, true);

_topMenu.Caption = "Reports";
_topMenu.Visible = true;

// Add the menu item for loading email reports.
_reports =

   (Office.CommandBarButton)_topMenu.Controls.Add(Office.MsoControlType.msoControlButton,

   Type.Missing, Type.Missing, Type.Missing, true);                                                                                   Type.Missing,                                                                                 Type.Missing,                                                                                   Type.Missing,                                                                                    true);

_reports.Caption = "Calendar / Email Reports";
_reports.Visible = true;

Visual Basic

 '// Get the Outlook menu bar.
 _menuBar = Me.Application.ActiveExplorer().CommandBars.ActiveMenuBar

 '// Get the index of the Help menu item on the Outlook menu bar.
_helpMenuIndex = _menuBar.Controls(_MENU_BEFORE).Index

 '// Add the top-level menu right before the Help menu.
_topMenu =

   CType(_menuBar.Controls.Add(Office.MsoControlType.msoControlPopup, _
      Type.Missing, Type.Missing, _helpMenuIndex, True), Office.CommandBarPopup)

 _topMenu.Caption = "Reports"
 _topMenu.Visible = True

 ' Add the menu item for loading email reports.
_reports = _topMenu.Controls.Add(Office.MsoControlType.msoControlButton, _
         Type.Missing, Type.Missing, Type.Missing, True)
 _reports.Caption = "Calendar / Email Reports"
 _reports.Visible = True

Loading Statistics Based on Existing Outlook Data

Data to produce reports on Outlook usage is stored in a SQL Express database. When the add-in first loads, it needs to scan the mail and calendar folders to gather statistics on existing items. The EventTracker class handles the initial data load, as well as hooking events fired when new items are added to those folders.

The schema for the database has tables for storing information about the three types of items we are reporting statistics: inbox items, sent mail items, and appointment items.

Since scanning through the folders can take some time if you are like me and keep every email ever received, it’s best to start the initial data load on a separate thread. Now Outlook can continue responding to user input, while the add-in does its work.

Visual C#

public void LoadData()
{
   //create new thread for large inboxes
   Thread thread = new Thread(new ThreadStart(CheckInitialLoad));
   thread.IsBackground = true;
   thread.Start();
}

Visual Basic

Public Sub LoadData()
   Dim thread As Thread = New Thread(AddressOf CheckInitialLoad)
   thread.IsBackground = True
   thread.Start()
End Sub

The initial data load raises an to notify other code, like the report popup form, that the data isn’t ready to produce reports yet. If the database doesn’t contain any exisitng data, then the data load will add records for each exisiting item. Allowing the thread to sleep briefly between iterations prevents the data load from interfering with the responsiveness of the main Outlook thread.

Visual C#

private void CheckInitialLoad()
{
   if (!object.Equals(StartDataLoad,null))
   {
      StartDataLoad(this, null);
   }

ReportDBDataSetTableAdapters.SentMailTableAdapter sentItemTA =

   new ReportDBDataSetTableAdapters.SentMailTableAdapter();
ReportDBDataSetTableAdapters.InboxTableAdapter inboxTA =

   new ReportDBDataSetTableAdapters.InboxTableAdapter();
ReportDBDataSetTableAdapters.CalendarTableAdapter calTA =

   new ReportDBDataSetTableAdapters.CalendarTableAdapter();

   //check to see if calendar stats have been loaded
   if (calTA.GetData().Rows.Count == 0)
   {
      foreach (object item in _calendarItems)
      {
         if (item is Outlook.AppointmentItem)
         {
            AddCalendarItem(item as Outlook.AppointmentItem);
         }
         Thread.Sleep(10);
      }
   }
   if (!object.Equals(StopDataLoad, null))
   {
      StopDataLoad(this, null);
   }
}

Visual Basic

 Private Sub CheckInitialLoad()

   RaiseEvent StartDataLoad(Me, Nothing)

   Dim sentItemTA As ReportDBDataSetTableAdapters.SentMailTableAdapter = _

      New ReportDBDataSetTableAdapters.SentMailTableAdapter
   Dim inboxTA As ReportDBDataSetTableAdapters.InboxTableAdapter = _

      New ReportDBDataSetTableAdapters.InboxTableAdapter
   Dim calTA As ReportDBDataSetTableAdapters.CalendarTableAdapter = _

      New ReportDBDataSetTableAdapters.CalendarTableAdapter

   If calTA.GetData.Rows.Count = 0 Then
      For Each item As Object In _calendarItems
         If TypeOf item Is Outlook.AppointmentItem Then
            AddCalendarItem(CType(item, Outlook.AppointmentItem))
         End If
         Thread.Sleep(10)
      Next
   End If
   If inboxTA.GetData.Rows.Count = 0 Then
       For Each item As Object In _inboxItems
          If TypeOf item Is Outlook.MailItem Then
             AddInboxItem(CType(item, Outlook.MailItem))
          End If
          Thread.Sleep(10)
        Next
    End If
    If sentItemTA.GetData.Rows.Count = 0 Then
       For Each item As Object In _sentMailItems
          If TypeOf item Is Outlook.MailItem Then
             AddSentMailItem(CType(item, Outlook.MailItem))
          End If
      Thread.Sleep(10)
      Next
   End If

   RaiseEvent StopDataLoad(Me, Nothing)

End Sub

By listening to the StartDataLoad and StopDataLoad events, we can display a message to the user if they try to load a report.

Visual C#

if (_isDataLoading)
{
MessageBox.Show("Outlook is currently initializing your folders to

   enable reporting for the first time.  Try again in a few minutes.", 
   "Loading initial data", MessageBoxButtons.OK, MessageBoxIcon.Warning);
}

Visual Basic

If (_isDataLoading) Then

MessageBox.Show("Outlook is currently initializing your folders to enable reporting for the first time.  Try again in a few minutes.", "Loading initial data", MessageBoxButtons.OK, MessageBoxIcon.Warning)

Listening for New Items

After the initial data load, the add-in can just listen for incoming items to keep track of Outlook usage. To listen for incoming items, you can use folder events. To hook into folder events you first need to obtain a reference to an Outlook.MAPIFolder object that encapsulates an Outlook folder like Inbox, Sent Mail, or Calendar. In order to get the default Outbox folder call the GetDefaultFolder method of the MAPI namespace object. Then you need to add handlers for the ItemAdd event of the Outlook folders. The following code shows how to listen for incoming mail items in the Inbox folder.

Visual C#

// Obtain references to the folder objects that fire the events we are interested in.
Outlook.MAPIFolder inbox =

   app.Session.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox);
// Store references to the item collection objects.
_inboxItems = inbox.Items;
_inboxItems.ItemAdd += new Outlook.ItemsEvents_ItemAddEventHandler(InboxFolderItemAdded)

/// <summary>
/// Handles new mail items added to the inbox
/// </summary>
/// <param name="Item">Reference to the Outlook object added</param>
private void InboxFolderItemAdded(object Item)
{
   if (Item is Outlook.MailItem)
   {
      AddInboxItem(Item as Outlook.MailItem);
   }
}

Visual Basic

Dim inbox As Outlook.MAPIFolder = _

   app.Session.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox)
_inboxItems = inbox.Items
AddHandler _inboxItems.ItemAdd, AddressOf InboxFolderItemAdded

Private Sub InboxFolderItemAdded(ByVal Item As Object)
   If TypeOf Item Is Outlook.MailItem Then
      AddInboxItem(CType(Item, Outlook.MailItem))
   End If
End Sub

Appointments and sent mail items can be tracked in a similar manner. Additionally, the Outlook folders support events for removing or changing items.

Items can easily be stored in the database by using table adapters automatically generated from the dataset. Each item has a table adapter which corresponds to a table in the database.

Visual C#

/// <summary>
/// Stores a new message in the database
/// </summary>
/// <param name="mailItem"></param>
private void AddInboxItem(Outlook.MailItem mailItem)
{
ReportDBDataSetTableAdapters.InboxTableAdapter ta =

   new ReportDBDataSetTableAdapters.InboxTableAdapter();

   //determine if mail was sent to an alias or group address
   bool isAliased = true;
   if (mailItem.To == mailItem.ReceivedOnBehalfOfName || mailItem.CC == mailItem.ReceivedOnBehalfOfName)
   {
      isAliased = false;
   }
   try
   {
      ta.Insert(mailItem.SenderName,

      mailItem.SenderName, mailItem.SentOn, isAliased, null,

      mailItem.Subject, mailItem.EntryID);
   }
   catch (Exception ex)
   {
      System.Diagnostics.Debug.Write(ex);
   }
}

Visual Basic

Private Sub AddInboxItem(ByVal mailItem As Outlook.MailItem)
   Dim ta As ReportDBDataSetTableAdapters.InboxTableAdapter = New ReportDBDataSetTableAdapters.InboxTableAdapter
   Dim isAliased As Boolean = True
   If mailItem.To = mailItem.ReceivedOnBehalfOfName OrElse mailItem.CC = mailItem.ReceivedOnBehalfOfName Then
                isAliased = False
   End If
   Try
      ta.Insert(mailItem.SenderName, mailItem.SenderName, mailItem.SentOn, isAliased, Nothing, mailItem.Subject, mailItem.EntryID)
   Catch ex As Exception
      System.Diagnostics.Debug.Write(ex)
   End Try
End Sub

Producing the Reports

Now that we a have some data points about our Outlook usage, we can produce reports. The reports are displayed in a datagrid on a form that is launched from the Reports menu. The report popup dialog contains a selector for various report types and a selectable date range.

Each report is populated using a method from our table adapters. For example, to get a count of emails sent over a given period, you can use the following code:

Visual C#

this.inboxTableAdapter.CountEmailsRecieved(this.reportDBDataSet.Inbox, fromDate, toDate);
this.dataGridView1.Columns.Add("Emails Recieved", "Emails Received");
this.dataGridView1.Columns["Emails Recieved"].DataPropertyName = "Emails Recieved";
this.reportDBDataSetBindingSource.DataSource = this.reportDBDataSet.Inbox;

Visual Basic

Me.InboxTableAdapter.CountEmailsRecieved(Me.ReportDBDataSet.Inbox, fromDate, toDate)
Me.dataGridView1.Columns.Add("Emails Recieved", "Emails Received")
Me.dataGridView1.Columns("Emails Recieved").DataPropertyName = "Emails Recieved"
Me.reportDBDataSetBindingSource.DataSource = Me.ReportDBDataSet.Inbox

Creating a Form Region

Another way you can display data about Outlook usage is a form region. Form regions can be added to any existing Outlook form. You can also control whether the region is shown in the preview pane, the inspector, or on new items. For this add-in, we’ll add a form region on email messages to show statistics about the recipient / sender.

The first step in creating a new form region is to customize an existing Outlook form. In Outlook, click Tools -> Forms -> Design a Form. Then select Message from the standard forms library. The Outlook form will appear in the design view. On the ribbon bar, select the button for creating a new form region.

On the form, add a new textbox control. You can’t use the regular Outlook textbox though. Right-click the Toolbox window and select Custom Controls. Scroll through the list of controls and select the Microsoft Office Outlook TextBox Control, and then click OK.

Add the textbox to the form to display the Outlook statistics.

Now you can save the form region as an .ofs file and add it to the project as a resource file. In order to connect the form region with our add-in, we need to create a region manifest file and a registry entry. The region manifest is an xml file that defines how Outlook displays the region.

<?xml version="1.0" encoding="utf-8" ?>
<FormRegion xmlns="http://schemas.microsoft.com/office/12/outlook/formregion.xsd">
  <name>OutlookStatsRegionCS</name>
  <formRegionType>adjoining</formRegionType>
  <title>Outlook Statistics</title>
  <showInspectorRead>true</showInspectorRead>
  <showReadingPane>true</showReadingPane>
  <showInspectorCompose>false</showInspectorCompose>
  <addin>OutlookStatsCS.Connect</addin>
</FormRegion>

The documentation for the XML Schema for form regions is located here. Since the form for composing new mail item shouldn’t have usage statistics at the bottom, set the showInspectorCompose property to false.

To associate the region manifest with Outlook, you need to create a new registry key under HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions\IPM.Note called OutlookStatsRegionCS. The value of the key should be the path to the region manifest XML file. A sample registry file is included in the project’s \Registry folder in the region_registry.reg file.

Wiring the Region to the Outlook Add-in

Because form regions are based on the Microsoft Forms 2.0 types, you need to add a reference in the add-in project to Microsoft Forms 2.0 Object Library. Now you can add a new class to manage that form region, called OutlookStatsRegion.cs.

The constructor for this class needs a reference to the instance of the form region.

Visual C#

public OutlookStatsRegion(Outlook.FormRegion region)
{
   _region = region;
   _region.Close += new Outlook.FormRegionEvents_CloseEventHandler(Region_Close);

   _form = region.Form as Forms.UserForm;

   _txtStats = (Outlook.OlkTextBox)_form.Controls.Item("txtStats");
   _txtStats.Text = GetEmailStatistics(region.Item);
}

Visual Basic

Public Sub New(ByVal [region] As Outlook.FormRegion)
   _region = [region]
   AddHandler _region.Close, AddressOf Region_Close

   _form = CType([region].Form, Forms.UserForm)

   _txtStats = CType(_form.Controls.Item("txtStats"), Outlook.OlkTextBox)
   _txtStats.Text = GetEmailStatistics([region].Item)
End Sub 'New

Using the reference to the region, we can get access to the mail item, and therefore the sender name and email address need to display the statistics.

Visual C#

private string GetEmailStatistics(object Item)
{
   string result = string.Empty;

   if (Item is Outlook.MailItem)
   {
      Outlook.MailItem mailItem = Item as Outlook.MailItem;

ReportDBDataSetTableAdapters.InboxTableAdapter inboxTA = new ReportDBDataSetTableAdapters.InboxTableAdapter();

      int? countEmailsReceived = inboxTA.CountEmailsReceivedFrom(mailItem.SenderName);
                
      sb.Append("Emails received from ");
      sb.Append(mailItem.SenderName);
      sb.Append(": ");
      sb.Append(countEmailsReceived.Value.ToString());
      sb.Append("  [");
      sb.Append(percentTotalReceived);
      sb.AppendLine("% of total received]");

      result = sb.ToString();
   }

   return result;
}

Visual Basic

Private Function GetEmailStatistics(ByVal Item As Object) As String
   Dim result As String = String.Empty

   If TypeOf Item Is Outlook.MailItem Then
      Dim mailItem As Outlook.MailItem = CType(Item, Outlook.MailItem)
      Dim inboxTA As New ReportDBDataSetTableAdapters.InboxTableAdapter()
      Dim inbox As New ReportDBDataSet.InboxDataTable()
      Dim countEmailsReceived As Nullable(Of Integer) = _

         inboxTA.CountEmailsReceivedFrom(mailItem.SenderName)

      sb.Append("Emails received from ")
      sb.Append(mailItem.SenderName)
      sb.Append(": ")
      sb.Append(countEmailsReceived.Value.ToString())
      sb.Append("  [")
      sb.Append(percentTotalReceived)

      result = sb.ToString()
   End If

    Return result
End Function 'GetEmailStatistics

Almost there. Next we have to modify the Connect class to implement the form region interface.

Visual C#

public partial class Connect : Outlook.FormRegionStartup

Visual Basic

Partial Public Class Connect
   Implements Outlook.FormRegionStartup

The two methods defined in this interface are called as Outlook loads an item and prepares to show a form. When Outlook starts to load the user interface for a message class that has a form region registered, it first calls the GetFormRegionStorage method to load the layout information for the form region. GetFormRegionStorage should return either a string (which is the path to the .ofs file), an IStorage instance for the contents of the .ofs file, or a byte array that contains the contents of the .ofs file. Before Outlook displays the form region to the user, it calls the BeforeFormRegionShow method, and passes a reference to the form region object.

Visual C#

public object GetFormRegionStorage(string FormRegionName, object Item,
   int LCID, Outlook.OlFormRegionMode FormRegionMode,
   Outlook.OlFormRegionSize FormRegionSize)
{
   if (FormRegionName == "OutlookStatsRegionCS")
   {
      // Return the storage only when there are headers
      return Properties.Resources.OutlookStatsRegionCS;
   }

   return null;
}

public void BeforeFormRegionShow(Outlook.FormRegion FormRegion)
{
   if (FormRegion.InternalName == "OutlookStatsRegionCS")
   {
      OutlookStatsRegion newRegion = new OutlookStatsRegion(FormRegion);
      newRegion.Closed += new EventHandler(Region_Closed);

      _openRegions.Add(newRegion);
   }
}

Visual Basic

Public Sub BeforeFormRegionShow(ByVal FormRegion As Microsoft.Office.Interop.Outlook.FormRegion) Implements Microsoft.Office.Interop.Outlook._FormRegionStartup.BeforeFormRegionShow
   If FormRegion.InternalName = "OutlookStatsRegionVB" Then
      Dim newRegion As New OutlookStatsRegion(FormRegion)
      AddHandler newRegion.Closed, AddressOf Region_Closed

      _openRegions.Add(newRegion)

   End If
End Sub

Public Function GetFormRegionStorage(ByVal FormRegionName As String, _

   ByVal Item As Object, ByVal LCID As Integer, _

   ByVal FormRegionMode As Microsoft.Office.Interop.Outlook.OlFormRegionMode, _

   ByVal FormRegionSize As Microsoft.Office.Interop.Outlook.OlFormRegionSize) As Object Implements Microsoft.Office.Interop.Outlook._FormRegionStartup.GetFormRegionStorage

   If FormRegionName = "OutlookStatsRegionVB" Then
      Return My.Resources.OutlookStatsRegionVB
   End If

   Return Nothing
End Function

The last step is to register the add-in with Outlook. The add-in template provided with this article automatically generates a .reg file with the necessary settings to register the COM add-in created by the project with Outlook. Double click the .reg in Windows Explorer to register the add-in. Now you can change the debug properties of the project to start Outlook when debugging by setting the Start Action to Start External Program and then browse to the path of Outlook 2007.

Conclusion

As you can see, VSTO 2005 SE allows developers a powerful tool for customizing Office 2007. New features in VSTO 2005 SE such as the Ribbon bar and custom form regions allow for even better integration than previous versions of VSTO. Outlook events made it possible for us to calculate statistics about email and calendar usage. In addition to the reports included in this add-in there is room for future additions. Some possibilities are:

Adding a custom region on contacts to show amount of time spent in meetings with a particular person
Tracking the amount of time spent reading / composing emails
Tracking the amount spent on tasks or the percentage of tasks completed on time