Office Communicator Automation API supports the following objects grouped by their functionality:

• Object that encapsulates Office Communicator 2007: The Messenger object represents a Communicator instance in an application. Using the interfaces implemented in this object, an application can manipulate a Communicator instance the same way an interactive user would. The supported features include signing in to Microsoft Office Communications Server 2007, managing and manipulating contacts, managing the presence states of the signed-in user, querying the presence of the user’s contacts, initiating instant messaging chats, and so on. This object implements the IMessenger3 interface and the DMessengerEvents dispinterface. The IMessenger3 interface inherits from the IMessenger2 interface, which, in turn, inherits from the IMessenger interface. The IMessenger* interfaces define the methods or properties that an application can call to manipulate Communicator. The DMessengerEvents dispinterface defines the events that can be raised by Communicator. The application can register some or all of the events if it is interested in being notified of the events.
  
  
• Objects for interacting with Communicator without invoking any user-interface elements. This includes the MessengerPriv object, which implements the IMessengerPrivate interface to enable applications to add contacts to a running Communicator instance without invoking the Contact Picker.
  
  

In COM, interfaces are the most important programming entities. An application often works explicitly with an interface pointer to call the methods and properties defined in the interface. Knowledge of interfaces helps an application developer use an API more productively.

In Office Communicator Automation API, the interfaces can be grouped according to the following categories:

• Communicator-related functionality: This group includes the IMessenger, IMessenger2, IMessenger3, IMessengerWindow, and IMessengerConversationWnd interfaces. An application can use these interfaces to manipulate a running Communicator programmatically. For example, to add contacts to Communicator, the application can call the IMessenger::AddContact method. To start dialing the work phone number of a contact of the local client, the application calls the IMessenger::Phone method. To initiate an instant messaging (IM) conversation with another contact, the application can invoke IMessenger::InstantMessage method. The application can also use these interfaces to provide a Communicator-compatible communications service. For example, a document management system can use these interfaces to provide presence status of members of a workgroup collaborating on a project. Two members can initiate an IM conversation without leaving the document management system. After the conversation, the system can call the API to retrieve the conversation texts from the Communicator and save it for later reference. For more information about conversation texts, see IMessengerConversationWnd::History.
  
  
• Contacts and groups managing functionality: This category includes the IMessengerContact, IMessengerContacts, IMessengerContactAdvanced, IMessengerGroup, and IMessengerGroups interfaces. An application uses these interfaces to work with a contact, a list of contacts, a group, or a list of groups.
  
  
• Communications service: This includes the IMessengerService and IMessengerServices interfaces. In Office Communicator Automation API, there is only one communications service; Microsoft Office Communications Server 2007 provides it. An application can use the IMessengerService interface to gain access to the communications service.
  
  
• Interaction with Communicator without any UI elements: This includes the IMessengerPrivate interface, which is used to add a contact without prompting the user with the Contact Picker of Communicator.
  
  

Events are basically callbacks that Communicator or Communications Server uses to inform an application of changes occurring on the server or in the Communicator instance. Some of the changes can be the result of method execution. If the application is interested in being notified of any events, it must implement the callbacks and register them appropriately.

For example, if your application is displaying a list of local client contacts, you will want to implement all of the contact-related callbacks. With these callback functions, you will be able to display contact status changes as they occur on the Office Communicator server. Method calls that add or remove contacts or groups do not return success values synchronously. You must rely on the asynchronous callback functions to determine the success or failure of a requested Office Communicator server action.

Enumerated types define constants used by the API, including error codes returned by the methods or properties of interfaces.

Error codes for those occurred while executing Communicator-related methods or properties are defined in Error Codes.

Error codes are HRESULT values. Applications written in C or C++ receive method call results as HRESULT values. Managed code languages such as C# and Visual Basic .NET do not have access to HRESULT values. Standard values include:

• 0x80004005 (E_FAIL or MSGR_E_FAIL)
  
  
• 0 (S_OK or MSGR_S_OK).
  
  

The API-specific ones fall into the following ranges:

• [0x81000301, 0x81000356]
  
  
• [0x01000301, 0x01000306]
  
  
• [0x81000601, 0x81000621]
  
  

For detailed information about each value and its meaning, see Error Codes.

If you are writing a manage code application in a .NET language such as C# or Visual Basic .NET, you need to catch COM exceptions if they are raised. The exception event raised contains an ErrorCode property that is an integer equivalent of the HRESULT error code value found in Error Codes.

The API DLL responsible for the Office Communicator automation is an ActiveX® (COM) object. As such, it raises a COM exception event when an error condition occurs. The COM exception is raised syncronously to the method call and must be handled. To avoid an inefficient use of system resources, it is better to prevent the conditions that give rise to an exception than to allow an exception handler catch the exception.

Communicator applications require that you installed Microsoft® Office Communicator 2007 on the same computer on which you build and run an application.

For unmanaged C/C++ applications, the following header files must be included in the application project:

• Msgrua.h
  
  
• Msgrpriv.h
  
  

Concepts