Partager via


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 .

Note Pour utiliser les améliorations, toutes les applications Windows 2000, Windows XP et Windows Server 2003 doivent appeler StgOpenStorageEx au lieu de StgOpenStorage. La fonction StgOpenStorage est utilisée pour la compatibilité avec Windows 2000 et les applications antérieures.
 

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.

Note L’ouverture d’un objet de stockage en mode transactionnel en mode lecture et/ou écriture sans refuser les autorisations d’écriture à d’autres personnes (par exemple, le paramètre grfMode spécifie STGM_SHARE_DENY_WRITE) peut prendre du temps, car l’appel StgOpenStorageEx doit créer une copie instantané de l’ensemble de l’objet de stockage.
 

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

Fichiers composés

IStorage

STGFMT

Constantes STGM

STGOPTIONS

StgCreateDocfile

StgCreateStorageEx

StgOpenStorage