Fonction StgOpenStorageEx (coml2api.h)
La fonction StgOpenStorageEx ouvre un objet de stockage racine existant dans le système de fichiers. Utilisez cette fonction pour ouvrir les fichiers composés et les fichiers standard. Pour créer un fichier, utilisez la fonction StgCreateStorageEx .
Syntaxe
HRESULT StgOpenStorageEx(
[in] const WCHAR *pwcsName,
[in] DWORD grfMode,
[in] DWORD stgfmt,
[in] DWORD grfAttrs,
[in, out] STGOPTIONS *pStgOptions,
[in] PSECURITY_DESCRIPTOR pSecurityDescriptor,
[in] REFIID riid,
[out] void **ppObjectOpen
);
Paramètres
[in] pwcsName
Pointeur vers le chemin du fichier de chaîne Unicode terminé par null qui contient l’objet de stockage. Cette taille de chaîne ne peut pas dépasser MAX_PATH caractères.
Windows Server 2003 et Windows XP/2000 : Contrairement à la fonction CreateFile , la limite de MAX_PATH ne peut pas être dépassée à l’aide du préfixe « \ ? ».
[in] grfMode
Valeur qui spécifie le mode d’accès pour ouvrir le nouvel objet de stockage. Pour plus d’informations, consultez Constantes STGM. Si l’appelant spécifie le mode traité avec STGM_CREATE ou STGM_CONVERT, le remplacement ou la conversion se produit lorsque l’opération de validation est appelée pour le stockage racine. Si IStorage ::Commit n’est pas appelé pour l’objet de stockage racine, le contenu précédent du fichier est restauré. STGM_CREATE et STGM_CONVERT ne peuvent pas être combinés avec l’indicateur STGM_NOSNAPSHOT, car une copie instantané est requise lorsqu’un fichier est remplacé ou converti en mode traité.
Si l’objet de stockage est ouvert en mode direct (STGM_DIRECT) avec accès à STGM_WRITE ou STGM_READWRITE, le mode de partage doit être STGM_SHARE_EXCLUSIVE , sauf si le mode STGM_DIRECT_SWMR est spécifié. Pour plus d'informations, consultez la section Notes. Si l’objet de stockage est ouvert en mode direct avec accès à STGM_READ, le mode de partage doit être STGM_SHARE_EXCLUSIVE ou STGM_SHARE_DENY_WRITE, sauf si STGM_PRIORITY ou STGM_DIRECT_SWMR est spécifié. Pour plus d'informations, consultez la section Notes.
Le mode d’ouverture d’un fichier peut affecter les performances de l’implémentation. Pour plus d’informations, consultez Limites d’implémentation de fichiers composés.
[in] stgfmt
Valeur qui spécifie le format de fichier de stockage. Pour plus d’informations, consultez l’énumération STGFMT .
[in] grfAttrs
Valeur qui dépend de la valeur du paramètre stgfmt .
STGFMT_DOCFILE doit être égal à zéro (0) ou FILE_FLAG_NO_BUFFERING. Pour plus d’informations sur cette valeur, consultez CreateFile. Si la taille de secteur du fichier, spécifiée dans pStgOptions, n’est pas un multiple entier de la taille de secteur physique du disque sous-jacent, cette opération échoue. Toutes les autres valeurs de stgfmt doivent être égales à zéro.
[in, out] pStgOptions
Pointeur vers une structure STGOPTIONS qui contient des données sur l’objet de stockage ouvert. Le paramètre pStgOptions est valide uniquement si le paramètre stgfmt est défini sur STGFMT_DOCFILE. Le membre usVersion doit être défini avant d’appeler StgOpenStorageEx. Pour plus d’informations, consultez la structure STGOPTIONS .
[in] pSecurityDescriptor
Réservés au; doit être égal à zéro.
[in] riid
Valeur qui spécifie le GUID du pointeur d’interface à retourner. Peut également être la valeur spécifiée par l’en-tête pour IID_IStorage pour obtenir l’interface IStorage ou pour IID_IPropertySetStorage pour obtenir l’interface IPropertySetStorage .
[out] ppObjectOpen
Adresse d’une variable pointeur d’interface qui reçoit un pointeur pour une interface sur l’objet de stockage ouvert ; contient la valeur NULL en cas d’échec de l’opération.
Valeur retournée
Cette fonction peut également retourner des erreurs de système de fichiers ou des erreurs système encapsulées dans un HRESULT. Pour plus d’informations, consultez Stratégies de gestion des erreurs et Gestion des erreurs inconnues.
Remarques
StgOpenStorageEx est un sur-ensemble de la fonction StgOpenStorage et doit être utilisé par le nouveau code. Les améliorations futures du stockage structuré seront exposées via cette fonction. Pour plus d’informations sur les plateformes prises en charge, consultez la section Configuration requise.
La fonction StgOpenStorageEx ouvre l’objet de stockage racine spécifié en fonction du mode d’accès dans le paramètre grfMode et, si elle réussit, fournit un pointeur d’interface pour l’objet de stockage ouvert dans le paramètre ppObjectOpen . Cette fonction peut être utilisée pour obtenir une implémentation de fichier composé IStorage, une implémentation de fichier composé IPropertySetStorage ou une implémentation de fichier composé
Implémentation du système de fichiers NTFS d’IPropertySetStorage.
Lorsque vous ouvrez un fichier, le système sélectionne une implémentation de stockage structuré en fonction de l’indicateur STGFMT que vous spécifiez sur le type de fichier et le type de lecteur où le fichier est stocké.
Utilisez la fonction StgOpenStorageEx pour accéder au stockage racine d’un document de stockage structuré ou au stockage de jeux de propriétés de tout fichier prenant en charge les jeux de propriétés. Pour plus d’informations sur les identificateurs d’interface (ID) pris en charge pour les différentes valeurs STGFMT , consultez STGFMT.
Lorsqu’un fichier est ouvert avec cette fonction pour accéder à l’implémentation du jeu de propriétés NTFS, des règles de partage spéciales s’appliquent. Pour plus d’informations, consultez Implémentation IPropertySetStorage-NTFS.
Si un fichier composé est ouvert en mode transactionné, en spécifiant STGM_TRANSACTED et en mode lecture seule, en spécifiant STGM_READ, il est possible de modifier l’objet de stockage retourné. Par exemple, il est possible d’appeler IStorage ::CreateStream. Toutefois, il n’est pas possible de valider ces modifications en appelant IStorage ::Commit. Par conséquent, de telles modifications seront perdues.
Il n’est pas valide d’utiliser les indicateurs STGM_CREATE, STGM_DELETEONRELEASE ou STGM_CONVERT dans le paramètre grfMode pour cette fonction.
Pour prendre en charge le mode simple d’enregistrement d’un objet de stockage sans sous-stockage, la fonction StgOpenStorageEx accepte l’une des deux combinaisons d’indicateurs suivantes comme modes valides dans le paramètre grfMode :
STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE
STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE
Pour prendre en charge le mode direct à écriture unique, multilecteur, la première combinaison d’indicateurs est le paramètre grfMode valide pour l’enregistreur. La deuxième combinaison d’indicateurs est valide pour les lecteurs.
STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE
STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE
Pour plus d’informations sur le mode simple et les modes à écriture unique/à plusieurs lecteurs, consultez Constantes STGM.
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 |