IMAPIProp::OpenProperty

Article
04/04/2023

S’applique à : Outlook 2013 | Outlook 2016

Retourne un pointeur vers une interface qui peut être utilisée pour accéder à une propriété.

HRESULT OpenProperty(
  ULONG ulPropTag,
  LPCIID lpiid,
  ULONG ulInterfaceOptions,
  ULONG ulFlags,
  LPUNKNOWN FAR * lppUnk
);

Paramètres

ulPropTag

[in] Balise de propriété pour la propriété à accéder. L’identificateur et le type doivent être inclus dans la balise de propriété.

lpiid

[in] Pointeur vers l’identificateur de l’interface à utiliser pour accéder à la propriété . Le paramètre lpiid ne doit pas être null.

ulInterfaceOptions

[in] Données liées à l’interface identifiée par le paramètre lpiid .

ulFlags

[in] Masque de bits d’indicateurs qui contrôle l’accès à la propriété . Les indicateurs suivants peuvent être définis :

MAPI_CREATE

Si la propriété n’existe pas, elle doit être créée. Si la propriété existe, la valeur actuelle de la propriété doit être ignorée. Lorsqu’un appelant définit l’indicateur MAPI_CREATE, il doit également définir l’indicateur MAPI_MODIFY.

MAPI_DEFERRED_ERRORS

Permet à OpenProperty de retourner avec succès, éventuellement avant que l’objet ne soit entièrement disponible pour l’appelant. Si l’objet n’est pas disponible, effectuer un appel d’objet suivant peut générer une erreur.

MAPI_MODIFY

MAPI_MODIFY est nécessaire dans les situations suivantes :

Lors de l’ouverture d’une propriété de flux, telle que IID_IStream, pour la modifier.
Lors de l’ouverture d’une pièce jointe de message incorporée, telle que PR_ATTACH_DATA_OBJ ouverte avec IID_IMessage, pour la modifier.

lppUnk

[out] Pointeur vers l’interface demandée à utiliser pour l’accès aux propriétés.

Valeur renvoyée

S_OK

Le pointeur d’interface demandé a été retourné avec succès.

MAPI_E_INTERFACE_NOT_SUPPORTED

L’interface demandée n’est pas prise en charge pour cette propriété.

MAPI_E_NO_ACCESS

L’appelant n’a pas les autorisations nécessaires pour accéder à la propriété .

MAPI_E_NO_SUPPORT

L’objet ne peut pas fournir l’accès à cette propriété via l’interface demandée.

MAPI_E_NOT_FOUND

La propriété demandée n’existe pas et MAPI_CREATE n’a pas été défini dans le paramètre ulFlags .

MAPI_E_INVALID_PARAMETER

Le type de propriété dans la balise est défini sur PT_UNSPECIFIED.

Remarques

La méthode IMAPIProp ::OpenProperty fournit l’accès à une propriété via une interface particulière. OpenProperty est une alternative aux méthodes IMAPIProp ::GetProps et IMAPIProp ::SetProps . Lorsque GetProps ou SetProps échoue parce que la propriété est trop grande ou trop complexe, appelez OpenProperty. OpenProperty est généralement utilisé pour accéder aux propriétés de type PT_OBJECT.

Remarques pour les appelants

Pour accéder aux pièces jointes des messages, ouvrez la propriété PR_ATTACH_DATA_OBJ (PidTagAttachDataObject) avec un identificateur d’interface différent, selon le type de pièce jointe. Le tableau suivant décrit comment appeler OpenProperty pour les différents types de pièces jointes :

Type de pièce jointe	Identificateur d’interface à utiliser
Binaire	IID_IStream
String	IID_IStream
Message	IID_IMessage
OLE 2.0	IID_IStreamDocfile

IStreamDocfile est un dérivé de l’interface IStream basée sur un fichier composé OLE 2.0. IStreamDocfile est le meilleur choix pour accéder aux pièces jointes OLE 2.0, car il implique le moins de surcharge. Vous pouvez utiliser IID_IStreamDocFile pour les propriétés qui contiennent des données stockées dans un stockage structuré disponible via l’interface IStorage .

Pour plus d’informations sur l’utilisation d’OpenProperty avec des pièces jointes, consultez la propriété PR_ATTACH_DATA_OBJ et Ouverture d’une pièce jointe.

N’utilisez pas le pointeur IStream que vous recevez pour appeler sa méthode Seek ou SetSize , sauf si vous utilisez une variable de position ou de taille nulle. En outre, ne vous fiez pas à la valeur du paramètre de sortie plibNewPosition retourné par l’appel Seek .

Si vous appelez OpenProperty pour accéder à une propriété avec l’interface IStream , utilisez uniquement cette interface pour y apporter des modifications. N’essayez pas de mettre à jour la propriété avec les autres méthodes IMAPIProp : IUnknown , telles que SetProps ou IMAPIProp ::D eleteProps.

N’essayez pas d’ouvrir une propriété avec OpenProperty plusieurs fois. Les résultats ne sont pas définis, car ils peuvent varier d’un fournisseur à l’autre.

Si vous devez modifier la propriété à ouvrir, définissez l’indicateur MAPI_MODIFY. Si vous ne savez pas si l’objet prend en charge la propriété, mais que vous le pensez, définissez les indicateurs MAPI_CREATE et MAPI_MODIFY. Chaque fois que MAPI_CREATE est défini, MAPI_MODIFY doit également l’être.

Vous êtes chargé de recaster le pointeur d’interface retourné dans le paramètre lppUnk en un pointeur approprié pour l’interface spécifiée dans le paramètre lpiid . Vous devez également utiliser le pointeur retourné pour appeler sa méthode IUnknown ::Release lorsque vous en avez terminé.

Parfois, la définition des indicateurs dans le paramètre ulFlags n’est pas suffisante pour indiquer le type d’accès à la propriété requise. Vous pouvez placer des données supplémentaires, telles que des indicateurs, dans le paramètre ulInterfaceOptions . Ces données dépendent de l’interface. Certaines interfaces (telles que IStream) l’utilisent, d’autres non. Par exemple, lorsque vous ouvrez une propriété à modifier avec IStream, définissez l’indicateur STGM_WRITE dans le paramètre ulInterfaceOptions en plus de MAPI_MODIFY. Lorsque vous ouvrez une table à l’aide de l’interface IMAPITable , vous pouvez définir ulInterfaceOptions sur MAPI_UNICODE pour indiquer si les colonnes de la table contenant des propriétés de chaîne doivent être au format Unicode.

Référence MFCMAPI

Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.

Fichier	Fonction	Commentaire
StreamEditor.cpp	CStreamEditor ::ReadTextStreamFromProperty	MFCMAPI utilise la méthode IMAPIProp ::OpenProperty pour récupérer une interface de flux de texte et de propriétés binaires volumineuses.

Partager via