The Windows Messenger APIs

With the release of the Messenger APIs to the Microsoft Developer Network (MSDN), you can develop applications that leverage the capabilities of Windows Messenger. The Messenger APIs are similar to the Exchange IM control APIs. In fact, many of the events and methods have the same or similar names . The main difference between the Exchange IM and Messenger object models is that Exchange IM supports only the Rendezvous Protocol (RVP), while Messenger supports a number of protocols, including RVP and the Session Initiation Protocol (SIP). Also, Messenger does not ship a control with a user interface; you have to build your own interface for your Messenger applications.

To show you how to use the Messenger library, I built a simple ActiveX control that uses the library. This control can be hosted in the Training application instead of the Exchange IM control.

You start working with Messenger by using the Messenger API type library, which allows you to listen for events occurring within Messenger and also enumerate groups, contacts, and other Messenger lists. At the core of the Messenger object library is the Messenger.UIAutomation object. This is the object you must create to use the other objects in the object library. The following code from the custom control initializes a variable to this object and also sets up Visual Basic to listen for events from the object model:

 Dim WithEvents oMessenger As Messenger      Private Sub UserControl_Initialize()     'Initalize the treeview control and Messenger control     'See if the user is logged on     On Error GoTo errHandler     TreeViewContacts.ImageList = ImageListContacts     TreeViewContacts.Scroll = True     Set oMessenger = CreateObject("Messenger.UIAutomation.1")     If oMessenger.MyStatus = MISTATUS_OFFLINE _                            Or oMessenger.MyStatus = MISTATUS_UNKNOWN Then         Dim oNode As Node         Set oNode = TreeViewContacts.Nodes.Add(, 1, "NodeRoot", _                                                "Click here to logon", 3)         oNode.Bold = True         oNode.Selected = True         SetStatus oMessenger.MyStatus     Else         SetStatus oMessenger.MyStatus         'Parse through the groups and add info to the tree         DrawTree     End If          Exit Sub errHandler:     MsgBox "There was an error initializing the control.  Error# " _          & Err.Number & " Description: " & Err.Description     UserControl.Enabled = False End Sub 

Once you create this object, you can access some of the other objects, such as the Groups collection and its child object the Contacts collection. The following code taken from the control shows how to enumerate groups and contacts and display them. Notice that you can use for...each to loop through each collection.

 Sub DrawTree()     On Error Resume Next     'Clear the tree     TreeViewContacts.Nodes.Clear     'Scroll through all lists in Messenger and     'draw out the contacts on the list.     Dim oGroups As MessengerAPI.IMessengerGroups     Dim oGroup As MessengerAPI.IMessengerGroup     Set oGroups = oMessenger.MyGroups     For Each oGroup In oGroups         'Create a root node for each group         Set oTestNode = TreeViewContacts.Nodes.Add(, 1, oGroup.Name, _                                                    oGroup.Name, 6)         'Scroll through all contacts in the list and add them         Dim oContacts As MessengerAPI.IMessengerContacts         Set oContacts = oGroup.Contacts         Dim oContact As MessengerAPI.IMessengerContact         For Each oContact In oContacts             'Add the contact to the group             'Generate random number to add to key             'just in case more than one key exists already             Randomize             RndInt = Int((500 * Rnd) + 1)             TreeViewContacts.Nodes.Add oGroup.Name, 4, _                                  oContact.SigninName & " " _                                  & RndInt, oContact.FriendlyName, _                                  GetStatusImageIndex(CInt(oContact.Status))             oTestNode.Sorted = True         Next     Next End Sub 

The final interesting part of the Messenger API concerns events. Messenger fires events for groups being added or deleted through the user interface, contacts being added or deleted through the user interface, status changes, or even sign-in and sign-out actions. All the events are documented in the SDK. Here is some of the event code in the custom control:

 Private Sub SetStatus(iStatus As Integer)     Dim txtStatus As String     txtStatus = ""     Select Case iStatus         Case 1             txtStatus = "Offline"         Case 2             txtStatus = "Online"         Case 6             txtStatus = "Appear Offline"         Case 10             txtStatus = "Busy"         Case 14             txtStatus = "Be Right Back"         Case 18             txtStatus = "Away"         Case 34             txtStatus = "Away"         Case 50             txtStatus = "On the Phone"         Case 66             txtStatus = "Out to Lunch"     End Select     lblStatus.Caption = txtStatus End Sub      Private Sub oMessenger_OnMyStatusChange(ByVal hr As Long, _                                   ByVal mMyStatus As MessengerAPI.MISTATUS)     SetStatus CInt(mMyStatus) End Sub      Private Sub oMessenger_OnSignin(ByVal hr As Long)     On Error Resume Next     'Change the root node if successful     If hr = 0 Then         DrawTree     End If End Sub      Private Sub oMessenger_OnSignout()     On Error Resume Next     TreeViewContacts.Nodes.Clear     Set oNode = TreeViewContacts.Nodes.Add(, 1, "NodeRoot", _                                            "Click here to logon", 3)     oNode.Bold = True     oNode.Selected = True          'Change back the root node     TreeViewContacts.Nodes.Item("NodeRoot").Text = "Click here to logon" End Sub 

We've taken just a quick look at the Messenger object model. The object model also supports adding custom add-ins to Messenger and other functionality. Be sure to browse through the sample control included with the companion files and also browse through the Messenger SDK.