Become a Columnist Microsoft Exchange Site Microsoft Support SiteMSDN Exchange Site



Example 2 using the Windows Messenger API     Download Examples

Windows Messenger provides a couple of API's that you can use to build RTC applications with a bit of a higher level of abstraction then using the RTC API. Currently their are two object libraries you can use with the Windows Messenger client. There is the "MessengerAPI"  library which is documented here and the "Messenger" library which is undocumented at the moment because of its use in the MSN Messenger client (It is unofficially documented on a lot of MSN user sites for more information have a look at msnfanatic and hypothetic ). For this article I've used a mixture of both the documented "MessengerAPI" and undocumented "Messenger" libraries as this lent to providing the easiest solution for sending a dynamic Instant Message.


There are two requirements you need to fulfil before you can use this code, firstly the machine you want to use this code on must have Windows Messenger Version 5.0 or higher installed. The other requirement is your client must already be configured to connect to your Live Communication Server and Live Communication Server should be set as the primary service on the client. The Windows Messenger Client supports connections to multiple service providers but for this code only one should be configured which is the SIP communication server. The easiest way to test that your client is configured properly is make sure you can logon to Windows messenger and LCS before you use this code. You can also check the setting of the following 2 registry keys.

"HKEY_CURRENT_USER\Software\Microsoft\MessengerService\UserMicrosoft RTC Instant Messaging" Reg_sz  (should be set to the SIP URI (sign-in name of the sending user)

"HKEY_CURRENT_USER\Software\Microsoft\MessengerService\PrimaryService"  Reg_SZ " "Microsoft RTC Instant Messaging"

How it works

For this sample I've created a simple VB6 project with one form the first thing we need however is to do some obligatory object declarations

Private WithEvents objmessenger As MessengerAPI.Messenger
Private WithEvents objImsg As Messenger.MsgrObject
Private contact As Messenger.IMsgrUser2

In the Form_Load Event there's some code that firstly creates 2 messenger objects this is because I want to use events out of both these objects. The next section checks to see if Messenger is currently signed in and if it isn't it calls the autosignin method. The autosignin method should use the currently logged on credentials to sign into the LCS server this will then trigger the signin event. If the user is already signed in it will call the sendimmsg function

Private Sub Form_Load()

Set objmessenger = New MessengerAPI.Messenger
Set objImsg = New Messenger.MsgrObject
    Call objmessenger.AutoSignin
    Call sendimmsg
End If
End Sub

The signin event simply calls the sendimsg function.

Private Sub objmessenger_OnSignin(ByVal hr As Long)
   Call sendimmsg
End Sub

The sendimsg function first retrieves the command-line parameters by using the command$ function that returns anything that was entered at the command line as a string. The next piece of code then looks at this string and finds the first space which should correspond to the end of the recipient address. The two mid statements then separate the string into a recipient address and then treats the rest of what was entered at the command line as the message to send. The next part of this sub then creates a user object using the messenger type library createuser method. Once the user has been created the sendtext method of the user object is used to send a message. The parameter I've used with the sendtext method listens for the result of the send which will then raises a onsendresult event.

Private Sub sendimmsg()
  Dim imheader As String
  Dim recipient1 As String
  Dim mess As String
  inpara = Command$
  recipient1 = Mid(inpara, 1, InStr(inpara, " "))
  mess = Mid(inpara, (InStr(inpara, " ") + 1), Len(inpara))
  imheader = "Mime-Version: 1.0" & vbCrLf & "Content-Type: text/plain; charset=UTF-8" & vbCrLf & vbCrLf
  Set contact = objImsg.CreateUser(recipient1, objImsg.Services.PrimaryService)
  send = contact.SendText(imheader, mess, 2)
End Sub

The onsendresult unloads the form which then raises the forms unload event, the unload event logs the messenger client out and cleans up the messenger objects.

Private Sub objImsg_OnSendResult(ByVal hr As Long, ByVal lCookie As Long)
    Unload Form1
End Sub
Private Sub Form_Unload(Cancel As Integer)
    Set objmessenger = Nothing
    Set objmessenger = Nothing
    Set contact = Nothing
End Sub

Using this example

This code is designed to be complied to an EXE and then run with two command line parameters, the first command line parameter is the SIP URI (or sign-in name) of the user you want to send a message to and the second parameter is the message you want to send. For example

myprog.exe This is a test message

Troubleshooting the Example

If you find this example is not working the best way to troubleshoot any problem is to enable client side logging this allows you to see everything from client initiation and authentication to the client conversation with the server. To enable client side logging on a PC  set the "HKEY_CURRENT_USER\Software\Microsoft\Tracing\RTCDLL\EnableFileTracing" registry key to 1 and then restart Windows messenger. A log file is then created in the users %USERPROFILE%\Tracing directory (unless you configure another location)

Download Examples

Disclaimer: Your use of the information contained in these pages is at your sole risk. All information on these pages is provided "as is", without any warranty, whether express or implied, of its accuracy, completeness, fitness for a particular purpose, title or non-infringement, and none of the third-party products or information mentioned in the work are authored, recommended, supported or guaranteed by Stephen Bryant or Pro Exchange. OutlookExchange.Com, Stephen Bryant and Pro Exchange shall not be liable for any damages you may sustain by using this information, whether direct, indirect, special, incidental or consequential, even if it has been advised of the possibility of such damages.

Copyright Stephen Bryant 2008