IABLogon::PrepareRecips
S’applique à : Outlook 2013 | Outlook 2016
Prépare une liste de destinataires pour une utilisation ultérieure par le système de messagerie.
HRESULT PrepareRecips(
ULONG ulFlags,
LPSPropTagArray lpPropTagArray,
LPADRLIST lpRecipList
);
Paramètres
ulFlags
[in] Masque de bits d’indicateurs qui contrôle le type du texte dans les chaînes retournées. L’indicateur suivant peut être défini :
- MAPI_CACHE_ONLY : utilisez uniquement le carnet d’adresses en mode hors connexion pour effectuer la résolution de noms. Par exemple, vous pouvez utiliser cet indicateur pour permettre à une application cliente d’ouvrir la liste d’adresses globale (GAL) en mode d’échange mis en cache et d’accéder à une entrée de ce carnet d’adresses à partir du cache sans créer de trafic entre le client et le serveur. Cet indicateur est pris en charge uniquement par le fournisseur de carnets d’adresses Exchange.
lpPropTagArray
[in] Pointeur vers une structure SPropTagArray qui contient un tableau de balises de propriété qui indiquent les propriétés qui nécessitent une mise à jour, le cas échéant. Le paramètre lpPropTagArray peut être NULL.
lpRecipList
[in] Pointeur vers une structure ADRLIST qui contient la liste des destinataires.
Valeur renvoyée
S_OK
La liste des destinataires a été préparée avec succès.
MAPI_E_NOT_FOUND
Un ou plusieurs destinataires du paramètre lpRecipList n’existent pas.
Un client appelle la méthode MAPI IAddrBook ::P repareRecips pour modifier ou réorganiser un ensemble de propriétés pour un ou plusieurs destinataires. Les destinataires peuvent ou non faire partie de la liste des destinataires d’un message sortant. MAPI transfère cet appel à la méthode IABLogon ::P repareRecips d’un fournisseur de carnets d’adresses .
IABLogon ::P repareRecips effectue quatre tâches main :
Garantit que tous les destinataires de la liste d’adresses pointés par le paramètre lpRecipList ont un identificateur d’entrée à long terme.
Garantit que tous les destinataires ont les propriétés spécifiées dans le tableau de valeurs de propriété vers lequel pointe le paramètre lpPropTagArray .
Garantit que les propriétés du tableau de valeurs de propriété apparaissent avant toutes les autres propriétés qui existaient avant l’appel.
Garantit que l’ordre des propriétés dans la structure ADRENTRY de chaque destinataire dans la structure ADRLIST est le même que dans le tableau des valeurs de propriété.
La structure ADRENTRY dans le paramètre lpRecipList contient une structure ADRENTRY pour chaque destinataire. Chaque structure ADRENTRY contient un tableau de structures SPropValue pour décrire les propriétés du destinataire. Lorsque IABLogon ::P repareRecips est retourné, le tableau de structure SPropValue pour chaque destinataire inclut les propriétés de lpPropTagArray , suivies des autres propriétés du destinataire.
Remarques pour les responsables de l’implémentation
L’implémentation d’IABLogon ::P repareRecips implique de placer les propriétés dans un ordre spécifique, de récupérer des valeurs de propriété et de convertir des identificateurs d’entrée à court terme en identificateurs d’entrée à long terme. Les propriétés demandées dans le paramètre lpPropTagArray doivent se trouver au début du tableau de valeurs de propriété associé à la structure ADRENTRY de chaque destinataire dans le paramètre lpRecipList . Si les valeurs de ces propriétés n’existent pas, ouvrez l’utilisateur de messagerie ou la liste de distribution associé à l’aide de son identificateur d’entrée et récupérez les valeurs de propriété manquantes.
Allouez chaque structure SPropValue passée dans lpRecipList séparément afin que les structures puissent être libérées individuellement. Si vous devez allouer de l’espace supplémentaire pour une structure SPropValue , par exemple pour stocker les données d’une propriété de chaîne, utilisez la fonction MAPIAllocateBuffer pour allouer de l’espace supplémentaire pour le tableau de valeurs de propriété complète. Utilisez la fonction MAPIFreeBuffer pour libérer le tableau de valeurs de propriété d’origine, puis utilisez la fonction MAPIAllocateMore pour allouer toute mémoire supplémentaire nécessaire.
Pour implémenter IABLogon ::P repareRecips, procédez comme suit :
Recherchez les entrées dans le paramètre lpPropTagArray . Si le tableau de valeurs de propriété est vide, il n’y a pas de travail à faire. Retourne une valeur de réussite.
Traitez chaque destinataire dans le paramètre lpRecipList . Il existe un membre de structure ADRENTRY pour chaque destinataire dans la liste. Ignorez les types de destinataires suivants :
Destinataires sans identificateur d’entrée dans le membre rgPropVals de leur structure ADRENTRY (autrement dit, les destinataires non résolus).
Destinataires avec un identificateur d’entrée qui n’appartient pas à votre fournisseur. Ces destinataires seront transmis à un autre fournisseur de carnets d’adresses.
Ouvrez le destinataire et récupérez les propriétés qui sont déjà définies pour le destinataire.
Fusionnez le tableau de valeurs de propriété spécifié dans l’objet lpRecipList avec le tableau de propriétés retourné par GetProps. Si la même propriété se trouve dans les deux tableaux de propriétés, utilisez la valeur de lpRecipList.
Si le tableau de valeurs de propriété lpRecipList est suffisamment grand pour contenir toutes les propriétés nécessaires, remplacez-le simplement par le tableau fusionné. Si le tableau de valeurs de propriété lpRecipList n’est pas assez grand, remplacez-le par un tableau nouvellement alloué. Assurez-vous que le nouveau tableau a une valeur mise à jour dans chacun de ses membres cValues .
Si vous ne reconnaissez pas une ou plusieurs propriétés dans le paramètre lpPropTagArray , définissez le type de propriété dans la structure ADRENTRY du destinataire sur PT_ERROR et la valeur de la propriété sur MAPI_E_NOT_FOUND ou sur une autre valeur qui donne une raison plus spécifique à l’indisponibilité de la propriété. Pour plus d’informations sur PT_ERROR, consultez Types de propriétés.
Remarque
Ne réallouez jamais la structure ADRLIST passée dans IABLogon ::P repareRecips ou ne modifiez jamais son nombre d’entrées.