| |
A thread here at DevHood started back on Monday, June 10, 2002, about getting the status of users in your MSN / Windows Messenger ("Messenger" from now on) list and displaying it on your web site. If you take a quick peek, there were a lot of questions about such a feat. As I researched the problem, I thought this would warrant a tutorial since it's a great way to enhance your site with Messenger. This tutorial will help you understand a little about the Messenger API's and will help you put a Messenger Buddy List on your site. Once finished, you should be able to understand the API's and extend the features, such as putting images next to a pre-existing list of users, perhaps from a database, for those that have Messenger and associated Passports.
What You'll Need
Before we get started, you'll want to download one or two things. Even though the web page uses client-side scripting to display (or harness) a Messenger contact list - which requires the end-user to have Messenger - you'll want Messenger too in order to test it (if you don't already).
- If you're not using MSN Messenger (pre-Windows XP) or Windows Messenger (Windows XP), you're missing out. Packed with features and a low footprint on your system, you may download it at .
- You'll also benefit from the Messenger API documents (CHM - or Compiled HTML Help - files), which you can get from . If you have a newer version of Messenger, you already have the automation interfaces registered on your system.
Introduction to the Messenger API's
The Messenger API is a very rich API (unlike AOL IM, who won't let anyone touch their precious protocol), but can be a little confusing. There is an automation interface for controlling the user interface, an automation interface for writing plugins, and an automation interface for services extensions (like the Exchange service plugin for Messenger). The one we're interested in today is the user interface automation library.
If you're using VC++, you'll want to take a look at the MessengerUI.chm file, especially the documentation for VC++ describing all the interfaces and UUIDs. If you're a VB programmer or .NET developer, you'll want to take a look at the section for VB. It describes everything using objects, enumerations, and still gives you the juicy stuff.
Writing a Simple Macro with the Messenger API's
For a simple test, I added a reference to the "Messenger API Type Library" in Excel's VBA environment, and made this quick little macro:
Public Sub GetBuddies()
Dim msgr As New MessengerAPI.Messenger
Dim groups As IMessengerGroups
Dim group As IMessengerGroup
Dim contacts As IMessengerContacts
Dim contact As IMessengerContact
Dim I As Integer
Dim J As Integer
I = 1
J = 1
Set groups = msgr.MyGroups
For Each group In groups
Sheet1.Cells(I, 1) = group.Name
Set contacts = group.contacts
J = I + 1
For Each contact In contacts
Sheet1.Cells(J, 2) = contact.FriendlyName
Sheet1.Cells(J, 3) = contact.SigninName
Sheet1.Cells(J, 4) = GetStatus(contact.Status)
J = J + 1
Next
I = J
Next
End Sub
Public Function GetStatus(I As Integer) As String
Dim str As String
Select Case I
Case 1
str = "Offline"
Case 2
str = "Online"
Case 6
str = "Invisible"
Case 10
str = "Busy"
Case 14
str = "Be Right Back"
Case 18
str = "Idle"
Case 34
str = "Away"
Case 50
str = "On the Phone"
Case 66
str = "Out to Lunch"
Case Else
str = "Unknown"
End Select
GetStatus = str
End Function
|
With command-completion, this was a breeze. If you try taking the same approach with a scripting language like JScript (Microsoft's JavaScript) or VBScript, you'll find that it doesn't work. Even if you use "var msgr = new ActiveXObject(...)" for JScript or "Set msgr = CreateObject(...)" for VBScript, you'll get a scripting error from Internet Explorer (IE) that states it can't create the automation object.
So what gives? Beats me. I use the delightful and extremely helpful OLEView.exe utility that comes with every free and commercial development environment Microsoft distributes to look at all the automation interfaces, coclasses, and type library information and wound up just scratching my head. While Visual Basic can use the ProgID to create an instance of the coclass (class that implements the interface to which you think you're talking) and Visual C++ can use the CLSID, you can use neither in your scripting environment because the ProgIDs don't actually create objects in that instance. If you can figure this one out, by all means email me!
There is hope, however. If you dig around in Hotmail's source, you'll find a reference to a JavaScript file (.js) that contains all the goodies. Microsoft uses the infamous <object/> tag to instantiate the object.
Writing a Simple Script with the Messenger API's
So, lets create a simple HTML page with some basic functionality to display your name:
<html>
<head>
<title>Messenger Contact List</title>
<script language="jscript" event="onload" for="window">
if ("undefined" != typeof(msgrUI))
document.all.welcome.InnerText = msgrUI.MyFriendlyName
+ "'s Messenger Contacts";
</script>
</head>
<body background="white" text="black">
<p><b id="welcome">Messenger Buddies</b></p>
<p id="msgrList"><ol id="msgrBuds"/></p>
<object classid="clsid:B69003B3-C55E-4B48-836C-BC5946FC3B28"
id="msgrUI" width="1" height="1" style="display: none;"/>
</body>
</html>
|
When you open this page, you get a scripting error that "MyFriendlyName" isn't supported. You'll notice it's in the docs for the MessengerAPI.Messenger coclass that you instantiate (that's the CLSID for that ProgID in the <object/> tag). If you try the VC++ method of prepending "get_" to the property like "get_MyFriendlyName", you don't get an error but "undefined" is returned. In fact, as you'll find, "undefined" is returned for almost everything, including "MyContacts" and "MyGroups". Even though these properties are available in compiled languages such as VC++ and VB, they are not available in scripting languages. I'm sure this is by design, it's just not documented.
Don't give up hope, yet! Where there's a will, there's a way. Digging around in Hotmail's source a little more, I noticed a different set of CLSID's that they were using. Unfortunately, the one CLSID they were using was not documented in the CHM files I had you download, which was for the Messenger.MsgrObject ProgID. OLEView.exe showed me the light once again, however, and I ended up using the CLSID's for both the Messenger.MsgrObject and Messenger.UIAutomation objects, the latter of which implements all the things that Visual Basic could use so easily.
Writing a Advanced Script using the Messenger API's
We will finally create a page that works. We will use two objects, one of which is undocumented, but is described thoroughly by OLEView.exe if you understand IDL (the "COM language").
We can't rely on the Messenger.UIAutomation object since it apparently returns "undefined" when hosted in IE (or perhaps any scripting language). The other object (Messenger.MsgrObject) we will use does the trick, but it's by no means as elegant as Messenger.UIAutomation, which provides more functionality that actually does work in a scripting environment.
What follows is the final HTML for this tutorial, and I'll explain certain sections briefly below it:
<html>
<head>
<title>Messenger Contact List</title>
<script language="jscript">
</script>
<script language="jscript" event="onload" for="window">
</script>
</head>
<body background="white" text="black">
<p><b id="welcome">Messenger Contacts</b></p>
<p id="msgrList"><ol id="msgrBuds"></ol></p>
<object classid="clsid:F3A614DC-ABE0-11d2-A441-00C04F795683" id="msgr"
width="1" height="1" style="display: none;"/>
<object classid="clsid:B69003B3-C55E-4B48-836C-BC5946FC3B28"
id="msgrUI" width="1" height="1" style="display: none;"/>
</body>
</html>
|
As you can see, we now use two <object/> tags: "msgr" is the Messenger.MsgrObject object, and "msgrUI" is the Messenger.UIAutomation object. Remember, if you try to instantiate these using "new ActiveXObject()" or "CreateObject()", the automation interface won't be created. Also, don't try this server-side, it will just use your Messenger contact list - if it even works (the documentation warns against this, too).
You could add some browser detection code in there to keep Mozilla / Netscape from trying to do something it can't, but that should be taken care of by specifying the language as "JScript" instead of "JavaScript" (last time I checked, at least with 4.x).
The <script/> block that is attached to the "window.onload" event displays the list, or an error message depending on the state of you or your clients' Messenger. The regular <script/> block contains helper functions and event handlers used throughout the page.
In the "window.onload()" event handler, we use the "msgr" object and simply get your friendly name and the list of users. If you used "msgrUI", this wouldn't work since "undefined" would be return for each. We then iterate through the list of users and display HTML appropriate for each one. In that event handler - at the point we add HTML to output - we call another function, "setLink()". This method outputs an "a.onclick" event in the output HTML. When the user clicks the link for a name, it calls the "instantMessage()" function.
The "instantMessage()" function uses the other object, "msgrUI". It contains a method (which actually works) that displays the Instant Messaging (chat) window with the specified user as the recipient.
We also use the "AutoSignin()" method of the "msgrUI" object in the "signIn()" method we defined because it doesn't require user credentials (username and password). It tried to log in with the last-known credentials, just like Messenger does when it starts-up. The "msgr" object does have a "Login()" method, but it requires a username and password, which you must prompt for and handle on your own. There could also be security hazards depending on your environment as well. If the "msgrUI" object can't automatically signin, it will prompt for credentials on its own, which is probably a more secure method than JScript or VBScript could provide.
The rest of the code is pretty basic and self-explanitory, so I won't explain those.
Extending Functionality: What Else You can Do
This script just scratched the surface of what you can do. As you can see from Hotmail, they display an icon for each user that is in your list and that is online. If you wanted, you can create a bunch of icons (or tear them from the Messenger executable) to display next to users instead of their status as text, which is what I did in my latter sample. Just output "<img ...>" with the proper information instead of "Offline", "Online", etc.
If you're displaying a bunch of users with email addresses from a database already and you would like to add an icon next to each as described above, you could write a method that would search for the email address in the clients' contact list and then place an icon next to each, such as the following:
<script language="JScript" event="onload" for="window">
</script>
<table ...>
<tr>
<td id="">...</td>
</tr>
<tr>
<td id="">...</td>
</tr>
<tr>
<td id="">...</td>
</tr>
...
</table>
|
Explore the API and find out all the things you can do with Messenger to leverage greater functionality for your clients.
Summary
The Messenger API is an extensive API for of many objects, methods, properties, and events you can use in your compiled and interpreted applications. You have to treat them differently, however. Scripting languages don't work with the same ProgIDs that you may use in VC++, VB, or even .NET. With a little patience, OLEView.exe, and a little scripting experience, you can greatly enhance your site with Messenger!
|
|