Rôle du fournisseur de carnets d’adresses étranger

S’applique à : Outlook 2013 | Outlook 2016

Un fournisseur étranger est un fournisseur de carnet d’adresses qui :

• Affecte des identificateurs de modèle pour ses destinataires.
• Prend en charge la méthode IABLogon ::OpenTemplateID .
• Fournit du code pour gérer les destinataires qui existent dans les conteneurs d’autres fournisseurs de carnets d’adresses appelés fournisseurs d’hôtes. Ce code implique un objet de propriété, généralement une implémentation d’interface IMAPIProp , qui encapsule un objet de propriété du fournisseur hôte.

Agir en tant que fournisseur étranger est un rôle facultatif ; tous les fournisseurs n’ont pas besoin de prendre en charge les identificateurs de modèle et leur code associé. Implémentez votre fournisseur en tant que fournisseur étranger si vous souhaitez conserver le contrôle sur les destinataires créés par les fournisseurs d’hôtes à l’aide de modèles fournis par votre fournisseur.

Le format utilisé par votre fournisseur pour ses identificateurs d’entrée peut également être utilisé pour ses identificateurs de modèle. Les identificateurs de modèle doivent inclure le MAPIUID inscrit de votre fournisseur pour permettre à MAPI de lier correctement les destinataires aux fournisseurs appropriés.

MAPI appelle la méthode IABLogon ::OpenTemplateID de votre fournisseur lorsqu’un fournisseur hôte appelle IMAPISupport ::OpenTemplateID. Le fournisseur d’hôte transmet l’identificateur de modèle du destinataire dans le paramètre lpTemplateID dans son appel à IMAPISupport ::OpenTemplateID. MAPI détermine que l’identificateur de modèle appartient à votre fournisseur en faisant correspondre le MAPIUID dans l’identificateur de modèle avec le MAPIUID que votre fournisseur a inscrit au moment de l’ouverture de session. MAPI transfère ensuite l’appel du fournisseur d’hôte à votre fournisseur via la méthode IABLogon ::OpenTemplateID .

Le fournisseur d’hôte passe également un pointeur vers son implémentation d’objet de propriété pour le destinataire dans le paramètre lpMAPIPropData , un identificateur d’interface dans le paramètre lpInterface qui correspond au type d’implémentation d’interface passé dans lpMAPIPropData et un indicateur facultatif, FILL_ENTRY. Votre fournisseur est censé retourner dans le paramètre lppMAPIPropNew un pointeur vers une implémentation d’objet de propriété du type spécifié dans lpInterface. Le pointeur retourné peut être vers l’objet de propriété encapsulé implémenté par votre fournisseur ou vers l’objet fourni par le fournisseur hôte dans lpMAPIPropData. Votre fournisseur doit retourner un pointeur d’objet de propriété encapsulé dans les cas suivants :

• La table d’affichage du destinataire contient des contrôles de zone de liste.
• L’adresse e-mail du destinataire doit être assemblée à partir de données dans plusieurs contrôles de table d’affichage.
• Problèmes d’affichage des notifications de table par votre fournisseur.

L’indicateur FILL_ENTRY indique à votre fournisseur que le fournisseur hôte requiert la mise à jour de toutes les propriétés du destinataire. Votre fournisseur est tenu de répondre à cette demande.

Lorsqu’un fournisseur d’hôte appelle la méthode OpenTemplateID de votre fournisseur, votre fournisseur peut :

• Mettez à jour régulièrement les données d’une entrée copiée.
• Conservez une entrée copiée synchronisée avec son original, par exemple lorsqu’une entrée de carnet d’adresses est copiée dans le carnet d’adresses personnel.
• Implémentez des fonctionnalités qui ne peuvent pas être implémentées par le fournisseur d’hôte, telles que le remplissage dynamique des zones de liste dans la table de détails de l’entrée copiée à partir de données sur un serveur.
• Contrôler l’interaction entre les propriétés dans une entrée copiée ou un modèle instancié. Par exemple, le calcul PR_EMAIL_ADDRESS à partir d’autres propriétés affichées dans le tableau de détails.

Les deux premiers éléments sont des exemples de tâches qui ne nécessitent pas que votre fournisseur fournisse un objet de propriété encapsulé, une implémentation d’IMAPIProp basée sur l’implémentation du fournisseur d’hôte. Votre fournisseur peut simplement mettre à jour les propriétés si nécessaire et retourner, en définissant le paramètre lppMAPIPropNew pour qu’il pointe vers le pointeur transmis par le fournisseur d’hôte dans le paramètre lpMAPIPropData .

