Sending a Instant Message Programmatically via Live Communication Server Download Examples

Instant Messaging (or Live Communication ) gives you the ability to perform things such as real-time alerting and real time announcements. In Exchange IM the SDK runtime components allowed you to build simple script based solutions to send an Instant message on demand, these components use the RVP protocol so they will no longer work with Live Communication Server which needs a client that supports the SIP protocol. With Live Communication Server their are currently 2 client API's you can use to connect to a LCS Server and send Instant messages. The first method is the RTC client API which is a couple of client side DLL's  that are documented in the RTC SDK, the second method you can use is the Windows Messenger API that can be used for clients who have Windows Messenger V.5 and above installed.  For this article I've used VB as both these API's don't lend themselves to being scripted easily using VBS. Both these examples are designed to be complied as a EXE file so you can run them via a script or a batch file using the recipient and the message you want to send as command line parameters.

Example 1 using the RTC API

Currently their are 3 different versions of the RTC API that range from Version 1 to version 1.2, To connect to and interact with a Live Communication Server you need to be using version1.2 (or above) you can download the SDK and client side DLL's you require from here.  If you're using the RTC API on a Window XP machine you need to be careful that you reference the right object library in VB by default Windows XP will have either version 1 or 1.1 installed by default. If you use the RTCAPISetup.exe from the SDK to install the RTC API dll's this will install the merge module on the computer so that the side-by-side RTC Client API 1.2 DLLs are available for use on that machine. This means that you will have 2 different versions of the rtcdll.dll on your machine if you use the default reference in your VB project (referring to the rtcdll.dll located in the windows\system32 directory)  you will be referring to the older version 1 or 1.1 dll and you will find the code will fail because certain methods are unavailable in this version of the API. The recommended method you should use if your building a RTC v 1.2 client application is to create an application manifest and deploy it with your application see this for more details (I've included a sample manifest file that Ive used form my apps I found this works fine on XP and 2000).  If you do need to reference this DLL in your project for testing you can browse to the RTCdll.dll in the %\windir%\winsxs\*rtc directory to create a reference. The sources I've used to create this example come from this download from a TechEd event in Holland and the RTC SDK.

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 objRTCClient As RTCCORELib.IRTCClient2
Private WithEvents objRTCClientWithEvents As RTCCORELib.RTCClient
Private objProvisioning As RTCCORELib.IRTCClientProvisioning2
Private objProfile As RTCCORELib.IRTCProfile2
Private objsession As RTCCORELib.IRTCSession2
Private objpartic As RTCCORELib.IRTCParticipant
Private inpara As String
Private mess As String

In the Form_Load event the code starts by initializing the client object and then setting up the RTC client object to catch the necessary events. The eventfilter is setup to catch all the RTC client events. The provisioning object is used to create a profile that will be used to connect  to the LCS server. With GetProfile you pass all the parameters necessary to connect to the server all these are optional except the SIP URI(Sign-in name) if you have setup your DNS records for in-Band provisioning (I've found it more reliable to supply them though). In this example I'm using TCP to connect to the LCS server.

Private Sub Form_Load()
Set objRTCClient = New RTCCORELib.RTCClient
objRTCClient.Initialize
objRTCClient.EventFilter = 33554431
Set objRTCClientWithEvents = objRTCClient
objRTCClient.ListenForIncomingSessions = RTCLM_DYNAMIC
Set objProvisioning = objRTCClient
Call objProvisioning.GetProfile("yourdomain\username", "password", "sip:user@yourdomain.com", "yourserver", 2, 0)
End Sub

Once the profile has been successfully created it will fire an event which will be caught by the event object objRTCClientWithEvents. A Case statement is used to determine what type of event it was that fired, in this example I'm only interested in profile and session events. If it was a profile event the profilevent sub routine is called.

Private Sub objRTCClientWithEvents_Event(ByVal RTCEvent As RTCCORELib.RTC_EVENT, ByVal pEvent As Object)
    Select Case RTCEvent
           Case RTCE_PROFILE
                 Call ProfileEvent(pEvent)
           Case RTCE_SESSION_OPERATION_COMPLETE
                 Unload Form1
    End Select
End Sub

The profileevent sub looks to see if it was a getprofile event and if it was it will then enable this profile and then call the sendmess sub routine to send a message.

Private Sub ProfileEvent(ByVal pEvent As RTCCORELib.IRTCProfileEvent2)
     Select Case pEvent.EventType
            Case RTCCORELib.RTCPFET_PROFILE_GET
              If pEvent.StatusCode = 0 Then
                 Set objProfile = pEvent.Profile
                 Call objProvisioning.EnableProfile(objProfile, 15)
                 Call sendmess
              End If
     End Select
End Sub

The Sendmess sub 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 the code creates a IM session with the desired recipient and uses the sendmessge method of the session object to send the Instant message text. Note no attempt is made to determine if the participant is online or not before sending the message its just sent regardless if the user is offline or blocking the sender then the send will fail. (The sender does not need to be on the allow list to send a user an Instant message but it must not be on the block list)

Private Sub sendmess()
 Dim header As String
 inpara = Command$
 recipient1 = Mid(inpara, 1, InStr(inpara, " "))
 mess = Mid(inpara, (InStr(inpara, " ") + 1), Len(inpara))
 Set objsession = objRTCClient.CreateSession(RTCCORELib.RTC_SESSION_TYPE.RTCST_IM, vbNullString, objProfile, 0)
 Set objpartic = objsession.AddParticipant(recipient1, recipient1)
 Call objsession.SendMessage(header, mess, 0)
End Sub

Once the Sendmess sub has run it will fire a session completion event, in the session completion event it  unloads the form which will run then fire the  form unload event which disables the profile and closes all the objects used in this code.

Private Sub Form_Unload(Cancel As Integer)
If objProfile Is Nothing Then
        Else
            If Not objProvisioning Is Nothing Then
                Call objProvisioning.DisableProfile(objProfile)
            End If
            Set objProfile = Nothing
            Set objPresence = Nothing
            Set objProvisioning = Nothing
        End If
 Call objRTCClient.PrepareForShutdown
 Call objRTCClient.Shutdown
 Set objsession = Nothing
 Set objpartic = Nothing
 Set objRTCClient = Nothing
 Set objRTCClientWithEvents = Nothing

End Sub

Compiling

Before you compile the code you need to first include you own variables in the Getprofile statement in the form load event you need to add your own username, password and server name. You also need to check you have referenced the RTCCore 1.2 library correctly in the project and make sure you setup a manifest file if you want to use it on other machines (see the discussion in the requirements section).

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 user@mydomain.com 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)

Next page using the windows messenger API Example 2

Download Examples