Programming Microsoft Outlook and Microsoft Exchange 2003, Third Edition [Electronic resources] نسخه متنی

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.