Les deux deuxièmes tâches nécessitent que votre fournisseur retourne au fournisseur d’hôte un objet de propriété qui encapsule l’objet du fournisseur hôte avec des fonctionnalités supplémentaires, telles que la possibilité d’afficher une feuille de propriétés pour l’entrée. Cet objet de propriété est un utilisateur de messagerie ou une liste de distribution, selon le type d’objet transmis par le fournisseur d’hôte dans le paramètre lpMAPIPropData et indiqué par l’identificateur d’interface dans le paramètre lpInterface . Si le paramètre lpMAPIPropData pointe vers un utilisateur de messagerie, l’objet de propriété encapsulé de votre fournisseur doit être une implémentation IMailUser . Si lpMAPIPropData pointe vers une liste de distribution, il doit s’agir d’une implémentation IDistList .

L’objet de propriété encapsulé de votre fournisseur intercepte les appels de méthode IMAPIProp pour effectuer une manipulation spécifique au contexte du destinataire du fournisseur d’hôte, c’est-à-dire l’objet qu’il encapsule. MAPI n’a qu’une seule exigence pour les objets de propriété encapsulés : tous les appels à IMAPIProp ::OpenProperty demandant la propriété PR_DETAILS_TABLE (PidTagDetailsTable) doivent être passés au fournisseur hôte. L’implémentation de votre fournisseur peut utiliser la table retournée pour intercepter les notifications de table d’affichage ou pour ajouter les siennes si nécessaire.

La liste suivante inclut les tâches qui sont généralement implémentées dans l’objet de propriété encapsulé implémenté par des fournisseurs étrangers :

• Prétraitement et posttraitement des valeurs de propriété pour le destinataire hôte dans IMAPIProp ::GetProps.
• La gestion des détails affiche les contrôles de table, tels que les boutons et les zones de liste, dans IMAPIProp ::OpenProperty.
• Validation ou manipulation des valeurs de propriété pour le destinataire hôte dans IMAPIProp ::SetProps.
• Le calcul des propriétés requises telles que PR_EMAIL_ADDRESS et la vérification que toutes les propriétés nécessaires ont été définies avant d’enregistrer le destinataire de l’hôte dans IMAPIProp ::SaveChanges.

Pour implémenter IABLogon ::OpenTemplateID

1. Vérifiez si l’identificateur de modèle transmis avec le paramètre lpTemplateID est valide et est dans un format que votre fournisseur reconnaît. Si ce n’est pas le cas, échouez et retournez MAPI_E_INVALID_ENTRYID.

2. Créez un objet du type indiqué par l’identificateur du modèle, qu’il s’agit d’un utilisateur de messagerie, d’une liste de distribution ou d’un destinataire unique.

3. Appelez la méthode IUnknown ::AddRef dans l’objet de propriété du fournisseur d’hôte, qui est l’objet vers lequel pointe le paramètre lpMAPIPropData .

4. Si le paramètre ulTemplateFlags est défini sur FILL_ENTRY :

   1. Si le nouvel objet est un utilisateur de messagerie ou une liste de distribution :

      1. Récupérez toutes les propriétés du nouvel objet, éventuellement en appelant sa méthode IMAPIProp ::GetProps .

      2. Appelez la méthode IMAPIProp ::SetProps du fournisseur d’hôte pour copier toutes les propriétés récupérées dans l’objet de propriété du fournisseur d’hôte.

   2. Si le nouvel objet est un destinataire unique, appelez la méthode IMAPIProp ::SetProps du fournisseur d’hôte pour définir les propriétés suivantes :

      • PR_ADDRTYPE (PidTagAddressType) au type d’adresse géré par votre fournisseur.

      • PR_TEMPLATEID (PidTagTemplateid) à l’identificateur de modèle à partir des paramètres lpTemplateID et cbTemplateID .

      • PR_DISPLAY_TYPE (PidTagDisplayType) à DT_MAILUSER ou DT_DISTLIST, le cas échéant.

5. Définissez le contenu du paramètre lppMAPIPropNew pour qu’il pointe vers le nouvel objet de votre fournisseur ou l’objet de propriété transmis avec le paramètre lpMAPIPropData , selon que votre fournisseur détermine si un objet encapsulé est nécessaire.

6. Si une erreur critique se produit, telle qu’une défaillance réseau ou une condition de mémoire insuffisante, retournez la valeur d’erreur appropriée. Cette valeur doit être propagée au client avec la structure MAPIERROR appropriée, tâche effectuée par le fournisseur hôte.