Intégration des applications de messagerie instantanée à Office

Cet article montre comment configurer une application cliente de message instantanée (MI) afin qu'elle intègre des fonctionnalités sociales dans Office 2013, Office 2016, Office 2019 et Office 365, notamment l'affichage de présence et l'envoi de messages instantanés à partir d'une carte de visite.

Introduction

Office 2013 (et versions ultérieures) permet une intégration enrichie avec les applications clientes de messagerie instantanée, y compris Lync 2013 et Teams. Cette intégration permet aux utilisateurs de bénéficier des fonctionnalités de messagerie instantanée à partir de Word, Excel, PowerPoint, Outlook, Visio, Project et OneNote, ainsi que d’une intégration de la présence aux pages SharePoint. Les utilisateurs peuvent voir la photo, le nom, le statut de présence et les données de contact des personnes de leur liste de contacts. Ils peuvent démarrer une session de messagerie instantanée, un appel vidéo ou un appel téléphonique directement à partir de la carte de visite (élément d’interface utilisateur dans Office qui affiche les informations de contact et les options de communication). Office vous permet de rester en contact avec vos contacts sans vous sortir de votre e-mail ou de vos documents.

Vous pouvez personnaliser une application cliente de messagerie instantanée afin qu'elle communique avec Office. Vous pouvez notamment modifier votre application de messagerie instantanée pour qu'elle affiche les informations suivantes dans l'interface utilisateur d'Office :

• Photo du contact

• Nom du contact

• Note de statut personnel du contact

• Statut de la présence du contact

• Chaîne de disponibilité du contact (par exemple, « Disponible » ou « Absent(e) du bureau »)

• Chaîne de niveau d’aptitude du contact (par exemple, « Prêt pour la vidéo »)

• Lancement de messagerie instantanée en un clic

• Lancement d’un appel vidéo en un clic

• Lancement d’appel téléphonique en un clic (avec les fonctionnalités SIP, numéro de téléphone, messagerie vocale et appel de nouveau numéro).

• Gestion du contact (ajouter au groupe de messagerie instantanée)

• Emplacement et fuseau horaire du contact

• Données du contact, numéro de téléphone, adresse de messagerie, poste et nom de sa société

Figure 1. Carte de visite dans Office 2013

Pour permettre cette intégration dans Office, l'application cliente de messagerie instantanée doit implémenter un ensemble d'interfaces fournies par Office pour établir une connexion. Les API nécessaires à cette intégration sont incluses dans l'espace de noms UCCollborationLib figurant dans le fichier Microsoft.Office.UC.dll installé avec les versions de Office 2013, comprenant Lync et Skype Entreprise. L'espace de noms UCCollaborationLib inclut les interfaces que vous devez implémenter pour intégrer Office.

Intégration d’Office à une application cliente de messagerie instantanée

Quand une application Office 2013 (ou version ultérieure) démarre, elle suit le processus suivant pour s'intégrer à l'application cliente de messagerie instantanée par défaut :

1. Elle vérifie le Registre pour identifier l’application cliente de messagerie instantanée par défaut et se connecte ensuite à celle-ci.

2. Elle s’authentifie avec l’application cliente de messagerie instantanée.

3. Elle se connecte à des interfaces spécifiques qui sont exposées par l’application cliente de messagerie instantanée.

4. Elle détermine les fonctionnalités de l’utilisateur connecté (utilisateur local), notamment l’obtention des contacts de l’utilisateur, détermine la présence de l’utilisateur et ses fonctionnalités de messagerie instantanée (messagerie instantanée, conversation vidéo, appels VoIP etc.).

5. Elle obtient les informations de présence des contacts de l’utilisateur local.

6. Lorsque l'application cliente de messagerie instantanée s'arrête, l'application Office se déconnecte sans assistance.

Détection de l’application de messagerie instantanée

L'application Office recherche plusieurs clés et entrées spécifiques dans le Registre pour détecter l'application cliente de messagerie instantanée par défaut. Si elle détecte une application cliente de messagerie instantanée par défaut, elle tente de s'y connecter.

L'application Office suit le processus suivant pour découvrir l'application cliente de messagerie instantanée par défaut :

1. L’application Office vérifie si la sous-clé HKEY_CURRENT_USER\Software\IM Providers\DefaultIMApp du Registre est définie et lit le nom de l’application mentionnée.

2. Ensuite, l'application Office lit la clé HKEY_CURRENT_USER\Software\IM Providers\ Application name\UpAndRunning et suit les modifications de sa valeur.

3. Puis elle lit la clé de Registre HKEY_LOCAL_MACHINE\Software\IM Providers\ Application name et obtient les valeurs du ProcessName et de l'ID de classe (CLSID) stockées à cet emplacement.

4. Lorsque l'application cliente de messagerie instantanée a réussi sa séquence de démarrage et a enregistré toutes les classes correctement pour l'intégration de présence, elle définit la clé HKEY_CURRENT_USER\Software\IM Providers\ Application name\UpAndRunning sur « 2 », ce qui indique que l'application cliente est en cours d'exécution.

5. Lorsque l'application Office détecte que la clé HKEY_CURRENT_USER\Software\IM Providers\ Application name\UpAndRunning a la valeur « 2 », elle recherche le nom du processus de l'application cliente de messagerie instantanée dans la liste des processus en cours d'exécution sur l'ordinateur.

6. Lorsque l'application Office trouve le processus qui utilise l'application cliente de messagerie instantanée, elle appelle CoCreateInstance à l'aide du CLSID pour établir une connexion à l'application cliente de messagerie instantanée sous la forme d'un serveur COM hors processus.

Authentification de la connexion à l’application de messagerie instantanée

Lorsque l’application Office établit une connexion à l’application cliente de messagerie instantanée, elle effectue ensuite les opérations suivantes :

