StgCreateDocfileOnILockBytes, fonction (coml2api.h)

Article
02/24/2024

La fonction StgCreateDocfileOnILockBytes crée et ouvre un nouvel objet de stockage de fichiers composés au-dessus d’un objet de tableau d’octets fourni par l’appelant. L’objet de stockage prend en charge l’implémentation de fichier composé fournie par COM pour l’interface IStorage .

Syntaxe

HRESULT StgCreateDocfileOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  DWORD      grfMode,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Paramètres

[in] plkbyt

Pointeur vers l’interface ILockBytes sur l’objet de tableau d’octets sous-jacent sur lequel créer un fichier composé.

[in] grfMode

Spécifie le mode d’accès à utiliser lors de l’ouverture du nouveau fichier composé. Pour plus d’informations, consultez Constantes STGM et la section Remarques ci-dessous.

[in] reserved

Réservé pour une future utilisation ; doit être nul.

[out] ppstgOpen

Pointeur vers l’emplacement du pointeur IStorage sur le nouvel objet de stockage.

Valeur retournée

La fonction StgCreateDocfileOnILockBytes peut également retourner des erreurs de système de fichiers ou des erreurs système encapsulées dans une erreur HRESULT ou une erreur d’interface ILockBytes . Pour plus d’informations, consultez Stratégies de gestion des erreurs et Gestion des erreurs inconnues.

Remarques

La fonction StgCreateDocfileOnILockBytes crée un objet de stockage au-dessus d’un objet de tableau d’octets à l’aide de l’implémentation de fichier composé fourni par COM de l’interface IStorage . StgCreateDocfileOnILockBytes peut être utilisé pour stocker un document dans un magasin de données arbitraire, tel que la mémoire ou une base de données relationnelle. Le tableau d’octets (indiqué par le paramètre pLkbyt , qui pointe vers l’interface ILockBytes sur l’objet) est utilisé pour le stockage sous-jacent à la place d’un fichier disque.

À l’exception de la spécification d’un objet de tableau d’octets fourni par le programmeur, StgCreateDocfileOnILockBytes est similaire à la fonction StgCreateDocfile .

Le fichier composé nouvellement créé est ouvert en fonction des modes d’accès dans le paramètre grfMode , sous réserve des restrictions suivantes :

Le comportement du mode de partage et l’isolation transactionnelle dépendent de l’implémentation ILockBytes prenant en charge LockRegion et UnlockRegion avec LOCK_ONLYONCE sémantique. Les implémentations peuvent indiquer au stockage structuré qu’elles prennent en charge cette fonctionnalité en définissant le bit LOCK_ONLYONCE dans le membre grfLocksSupported de STATSTG. Si une implémentation ILockBytes ne prend pas en charge cette fonctionnalité, les modes de partage ne sont pas appliqués et les validations transactionnelles au niveau racine ne se coordonnent pas correctement avec d’autres instances transactionnelles ouvertes sur le même tableau d’octets. Les applications qui utilisent une implémentation ILockBytes qui ne prend pas en charge le verrouillage de région, comme l’implémentation CreateStreamOnHGlobal , doivent éviter d’ouvrir plusieurs instances simultanées sur le même tableau d’octets.

StgCreateDocfileOnILockBytes ne prend pas en charge le mode simple. L’indicateur STGM_SIMPLE, s’il est présent, est ignoré.

À des fins de conversion, le fichier est considéré comme existant. Par conséquent, il n’est pas utile d’utiliser la valeur STGM_FAILIFTHERE , car elle provoque le retour d’une erreur. Toutefois, les STGM_CREATE et les STGM_CONVERT restent utiles.

La possibilité de créer un fichier composé sur un objet de tableau d’octets est fournie pour prendre en charge le fait que les données (sous une arborescence IStorage et IStream ) vivent dans un espace non persistant. Compte tenu de cette fonctionnalité, rien n’empêche un document stocké dans un fichier d’utiliser cette fonctionnalité. Par exemple, un conteneur peut effectuer cette opération pour réduire l’impact sur son format de fichier provoqué par l’adoption de COM. Toutefois, il est recommandé que les documents COM adoptent l’interface IStorage pour leur propre stockage externe. Les avantages sont les suivants :

La structure de stockage du document est identique à sa structure de stockage lorsqu’il s’agit d’un objet incorporé, ce qui réduit le nombre de cas que l’application doit gérer.
Vous pouvez écrire des outils pour accéder aux objets ole incorporés et liés dans le document sans connaître particulièrement le format de fichier du document. Un exemple d’un tel outil est un utilitaire de copie qui copie tous les documents inclus dans un conteneur contenant des objets liés. Un utilitaire de copie comme celui-ci doit accéder aux liens contenus pour déterminer l’étendue des fichiers à copier.
L’implémentation IStorage résout le problème de validation des modifications apportées au fichier. Une application utilisant l’interface ILockBytes doit gérer ces problèmes elle-même.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	coml2api.h (inclure Objbase.h)
Bibliothèque	Ole32.lib
DLL	Ole32.dll

Voir aussi

StgCreateDocfile

Partager via