Stockage structuré dans MAPI
S’applique à : Outlook 2013 | Outlook 2016
Le stockage structuré fait référence au organization hiérarchique du stockage introduit avec COM. Dans un environnement de stockage structuré, le stockage est organisé en deux ou trois types d’objets :
Stream objets
Verrouiller les objets octets
Objets de stockage
Stream et les octets de verrou sont des objets de niveau inférieur qui accèdent directement aux données. Stream objets implémentent l’interface IStream qui définit des méthodes de lecture, d’écriture, de positionnement et de copie d’octets de données. Les objets Lock bytes implémentent une autre interface COM, ILockBytes, pour accéder aux données avec un tableau d’octets. Les tableaux d’octets sont généralement utilisés pour fournir un accès personnalisé au stockage sous-jacent.
Les objets de stockage sont superposés au-dessus du flux ou verrouillent les objets octets ; ils peuvent contenir un ou plusieurs de ces objets, ainsi que d’autres objets de stockage. Les objets de stockage implémentent l’interface IStorage qui définit des méthodes de création, d’accès et de maintenance d’objets imbriqués.
Étant donné que IStream, ILockBytes et IStorage sont des interfaces COM plutôt que des interfaces MAPI, leurs méthodes retournent des valeurs d’erreur COM plutôt que des valeurs MAPI. Les clients et les fournisseurs de services appelant des méthodes dans ces interfaces doivent utiliser la fonction d’API MapStorageSCode pour traduire ces valeurs en valeurs d’erreur MAPI. Pour plus d’informations, consultez MapStorageSCode.
Les clients et les fournisseurs de services utilisent le stockage structuré pour travailler avec des propriétés trop volumineuses pour être conservées avec les méthodes IMAPIProp , généralement des propriétés de chaîne et binaires volumineuses. L’une des façons courantes pour les clients ou les fournisseurs de services d’y accéder consiste à spécifier IStream ou IStorage comme identificateur d’interface dans un appel à la méthode IMAPIProp ::OpenProperty . Par exemple, les clients appellent OpenProperty avec PR_ATTACH_DATA_BIN comme balise de propriété et IID_IStream comme identificateur d’interface pour accéder à une pièce jointe binaire dans un message.
Les clients et les fournisseurs de services peuvent implémenter leurs propres objets de flux et de stockage ou appeler des fonctions d’API pour accéder aux implémentations fournies par MAPI ou COM. Étant donné que les implémentations fournies servent la plupart des objectifs, les clients et les fournisseurs de services ont rarement besoin de créer les leurs.
Lorsqu’un client appelle OpenProperty sur un objet MAPI pour accéder à l’une de ses propriétés via un objet de stockage, le fournisseur de services ouvre généralement l’objet de stockage en mode direct. Toutefois, il s’agit d’un comportement classique plutôt que obligatoire. Les clients doivent supposer que tous les objets de stockage ouverts ou créés par les fournisseurs de services sont traités et nécessitent un appel à IStorage ::Commit. Ils doivent également se rappeler que les modifications apportées aux objets de stockage ne seront pas rendues permanentes tant qu’elles n’appelleront pas IMAPIProp ::SaveChanges après la validation finale pour enregistrer l’objet MAPI. Pour plus d’informations, consultez IMAPIProp ::SaveChanges.
MAPI et COM fournissent plusieurs fonctions d’API pour définir ou accéder à des objets de stockage et de flux. Les fonctions couramment utilisées sont décrites dans le tableau suivant.
Fonctions d’accès aux objets de stockage et de Stream
| Fonction | Description |
|---|---|
|
HrIStorageFromStream |
Crée un objet de stockage pour accéder à un flux ou verrouiller un objet octets. |
|
OpenIMsgOnIStg |
Crée un objet message pour accéder à un objet de stockage. |
|
OpenStreamOnFile |
Crée un objet de flux pour accéder à un fichier. |
|
WrapCompressedRTFStream |
Crée un objet stream qui contient la version compressée ou non compressée d’un flux contenant le texte enrichi d’un message. |
Pour récupérer les noms des flux dans un sous-stockage donné
Appelez la méthode IStorage ::EnumElements du sous-stockage pour obtenir une interface IEnumSTATSTG .
Appelez IEnumSTATSTG ::Next avec autant de structures STATSTG à la fois que vous le pouvez. Si vous demandez 100 à la fois, Next renvoie généralement S_FALSE avec le contenu de pceltFetched défini sur le nombre qui ont été réellement récupérés.
Recherchez les structures STATSTG signalées avec STGTY_STREAM.
Relâchez le paramètre pwcsName .
Pour créer un objet de stockage pour accéder à un flux existant ou verrouiller un objet octets
- Les clients appellent HrIStorageFromStream.
Pour créer un objet message afin d’accéder à un objet de stockage existant
- Les fournisseurs de services et les clients appellent OpenIMsgOnIStg. L’objet message créé diffère des objets de message généralement créés par les fournisseurs de magasins de messages en ce qu’il ne prend pas en charge toutes les méthodes d’interface IMessage : IMAPIProp , telles que IMessage ::SubmitMessage. Un paramètre d’entrée facultatif pour OpenIMsgOnIStg est une fonction de rappel conforme au prototype MSGCALLRELEASE . Cette fonction est appelée par le nouvel objet message lorsque le nombre de références du message atteint zéro. L’implémentation d’une fonction MSGCALLRELEASE peut être utile pour effectuer le traitement final avant la suppression complète du nouveau message.
OpenStreamOnFile est couramment utilisé pour stocker les pièces jointes, car il crée un flux qui lit et écrit dans un fichier. OpenProperty avec PR_ATTACH_DATA_BIN comme balise de propriété crée un flux pour le stockage des données binaires de pièces jointes.
Pour compresser ou décompresser un flux contenant le texte du message au format RTF
- Les clients appellent WrapCompressedRTFStream. WrapCompressedRTFStream crée un flux qui encapsule le flux RTF. Le flux de wrapper n’implémente pas toutes les méthodes IStream ; Les méthodes suivantes sont exclues : Seek, SetSize, Revert, LockRegion, UnlockRegion, Stat et Clone. Cela est dû au fait que les objets de flux créés par WrapCompressedRTFStream ne prennent pas en charge SetSize ou Stat. Il n’existe pas de moyen simple d’étendre ou de récupérer leur taille. La meilleure stratégie consiste à choisir une taille de mémoire tampon raisonnable et à lire ou écrire dans une boucle.
Remarque
COM a une implémentation d’objet de stockage basée sur un tableau d’octets qui retourne un objet IEnumSTATSTG à partir de la méthode EnumElements qui pose problème. En particulier, la méthode QueryInterface ne fonctionne pas correctement. Les fournisseurs de services qui implémentent leurs propres objets de stockage à l’aide de l’implémentation COM doivent créer un wrapper mince pour l’objet IEnumSTATSTG qui transfère les appels aux méthodes IEnumSTATSTG sous-jacentes, mais implémente ses propres méthodes AddRef, Release, QueryInterface et Clone .