1. Elle appelle la méthode IUnknown::QueryInterface pour vérifier l'interface IUCOfficeIntegration.

2. Puis elle appelle la méthode IUCOfficeIntegration.GetAuthenticationInfo, en transmettant la version d'intégration prise en charge la plus récente (par exemple, « 15.0.0.0 »).

3. Si l’application cliente de messagerie instantanée prend en charge la version d’Office transmise en tant que paramètre, l’application renvoie la chaîne XML codée en dur suivante vers le code appelant :

   <authenticationinfo>

   Remarque

   Pour des raisons d'héritage, si l'application cliente de messagerie instantanée prend en charge la version d'Office transmise en tant que paramètre, elle doit renvoyer la valeur <authenticationinfo> exacte vers l'appel à destination de GetAuthenticationInfo.

4. Si l'application cliente de messagerie instantanée ne parvient pas à renvoyer une valeur, l'application Office appelle la méthode GetAuthenticationInfo à l'aide de la version d'Office prise en charge précédant la version la plus récente (par exemple, « 14.0.0.0 »).

5. Lorsqu'Office détermine que l'application cliente de messagerie instantanée prend en charge l'intégration de la messagerie instantanée et de la présence, il se connecte à un ensemble d'interfaces pour terminer l'initialisation. Pour plus d'informations, voir Connexion aux interfaces requises.

Si l’application Office rencontre une erreur lors d’une des étapes précédentes, elle reprend le processus et l’intégration de la présence n’est pas rétablie pendant la session de l’application Office.

Connexion aux interfaces requises

Après avoir authentifié la connexion à l'application cliente de messagerie instantanée, l'application Office essaie de se connecter à un ensemble d'interfaces requises que l'application cliente de messagerie instantanée doit exposer. L'application Office effectue cela en procédant comme suit :

• L'application Office obtient un objet ILyncClient en appelant la méthode IUCOfficeIntegration.GetInterface, en transférant la constante oiInterfaceLyncClient à partir de l'énumération UCCollaborationLib.OIInterface.

• L'application Office obtient un objet IAutomation en appelant la méthode IUCOfficeIntegration.GetInterface, en transmettant la constante oiInterfaceAutomation à partir de l'énumération OIInterface.

• L'application Office configure le détecteur d'événements _ILyncClientEvents.

• L'application Office configure le détecteur d'événements _IUCOfficeIntegrationEvents.

• L'application Office obtient l'état de connexion à partir de l'application cliente de messagerie instantanée en accédant à la propriété ILyncClient.State.

• L'application Office obtient les fonctionnalités de l'application cliente de messagerie instantanée en appelant la méthode IUCOfficeIntegration.GetSupportedFeatures, qui renvoie un indicateur de l'énumération UCCollaborationLib.OIFeature.

• L'application Office accède à la propriété ILyncClient.Self pour obtenir une référence à un objet ISelf.

Récupération des fonctionnalités de l’utilisateur local

L’application Office procède comme suit pour obtenir les fonctionnalités de l’utilisateur local :

1. Si l'application cliente de messagerie instantanée prend en charge l'interface IClient2, Office tente d'obtenir un objet IContactManager en accédant à la propriété IClient2.PrivateContactManager.

2. Si l'application de messagerie instantanée ne prend pas en charge l'interface IClient2, l'application Office obtient un objet IContactManager en accédant à la propriété ILyncClient.ContactManager. L'application cliente de messagerie instantanée doit renvoyer un objet IContactManager avant de pouvoir établir d'autres fonctionnalités de messagerie instantanée.

3. L'application Office accède à la propriété ILyncClient.Uri, puis appelle IContactManager.GetContactByUri pour obtenir l'objet IContact associé à l'utilisateur local.

4. L'application effectue plusieurs appels vers IContact.CanStart pour établir les fonctionnalités de l'utilisateur local, en transmettant successivement les valeurs de ModalityTypes.ucModalityInstantMessage et ModalityTypes.ucModalityAudioVideo.

Récupération de la présence du contact

L’application Office procède comme suit pour obtenir la présence du contact, notamment de l’utilisateur local :

1. L'application Office appelle IContact.GetContactInformation pour obtenir un élément de la présence du contact.

2. Puis elle s'abonne aux modifications de statut de présence du contact. Elle appelle IContactManager.CreateSubscription pour obtenir un objet IContactSubscription. Elle appelle ensuite IContactSubscription.AddContact pour ajouter le contact à l'abonnement, puis appelle IContactSubscription.Subscribe pour obtenir les modifications de statut du contact.

3. Si l'application de messagerie instantanée prend en charge IContact2, Office tente d'obtenir les informations de présence en appelant IContact2.BatchGetContactInformation2.

4. Puis elle récupère les propriétés de présence du contact en appelant IContact.BatchGetContactInformation. L'application Office peut obtenir un second jeu de propriétés de présence en accédant à la propriété IContact.Settings.

5. Enfin, l'application Office obtient l'appartenance de groupe du contact en accédant à la propriété IContact.CustomGroups. Ceci renvoie une collection IGroupCollection qui contient tous les objets IGroup auxquels appartient le contact.

Déconnexion de l’application de messagerie instantanée

Lorsque l’application Office détecte l’événement OnShuttingDown à partir de l’application de messagerie instantanée, elle se déconnecte sans assistance. Toutefois, si l’application Office s’arrête avant l’application de messagerie instantanée, l’application Office n’assure pas le nettoyage de la connexion. L’application de messagerie instantanée doit gérer les fuites de connexion du client.

Configuration des clés et des entrées de Registre

