Handbook for the Recently Present
One of the common calls I take in my job are from developers trying to write Instant Messaging and Presence (IM & P) providers to integrate with Office and Sharepoint. The number of cases I see are increasing so I wanted to start a series dedicated to that topic. The purposes of this series is to augment the documentation already out there and identify "gotchas" along the way. The first thing to know is the various terms I am going to use along the way. I will keep this page updated with the definitions that are added in later posts.
Provider Types
- OC20 - This is a provider that implements the IMessenger API. You must have Office 2007 or above. This is the deprecated API but Office 2010 and Office 2013 still support it.
- OCOM - This is a provider that implements the OCOM API. You must have Office 2010 or above to use this provider type.
- OCOM2 - This is a provider that implements the OCOM API. It's a superset of the OCOM API for Office 2010. You must have Office 2013 to use this provider type.
Initially, I am going to focus on the OCOM implementation. This is because this is the provider type that is going to be supported moving forward. I will write some articles about OC20 but not at first. With that said, let's get started. The first question I am going to answer is how do I get started?
How to get started
First, you need to decide in what language you are going to write your provider in. The Office implementation of the "client side" is implemented in COM and C/C++. Therefore, you need to decide if you want to write the provider in C/C++ or use .NET along with COM Interop. You cannot use Visual Basic 6.0 to build a provider. Trust me, I have tried. The problem with Visual Basic 6.0 is that it doesn't allow you specify UUID's for source interfaces. This results in failures when Office attempts to find the connection points for some source interfaces. For those not familiar with COM eventing this means that Office can't figure out how to listen to events raised by your provider. However, you can use Visual Basic.NET if you want. If you choose the C/C++ route the writing of the IDL will be a little more straight forward. However, if you choose .NET you will have to write the COM Interface definitions yourself.
Gross! I have to write my own interface definitions?!
Yep that's right. Remember, when you use this API you are mimicking the behavior of Office Communicator / Lync on the machine. However, Office Communicator / Lync will not be present. Therefore, you need to have a type library or Proxy / Stub Dll that will help COM marshal the objects from your provider to Office and back. If these are not present then Office will fail to interact with your provider. The type library that ships with Office Communicator / Lync cannot be redistributed with your solution. You must build you own and properly register it on the machine. For C/C++ solutions built using the Active Template Library (ATL) this is easy because the work is done for you. For .NET based solutions you must register the type library yourself.
How to troubleshoot my provider
If using Office 2007 and Office 2010 you can use the Presence Logs to figure out where Office is failing when interacting with your provider. You can turn on Presence Logging by creating the following registry key:
Hive: HKEY_CURRENT_USER
Key Name: Software\IM Providers
Value: OfficePresenceLogging
Data: 1 | 0 – 1 means enabled, 0 means disabled.
Make sure you create the directory %userprofile%\tracing before you attempt to start the Office application you are working in.
For Office 2013, this is a little more difficult. The logging mechanism was ported to use the built-in Event Tracing for Windows (ETW) architecture. Therefore you can no longer use this method in 2013. However, I am working on a way to enable this functionality. I will update this post when I have something for you.
Wow, how exciting! I want to start now, do I have to wait for you to finish this series?
No, you can read the documentation that was published on MSDN for a full high level overview. You can find the article here