Comme indiqué précédemment, les applications Office compatibles avec la messagerie instantanée recherchent des clés, des entrées et des valeurs spécifiques dans le Registre pour découvrir l’application cliente de messagerie instantanée à laquelle se connecter. Ces valeurs de Registre fournissent à l'application Office le nom du processus et le GUID de la classe qui sert de point d'entrée au modèle d'objet de l'application cliente de messagerie instantanée (autrement dit, la classe qui implémente l'interface IUCOfficeIntegration). L’application Office co-crée cette catégorie et se connecte en tant que client au serveur COM hors processus dans l’application cliente de messagerie instantanée.

Utilisez le tableau 1 pour identifier les clés, les entrées et les valeurs qui doivent être écrites dans le Registre pour intégrer une application cliente de messagerie instantanée à Office.

Tableau 1. Clés de Registre pour la configuration de l’application cliente de messagerie instantanée par défaut

Clé	Entrée	Type	Valeur	Exemple
HKEY_LOCAL_MACHINE\Software\IM Providers\Nom de <l’application>	FriendlyName	REG_SZ	Nom de l’application cliente de messagerie instantanée tierce.	Litware IM 2012
	ProcessName	REG_SZ	Nom du processus de l’application cliente de messagerie instantanée tierce.	litware.exe
	GUID	REG_SZ	ID de classe (CLSID) pour la classe racine pouvant être co-créée dans l'application de messagerie instantanée (il s'agit de la classe qui implémente l'interface IUCOfficeIntegration).	Un GUID
HKEY_CURRENT_USER\Software\IM Providers	DefaultIMApp	REG_SZ	Nom de l'application cliente de messagerie instantanée. Il doit s'agir du même nom que celui de la clé de Registre de niveau supérieur (ruche) HKEY_LOCAL_MACHINE.	Litware
HKEY_CURRENT_USER\Software\IM Providers\Nom de <l’application>	UpAndRunning	REG_DWORD	Nombre entier compris entre 0 et 2. 0 : n’est pas en cours d’exécution 1 : en cours de démarrage 2 : en cours d’exécution REMARQUE : la clé de Registre du nom de l’application doit être identique à la valeur de l’entrée DefaultIMApp.

Implémentation des interfaces requises pour l’intégration avec Office

Le fichier exécutable (ou le serveur COM) d'une application cliente de messagerie instantanée doit implémenter trois interfaces à partir de l'espace de noms UCCollaborationLib pour pouvoir s'intégrer à Office. Dans le cas contraire, l'application Office reprend le processus durant l'initialisation et la connexion avec l'application cliente de messagerie instantanée n'est pas établie.

Les interfaces suivantes sont requises :

• IUCOfficeIntegration : même si elle n'est pas obligatoire, l'interface _IUCOfficeIntegrationEvents doit également être implémentée dans la même classe dérivée.

• ILyncClient : même si elle n'est pas obligatoire, l'interface _ILyncClientEvents doit également être implémentée dans la même classe dérivée.

• IAutomation

Interface IUCOfficeIntegration

L'interface IUCOfficeIntegration fournit le point d'entrée permettant à une application Office de se connecter à l'application cliente de messagerie instantanée. L'interface définit trois méthodes qu'une application Office appelle dans le cadre du processus d'initialisation d'une connexion avec l'application cliente de messagerie instantanée. La classe qui implémente l'interface IUCOfficeIntegration doit pouvoir être co-créée pour qu'Office puisse co-créer une instance de celle-ci. En outre, il doit exposer le CLSID entré comme valeur pour l’entrée GUID dans la clé de Registre nom de l’application HKEY_LOCAL_MACHINE\Software\IM Providers\.

La classe qui hérite de IUCOfficeIntegration doit également implémenter l'interface _IUCOfficeIntegrationEvents. L'interface _IUCOfficeIntegrationEvents contient les membres qui exposent les gestionnaires d'événements de l'interface IUCOfficeIntegration.

Le tableau 2 indique les membres qui doivent implémentés dans la classe qui hérite de IUCOfficeIntegration et _IUCOfficeIntegration.

Tableau 2. Implémentation des interfaces IUCOfficeIntegration et _IUCOfficeIntegrationEvents

Interface	Membre	Description
IUCOfficeIntegration	Méthode GetAuthenticationInfo	Obtient la chaîne d’informations d’authentification.
	Méthode GetInterface	Obtient l’interface d’une version spécifique.
	Méthode GetSupportedFeatures	Obtient les fonctionnalités d’intégration Office prises en charge.
_IUCOfficeIntegrationEvents	Événement OnShuttingDown	Événement déclenché lorsque l’application cliente de messagerie instantanée est arrêtée.

Utilisez le code suivant pour définir une classe qui hérite des interfaces IUCOfficeIntegration et _IUCOfficeIntegration au sein d'une application cliente de messagerie instantanée.

// An example of a class that can be co-created and can integrate
// with Office as an IM provider.
[ClassInterface(ClassInterfaceType.None)]
[ComSourceInterfaces(typeof(_IUCOfficeIntegrationEvents))]
[Guid("{CLSID value}"), ComVisible(true)]
public class LitwareClientAppObject : IUCOfficeIntegration
{
    // Implementation details omitted.
}

La méthode GetAuthenticationInfo prend une chaîne comme argument pour le paramètre version . Lorsque l’application Office appelle cette méthode, elle transfert l’une des deux chaînes comme argument, en fonction de la version d’Office. Lorsque l'application Office fournit la méthode avec la version d'Office prise en charge par l'application cliente de messagerie instantanée (autrement dit, qui prend en charge la fonctionnalité), la méthode GetAuthenticationInfo renvoie une chaîne XML <authenticationinfo> codée en dur.

Utilisez le code suivant pour implémenter la méthode GetAuthentication dans le code d’application cliente de messagerie instantanée.

public string GetAuthenticationInfo(string _version)
{
    // Define the version of Office that the IM client application supports.
    string supportedOfficeVersion = "15.0.0.0";
    // Do a simple check for equivalency.
    if (supportedOfficeVersion == _version)
    {
        // If the version of Office is supported, this method must 
        // return the string literal "<authenticationinfo>" exactly.
        return "<authenticationinfo>";
    }
    else
    {
        return null;
    }
}

La méthode GetInterface navette les références aux classes vers le code appelant, en fonction de ce qui est passé en tant qu’argument pour le paramètre d’interface . Lorsqu'une application Office appelle la méthode GetInterface, elle transfert une des deux valeurs pour le paramètre de l'interface : soit la constante oiInterfaceILyncClient (1) ou la constante oiInterfaceIAutomation (2) de l'énumération UCCollaborationLib.OIInterface. Si l'application Office transfère la constante oiInterfaceILyncClient, la méthode GetInterface renvoie une référence à une classe qui implémente l'interface ILyncClient. Si l'application Office transfère la constante oiInterfaceIAutomation, la méthode GetInterface renvoie une classe qui implémente l'interface IAutomation.

Utilisez le code suivant pour implémenter la méthode GetInterface dans le code de l'application cliente de messagerie instantanée.

public object GetInterface(string _version, OIInterface _interface)
{
    // These objects implement the ILyncClient or IAutomation 
    // interfaces respectively. There is no restriction on what these
    // classes are named.
    IMClient imClient = new IMClient();
    IMClientAutomation imAutomation = new IMClientAutomation();
    // Return different object references depending on the value passed in
    // for the _interface parameter.
    switch (_interface)
    {
        // The calling code is asking for an object that inherits
        // from ILyncClient, so it returns such an object.
        case OIInterface.oiInterfaceILyncClient:
        {
            return imClient;
        }
        // The calling code is asking for an object that inherits
        // from IAutomation, so it returns such an object.
        case OIInterface.oiInterfaceIAutomation:
        {
            return imAutomation;
        }
        default:
        {
            throw new NotImplementedException();
        }
    }
}

La méthode GetSupportedFeatures renvoie des informations sur les fonctionnalités de messagerie instantanée prises en charge par l'application cliente de messagerie instantanée. Il prend une chaîne pour son seul paramètre, version. Lorsque l’application Office appelle la méthode GetSupportedFeatures, celle-ci renvoie une valeur à partir de l’énumération UCCollaborationLib.OIFeature. La valeur renvoyée définit les fonctionnalités du client de messagerie instantanée, où chaque fonctionnalité de l’application cliente de messagerie instantanée est indiquée à l’application Office par l’ajout d’un indicateur à la valeur.

Utilisez le code suivant pour implémenter la méthode GetSupportFeatures dans le code de l’application cliente de messagerie instantanée.

public OIFeature GetSupportedFeatures(string _version)
{
    OIFeature supportedFeature1 = OIFeature.oiFeatureQuickContacts;
    OIFeature supportedFeature2 = OIFeature.oiFeatureFastSearch;
    return (supportedFeature1 | supportedFeature2);
}

Interface ILyncClient

L'interface ILyncClient mappe vers les fonctionnalités de l'application cliente de messagerie instantanée. Elle expose les propriétés qui font référence à la personne connectée à l'application (l'utilisateur local, représenté par l'interface UCCollaborationLib.ISelf), l'état de l'application, la liste des contacts de l'utilisateur local, ainsi que d'autres paramètres. Lorsqu'elle tente de se connecter à l'application cliente de messagerie instantanée, l'application Office obtient une référence à un objet qui implémente l'interface ILyncClient. À partir de cette référence, Office peut accéder à la plupart des fonctionnalités de l'application cliente de messagerie instantanée.

En outre, la classe qui implémente l'interface ILyncClient doit également implémenter l'interface _ILyncClientEvents. L'interface _ILyncClientEvents expose plusieurs événements requis pour surveiller l'état de l'application cliente de messagerie instantanée.

Le tableau 3 affiche les membres qui doivent être implémentés dans la classe qui hérite de ILyncClient et _ILyncClientEvents.

Tableau 3. Implémentation des interfaces ILyncClient et ILyncClientEvents

Interface	Membre	Description
ILyncClient	Propriété ContactManager	Obtient le Gestionnaire de groupe de contacts.
	Propriété ConversationManager	Obtient le Gestionnaire de conversations.
	Propriété Self	Obtient l'objet Self.
	Méthode SignIn	Démarre le processus de connexion de l’application cliente de messagerie instantanée avec une disponibilité spécifique.
	Propriété State	Obtient l’état actuel de la plateforme.
	Propriété Uri	Obtient l’URI de l’application cliente de messagerie instantanée.
_ILyncClientEvents	Événement OnStateChanged	Déclenché lorsque l'état de l'application cliente de messagerie instantanée est modifié. Vous devez gérer cet événement et obtenir la propriété eventData.NewState. L'événement est déclenché pour tous les processus liés à l'instance d'une application cliente de messagerie instantanée lorsqu'un sous-système de l'application entraîne la modification de l'état.

Pendant le processus d'initialisation, Office accède à la propriété ILyncClient.State. Cette propriété doit renvoyer une valeur à partir de l'énumération UCCollaborationLib.ClientState.

private ClientState _clientState;
public ClientState State
{
    get
    {
        return this._clientState;
    }
}

La propriété State stocke l'état actuel de l'application cliente de messagerie instantanée. Elle doit être définie et mise à jour dans l'ensemble de la session d'application cliente de messagerie instantanée. Lorsque l'application cliente de messagerie instantanée se connecte, se déconnecte ou s'arrête, elle doit définir la propriété State. Il est préférable de définir cette propriété dans les méthodes ILyncClient.SignIn et ILyncClient.SignOut, comme l'indique l'exemple suivant.

// This field is of a type that implements the 
// IAsynchronousOperation interface.
private IMClientAsyncOperation _asyncOperation = new IMClientAsyncOperation();
// This field is of a type that implements the ISelf interface.
private IMClientSelf _self;
public IMClientAsyncOperation SignIn(string _userUri, string _domainAndUser, 
    string _password, object _IMClientCallback, object _state)
{
    ClientState _previousClientState = this._clientState;
    this._clientState = ClientState.ucClientStateSignedIn;
    // The IMClientStateChangedEventData class implements the 
    // IClientStateChangedEventData interface.
    IMClientStateChangedEventData eventData = 
        new IMClientStateChangedEventData(_previousClientState, 
        this._clientState);
    if (_userUri != null)
    {
        // During the sign-in process, create a new contact with
        // the contact information of the currently signed-in user.
        this._self = new IMClientSelf(IMContact.BuildContact(_userUri));
    }
    // Raise the _ILyncClientEvents.OnStateChanged event.
    OnStateChanged(this, eventData as UC.ClientStateChangedEventData);
    
    return this._asyncOperation;
    }
}

L’exemple de code suivant montre comment configurer l’écouteur d’événements à l’aide des interfaces ILyncClientEvents etIUCOfficeIntegrationEvents .

using Microsoft.Office.Uc;
using System;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
namespace SampleImplementation
{
    // Note: UCOfficeIntegration inherits from both IUCOfficeIntegration and _IUCOfficeIntegrationEvents_Event
    [ClassInterface(ClassInterfaceType.None), Guid("13c41ef9-eb90-4e94-8a7c-1e9d686bc019"), ComVisible(true)]
    [ComSourceInterfaces(typeof(_IUCOfficeIntegrationEvents))]
    public class MyInstantMessengerOfficeIntegration : UCOfficeIntegration
    {
        #region IUCOfficeIntegration implementation
        public string GetAuthenticationInfo(string _version)
        {
            return "";
        }
        public object GetInterface(string _version, OIInterface _interface)
        {
            return null;
        }
        public OIFeature GetSupportedFeatures(string _version)
        {
            return OIFeature.oiFeatureAddOneNoteToConversation;
        }
        #endregion
        #region _IUCOfficeIntegrationEvents support
        // This event implements void _IUCOfficeIntegrationEvents.OnShuttingDown();
        public event _IUCOfficeIntegrationEvents_OnShuttingDownEventHandler OnShuttingDown;
        // This method is called by the IM application when it is beginning to shut down.
        // The method will raise the OnShuttingDown event which is translated by .NET COM interop layer
        // into a call to _IUCOfficeIntegrationEvents.OnShuttingDown.
        // This notifies Office applications that the IM application is going away.
        internal void RaiseOnShuttingDownEvent()
        {
            if (this.OnShuttingDown != null)
            {
                this.OnShuttingDown();
            }
        }
        #endregion
    }
    // Note: LyncClient inherits from both ILyncClient and _ILyncClientEvents_Event
    // You must implement LyncClient because the event handlers in _ILyncClientEvents expect you to pass a LyncClient interface.
    [ComVisible(true)]
    [ComSourceInterfaces(typeof(_ILyncClientEvents))]
    public class MyInstantMessengerOfficeIntegration2 :
        Client,
        Client2,
        LyncClient
    {
        #region Interfaces
        public LyncClientCapabilityTypes Capabilities
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public ConferenceScheduler ConferenceScheduler
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public ContactManager ContactManager
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public ConversationManager ConversationManager
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public DelegatorClient[] DelegatorClients
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public DeviceManager DeviceManager
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public bool InSuppressedMode
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public ContactManager PrivateContactManager
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public RoomManager RoomManager
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public Self Self
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public ClientSettings Settings
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public SignInConfiguration SignInConfiguration
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public ClientState State
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public ClientType Type
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public string Uri
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public Utilities Utilities
        {
            get
            {
                throw new NotImplementedException();
            }
        }
        public ApplicationRegistration CreateApplicationRegistration(string _appGuid, string _appName)
        {
            throw new NotImplementedException();
        }
        public AsynchronousOperation Initialize(string _clientName, string _version = "0", string _clientShortName = "0", string _clientNameAbbreviation = "0", string _clientLongName = "0", SupportedFeatures _supportedFeatures = SupportedFeatures.ucAllFeatures, [IUnknownConstant] object _CommunicatorClientCallback = null, object _state = null)
        {
            throw new NotImplementedException();
        }
        public AsynchronousOperation Shutdown([IUnknownConstant] object _CommunicatorClientCallback, object _state)
        {
            throw new NotImplementedException();
        }
        public AsynchronousOperation SignIn(string _userUri = "0", string _domainAndUsername = "0", string _password = "0", [IUnknownConstant] object _CommunicatorClientCallback = null, object _state = null)
        {
            throw new NotImplementedException();
        }
        public AsynchronousOperation SignOut([IUnknownConstant] object _CommunicatorClientCallback, object _state)
        {
            throw new NotImplementedException();
        }
        #endregion
        #region _ILyncClientEvents support
        public event _ILyncClientEvents_OnStateChangedEventHandler OnStateChanged;
        public event _ILyncClientEvents_OnNotificationReceivedEventHandler OnNotificationReceived;
        public event _ILyncClientEvents_OnCredentialRequestedEventHandler OnCredentialRequested;
        public event _ILyncClientEvents_OnSignInDelayedEventHandler OnSignInDelayed;
        public event _ILyncClientEvents_OnCapabilitiesChangedEventHandler OnCapabilitiesChanged;
        public event _ILyncClientEvents_OnDelegatorClientAddedEventHandler OnDelegatorClientAdded;
        public event _ILyncClientEvents_OnDelegatorClientRemovedEventHandler OnDelegatorClientRemoved;
        // Notifies Office apps that the IM client state (signed out, signing in, singed in, signing out, etc) has changed.
        internal void RaiseOnStateChangedEvent(ClientStateChangedEventData eventData)
        {
            if (this.OnStateChanged != null)
            {
                this.OnStateChanged(this, eventData);
            }
        }
        // Notifies Office apps that the IM client has received a notification event from MAPI (e.g. autodiscover has finished)
        internal void RaiseOnNotificationReceivedEvent(LyncClientNotificationReceivedEventData eventData)
        {
            if (this.OnNotificationReceived != null)
            {
                this.OnNotificationReceived(this, eventData);
            }
        }
        // Notifies Office apps that the IM client has received a request for credentials for some operation (e.g. sign in, web search)
        internal void RaiseOnCredentialRequestedEvent(CredentialRequestedEventData eventData)
        {
            if (this.OnCredentialRequested != null)
            {
                this.OnCredentialRequested(this, eventData);
            }
        }
        // Notifies Office apps that the IM client has been delayed from signing in and gives an estimated delay time.
        internal void RaiseOnSignInDelayedEvent(SignInDelayedEventData eventData)
        {
            if (this.OnSignInDelayed != null)
            {
                this.OnSignInDelayed(this, eventData);
            }
        }
        // Notifies Office apps that the capabilities of this IM client have changed.
        internal void RaiseOnCapabilitiesChangedEvent(PreferredCapabilitiesChangedEventData eventData)
        {
            if (this.OnCapabilitiesChanged != null)
            {
                this.OnCapabilitiesChanged(this, eventData);
            }
        }
        // Notifies Office apps that a DelegatorClient object has been added to the IM client object.
        internal void RaiseOnDelegatorClientAdded(DelegatorClientCollectionEventData eventData)
        {
            if (this.OnDelegatorClientAdded != null)
            {
                this.OnDelegatorClientAdded(this, eventData);
            }
        }
        // Notifies Office apps that a DelegatorClient object has been removed from the IM client object.
        internal void RaiseOnDelegatorClientRemoved(DelegatorClientCollectionEventData eventData)
        {
            if (this.OnDelegatorClientRemoved != null)
            {
                this.OnDelegatorClientRemoved(this, eventData);
            }
        }
        #endregion
    }
}

Interface IAutomation

L'interface IAutomation automatise les fonctionnalités de l'application cliente de messagerie instantanée. Elle peut être utilisée pour démarrer une conversation, participer à des conférences et fournir un contexte de fenêtre d'extensibilité.

Le tableau 4 indique les membres qui doivent être implémentés dans la classe qui hérite de IAutomation.

Tableau 4. Implémentation de l’interface IAutomation

Membre	Description
Méthode StartConversation	Démarre une conversation à l'aide de la modalité de conversation spécifiée. Une instance de IConversationWindow est renvoyée.

Implémentation de l’intégration de la présence du contact

En plus des trois interfaces requises mentionnées précédemment, il existe plusieurs autres interfaces importantes pour l'activation des fonctionnalités de la présence du contact dans Office. En voici quelques-unes :

• Interface IContact ou IContact2

• Interface ISelf

• Interfaces IContactManager et _IContactManagerEvents

• Interfaces IGroup et IGroupCollection

• Interface IContactSubscription

• Interface IContactEndPoint

• Interface ILocaleString

Interface IContact

L'interface IContact représente un utilisateur de l'application cliente de messagerie instantanée. L'interface expose la présence, les modalités disponibles, l'appartenance à un groupe et les propriétés du type de contact d'un utilisateur. Pour démarrer une conversation avec un autre utilisateur, vous devez fournir cette instance d'utilisateur IContact.

Le tableau 5 indique les membres qui doivent être implémentés dans la classe qui hérite de IContact.

Tableau 5. Implémentation de l’interface IContact

Membre	Description
Méthode CanStart	Renvoie true si un type de modalité donné peut être démarré sur le contact.
Méthode GetContactInformation	Obtient un élément de présence à partir d’un contact de publication.
Méthode BatchGetContactInformation	Obtient plusieurs éléments de présence à partir d’un contact de publication.
Propriété Settings	Obtient une collection de propriétés de contact.
Propriété CustomGroups	Obtient une collection de groupes dont le contact est membre.

Pendant le processus d'initialisation, l'application Office appelle la méthode IContact.CanStart pour déterminer les fonctionnalités de messagerie instantanée de l'utilisateur local. La méthode CanStart prend un indicateur de l’énumération UCCollaborationLib.ModalityTypes comme argument pour le paramètre _modalityTypes . Si l'utilisateur peut participer à la modalité demandée (autrement dit, si l'utilisateur est capable d'utiliser la messagerie instantanée, la messagerie audio et vidéo ou le partage d'application), la méthode CanStart renvoie true.

public bool CanStart(ModalityTypes _modalityTypes)
{
    // Define the capabilities of the current IM client application
    // user by using flags from the ModalityTypes enumeration.
    ModalityTypes userCapabilities = 
        ModalityTypes.ucModalityInstantMessage | 
        ModalityTypes.ucModalityAudioVideo | 
        ModalityTypes.ucModalityAppSharing;
    // Perform a simple test for equivalency.
    if (_modalityType == userCapabilities) 
    {
        return true;
    }
    else 
    {
        return false;
    }
}

La méthode GetContactInformation récupère les informations relatives au contact à partir de l'objet IContact. Le code appelant doit transmettre une valeur de l’énumération UCCollaborationLib.ContactInformationType pour le paramètre _contactInformationType , qui indique les données à récupérer.

public object GetContactInformation(
    ContactInformationType _contactInformationType)
{
    // Determine the information to return from the contact's data based
    // on the value passed in for the _contactInformationType parameter.
    switch (_contactInformationType)
    {
        case ContactInformationType.ucPresenceEmailAddresses:
        {
            // Return the URI associated with the contact.
            string returnValue = this.Uri.ToLower().Replace("sip:", String.Empty);
            return returnValue;
        }
        case ContactInformationType.ucPresenceDisplayName:
        {
            // Return the display name associated with the contact.
            string returnValue = this._DisplayName;
            return returnValue;
        }
        default:
        {
            throw new NotImplementedException;
        }
        // Additional implementation details omitted.
    }
}

Similaire à GetContactInformation, la méthode BatchGetContactInformation extrait plusieurs éléments de présence relatifs au contact à partir de l'objet IContact. Le code appelant doit passer un tableau de valeurs à partir de l’énumération ContactInformationType pour le paramètre _contactInformationTypes . La méthode renvoie un objet UCCollaborationLib.IContactInformationDictionary contenant les données requises.

public IMClientContactInformationDictionary BatchGetContactInformation(
    ContactInformationType[] _contactInformationTypes)
{
    // The IMClientContactInformationDictionary class implements the
    // IContactInformationDictionary interface.
    IMClientContactInformationDictionary contactDictionary = 
        new IMClientContactInformationDictionary();
    foreach (ContactInformationType type in _contactInformationTypes)
    {
        // Call GetContactInformation for each type of contact 
        // information to retrieve. This code adds a new entry to
        // a Dictionary object exposed by the
        // ContactInformationDictionary property.
        contactDictionary.ContactInformationDictionary.Add(
            type, this.GetContactInformation(type));
    }
    return contactDictionary;
}

La propriété IContact.Settings renvoie un objet IContactSettingDictionary contenant les propriétés personnalisées relatives au contact.

public IMClientContactSettingDictionary Settings
{
    get
    {
       // The IMClientContactSettingDictionary class implements
       // the IContactSettingDictionary interface.
       return new IMClientContactSettingDictionary();
    }
}

La propriété IContact.CustomGroups renvoie un objet IGroupCollection incluant tous les groupes dont le contact est membre.

public IMClientGroupCollection CustomGroups
{
    get {
       // The IMClientGroupCollection class implements
       // the IGroupCollection interface.
        return new IMClientGroupCollection();
    }
}

Interface ISelf

Pendant le processus d'initialisation, l'application Office récupère les données de l'utilisateur actuel en accédant à la propriété ILyncClient.Self, qui doit renvoyer un objet ISelf. L'interface ISelf représente l'utilisateur local et connecté de l'application cliente de messagerie instantanée.

Le tableau 6 présente les membres qui doivent être implémentés dans la classe qui hérite de ISelf.

Tableau 6. Implémentation de l’interface ISelf

Membre	Description
Propriété Contact	Obtient l'objet IContact associé à l'utilisateur local.

Les propriétés de présence, de modalités disponibles, d'appartenance au groupe et de type de contact de l'utilisateur local sont exposées via la propriété ISelf.Contact (qui renvoie un objet IContact). Pendant le processus d'initialisation, l'application Office accède à la propriété ISelf.Contact pour obtenir une référence aux informations de contact de l'utilisateur local.

Utilisez le code suivant pour définir une classe qui hérite de l'interface ISelf qui implémente la propriété Contact.

[ComVisible(true)]
public class IMClientSelf : ISelf
{
    // Declare a private field to store contact data for local user.
    private IMClientContact _contactData;
    // In the constructor for the ISelf object, the calling code 
    // must supply contact data.
    public IMClientSelf (IMClientContact _selfContactData)
    {
        this._contactData = _selfContactData;
    }
    // When accessed, the Contact property returns a reference
    // to the IContact object that represents the local user.
    public IMClientContact Contact
    {
        get
        {
            return this._contactData as IMClientContact;
        }
    }
    // Additional implementation details omitted.
}

Interfaces IContactManager et _IContactManagerEvents

L'objet IContactManager gère les contacts de l'utilisateur local, notamment les informations de contact de cet utilisateur local. L'application Office utilise un objet IContactManager pour accéder aux objets IContact qui correspondent aux contacts de l'utilisateur local.

Le tableau 7 affiche les membres qui doivent être implémentés dans la classe qui hérite de IContactManager et _IContactManagerEvents.

Tableau 7. Implémentation des interfaces IContactManager et _IContactManagerEvents

Interface	Membre	Description
IContactManager	Méthode GetContactByUri	Recherche ou crée une instance de contact à l’aide de l’URI du contact.
	Méthode CreateSubscription	Crée un objet ISubscription qui peut être utilisé pour le traitement par lots des abonnements ou des requêtes.
	Méthode Lookup	Recherche un groupe de contacts ou de distribution.
_IContactManagerEvents	Événement OnGroupAdded	Déclenché lorsqu'un groupe est ajouté à une collection de groupes. La collection de groupes mise à jour peut être obtenue à partir de la propriété IContactManager.Groups.
	Événement OnGroupRemoved	Déclenché lorsqu'un groupe est supprimé d'une collection de groupes. La collection de groupes mise à jour peut être obtenue à partir de la propriété IContactManager.Groups.
	Événement OnSearchProviderStateChanged	Déclenché lorsque le statut d'un fournisseur de recherche change.

Office appelle IContactManager.GetContactByUri pour obtenir les informations de présence d'un contact à l'aide de son adresse SIP. Lorsqu’un contact est configuré pour une adresse SIP dans Active Directory, Office détermine cette adresse pour un contact et appelle GetContactByUri, en passant l’adresse SIP du contact dans pour le paramètre _contactUri .

Lorsqu'Office ne peut pas déterminer l'adresse SIP du contact, il appelle la méthode IContactManager.Lookup pour trouver le SIP en utilisant le service de messagerie instantanée. Ici, Office transmet les meilleures données du contact qu'il peut trouver (par exemple, seule l'adresse de messagerie du contact). La méthode Lookup renvoie de manière asynchrone un objet AsynchronousOperation. Lorsqu'elle appelle le rappel, la méthode Lookup doit renvoyer la réussite ou l'échec de l'opération en plus de l'URI du contact.

public IMClientContact GetContactByUri(string _contactUri)
{
    // Declare a Contact variable to contain information about the contact.
    IMClientContact tempContact = null;
    // The _groupCollections field is an IGroupCollection object. Iterate 
    // over each group in collection to see if the 
    // contact is a part of the group.
    foreach (IMClientGroup group in this._groupCollections)
    {
       if (group.TryGetContact(_contactUri, out tempContact))
       {
           break;
       }
    }
    // Check to see that the URI returned a valid contact. If it
    // did not, create a new contact.
    if (tempContact == null)
    {
        tempContact = IMClientContact.BuildContact(_contactUri);
    }
    // Return the contact to the calling code.
    return tempContact;
}

L'application Office doit s'abonner aux modifications de présence d'un contact individuel. Par conséquent, lorsque le statut de présence d'un contact change, le serveur de messagerie instantanée avertit l'application cliente de messagerie instantanée, ce qui permet d'alerter l'application Office. Pour ce faire, l'application Office appelle la méthode IContactManager.CreateSubscription pour créer un objet IContactSubscription pour cette requête.

// Declare a private field to contain an IContactSubscription object.
private IMClientContactSubscription _contactSubscription;
// Return the IContactSubscription object associated 
// with the IContactManager object.
public IMClientContactSubscription CreateSubscription()
{
    return this._contactSubscription;
}

Interfaces IGroup et IGroupCollection

L'objet IGroup représente un ensemble de contacts avec des propriétés supplémentaires pour l'identification d'une collection de contacts par un nom de groupe collectif. Un objet IGroupCollection représente une collection d'objets IGroup définis par un utilisateur local et l'application cliente de messagerie instantanée. L'application Office utilise les objets IGroupCollection et IGroup pour accéder aux contacts de l'utilisateur local.

Le tableau 9 affiche les membres qui doivent être implémentés dans les classes qui héritent de IGroup et IGroupCollection dans le tableau suivant.

Tableau 9. Implémentation des interfaces IGroup et IGroupCollection

Interface	Membre	Description
IGroupCollection	Propriété Count	Renvoie le nombre d'objets IGroup de la collection.
	Propriété Item	Renvoie l'objet IGroup à la position d'index de la collection.
IGroup	Propriété Id	Renvoie l'ID du groupe.

Lorsque l'application Office obtient les informations relatives à l'utilisateur local, elle accède à l'appartenance aux groupes du contact (utilisateur local) en appelant la propriété IContact.CustomGroups, qui renvoie un objet IGroupCollection. Le IGroupCollection doit contenir un tableau (ou List) des objets IGroup. La classe qui dérive de IGroupCollection doit exposer une propriété Count, qui renvoie le nombre d'éléments de la collection, ainsi qu'une méthode d'indexation, this(int), qui renvoie un objet IGroup à partir de la collection.

Interface IContactSubscription

L'interface IContactSubscription vous permet de spécifier des contacts dont vous souhaitez recevoir des mises à jour d'informations de présence, ainsi que les types d'informations de présence qui déclenchent l'envoi d'une notification. Les applications Office utilisent un objet IContactSubscription pour enregistrer les modifications apportées au statut de présence du contact.

Le tableau 10 indique les membres qui doivent être implémentés dans les classes qui héritent de IContactSubscription.

Tableau 10. Implémentation de l’interface IContactSubscription

Membre	Description
Méthode AddContact	Ajoute un contact à l’objet d’abonnement.
Méthode Subscribe	Permet à l'application cliente de messagerie instantanée de suivre la présence d'un contact.

L'interface IContactSubscription doit contenir une référence pointant vers tous les objets IContact qu'elle surveille, à l'aide d'un tableau ou d'une List. La méthode IContactSubscription.AddContact ajoute un objet IContact pour la structure de données sous-jacente de l'objet IContactSubscription, ce qui ajoute un nouveau contact dont les changements de présence doivent être suivis.

// Store references to all of the IContact objects to subscribe to.
private List<IMClientContact> _subscribedContacts;
// Add a new IContact object to the collection of contacts.
public void AddContact(IMClientContact _contact)
{
    this._subscribedContacts.Add(_contact);
}

La méthode IContactSubscription.Subscribe permet à une application cliente de messagerie instantanée d'accéder aux observateurs de présence du contact. Elle peut utiliser une stratégie d'interrogation pour obtenir la présence à partir du serveur pour les contacts auxquels l'application cliente de messagerie instantanée s'est inscrite. La méthode Subscribe est utile dans les situations où la présence d'une personne ne figurant pas dans la liste des contacts d'un utilisateur est requise (par exemple, à partir d'un réseau plus grand public).

Interface IContactEndPoint

L'interface IContactEndPoint représente un numéro de téléphone à partir de la collection de numéros de téléphone d'un contact.

Le tableau 11 indique les membres qui doivent être implémentés dans les classes qui héritent de IContactEndPoint.

Tableau 11. Implémentation de l’interface IContactEndPoint

Membre	Description
Propriété DisplayName	Obtient la chaîne d’affichage.
Propriété Type	Obtient le type de point de terminaison du contact.
Propriété Uri	Obtient l’URI du contact.

Interface ILocaleString

L'interface ILocaleString est une structure de chaîne localisée contenant une chaîne localisée et l'ID des paramètres régionaux de la localisation. L'interface ILocaleString est utilisée pour mettre en forme la chaîne de statut personnalisé sur la carte de visite.

Le tableau 12 affiche les membres qui doivent être implémentés dans les classes qui héritent de ILocaleString.

Tableau 12. Implémentation de l’interface ILocaleString

Membre	Description
Propriété LocaleId	Obtient l’ID des paramètres régionaux.
Propriété Value	Obtient la chaîne.

Voir aussi

• Espace de noms UCCollaborationLib