StgCreateStorageEx, fonction (coml2api.h)

Article
08/22/2023

La fonction StgCreateStorageEx crée un objet de stockage à l’aide d’une implémentation fournie pour les interfaces IStorage ou IPropertySetStorage . Pour ouvrir un fichier existant, utilisez plutôt la fonction StgOpenStorageEx .

Les applications écrites pour Windows 2000, Windows Server 2003 et Windows XP doivent utiliser StgCreateStorageEx plutôt que StgCreateDocfile pour tirer parti des fonctionnalités améliorées de Stockage structuré Windows 2000 et Windows XP.

Syntaxe

HRESULT StgCreateStorageEx(
  [in]  const WCHAR          *pwcsName,
  [in]  DWORD                grfMode,
  [in]  DWORD                stgfmt,
  [in]  DWORD                grfAttrs,
  [in]  STGOPTIONS           *pStgOptions,
  [in]  PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]  REFIID               riid,
  [out] void                 **ppObjectOpen
);

Paramètres

[in] pwcsName

Pointeur vers le chemin du fichier à créer. Il est transmis sans interprétation au système de fichiers. Il peut s’agir d’un nom relatif ou null. Si la valeur est NULL, un fichier temporaire est alloué avec un nom unique. Si la valeur n’est pas NULL, la taille de chaîne ne doit pas dépasser MAX_PATH caractères.

Windows 2000 : Contrairement à la fonction CreateFile , vous ne pouvez pas dépasser la limite de MAX_PATH à l’aide du préfixe « \? ».

[in] grfMode

Valeur qui spécifie le mode d’accès à utiliser lors de l’ouverture du nouvel objet de stockage. Pour plus d’informations, consultez Constantes STGM. Si l’appelant spécifie le mode transactionné avec STGM_CREATE ou STGM_CONVERT, le remplacement ou la conversion a lieu 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 transactionné.

[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 .

Valeurs des paramètres	Signification
STGFMT_DOCFILE	0 ou FILE_FLAG_NO_BUFFERING. Pour plus d’informations, 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	Doit être égal à 0.

[in] pStgOptions

Le paramètre pStgOptions est valide uniquement si le paramètre stgfmt a la valeur STGFMT_DOCFILE. Si le paramètre stgfmt est défini sur STGFMT_DOCFILE, pStgOptions pointe vers la structure STGOPTIONS , qui spécifie les fonctionnalités de l’objet de stockage, telles que la taille de secteur. Ce paramètre peut être NULL, ce qui crée un objet de stockage avec une taille de secteur par défaut de 512 octets. Si la valeur n’est pas NULL, le membre ulSectorSize doit être défini sur 512 ou 4096. Si la valeur est 4096, STGM_SIMPLE ne peut pas être spécifié dans le paramètre grfMode . Le membre usVersion doit être défini avant d’appeler StgCreateStorageEx. Pour plus d’informations, consultez STGOPTIONS.

[in] pSecurityDescriptor

Permet de définir les listes de contrôle d’accès lors de la création du fichier. Si ce n’est pas null, doit être un pointeur vers la structure SECURITY_ATTRIBUTES . Pour plus d’informations sur la définition de listes de contrôle d’accès sur des fichiers, consultez CreateFile .

Windows Server 2003, Windows 2000 Server, Windows XP et Windows 2000 Professionnel : La valeur doit être NULL.

[in] riid

Valeur qui spécifie l’identificateur d’interface (IID) du pointeur d’interface à retourner. Cet IID peut être destiné à l’interface IStorage ou à l’interface IPropertySetStorage .

[out] ppObjectOpen

Pointeur vers une variable de pointeur d’interface qui reçoit un pointeur pour une interface sur le nouvel objet de stockage ; contient NULL si l’opération a échoué.

Valeur retournée

Cette fonction peut également retourner toutes les erreurs de système de fichiers ou les 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

Lorsqu’une application modifie son fichier, elle crée généralement une copie de l’original. La fonction StgCreateStorageEx est un moyen de créer une copie. Cette fonction fonctionne indirectement avec l’API de duplication du système de fichiers EFS (Encrypting File System). Lorsque vous utilisez cette fonction, vous devez définir les options pour le stockage de fichiers dans la structure STGOPTIONS .

StgCreateStorageEx est un sur-ensemble de la fonction StgCreateDocfile et doit être utilisé par le nouveau code. Les améliorations futures apportées au stockage structuré seront exposées via la fonction StgCreateStorageEx . Pour plus d’informations sur les plateformes prises en charge, consultez la section Configuration requise suivante.

La fonction StgCreateStorageEx crée un objet de stockage à l’aide de l’une des implémentations de stockage structuré fournies par le système. Cette fonction peut être utilisée pour obtenir un
Implémentation de fichier composé IStorage, implémentation de fichier composé IPropertySetStorage ou pour obtenir une implémentation NTFS IPropertySetStorage.

Lorsqu’un fichier est créé, l’implémentation de stockage utilisée dépend de l’indicateur que vous spécifiez et du type de lecteur sur lequel le fichier est stocké. Pour plus d’informations, consultez l’énumération STGFMT .

StgCreateStorageEx crée le fichier s’il n’existe pas. S’il existe, l’utilisation des indicateurs STGM_CREATE, STGM_CONVERT et STGM_FAILIFTHERE dans le paramètre grfMode indique comment procéder. Pour plus d’informations sur ces valeurs, consultez Constantes STGM. Il n’est pas valide, en mode direct, de spécifier le mode STGM_READ dans le paramètre grfMode (le mode direct est indiqué en ne spécifiant pas l’indicateur STGM_TRANSACTED). Cette fonction ne peut pas être utilisée pour ouvrir un fichier existant ; utilisez la fonction StgOpenStorageEx à la place.

Vous pouvez utiliser la fonction StgCreateStorageEx pour accéder au stockage racine d’un document de stockage structuré ou au stockage de jeux de propriétés de tout fichier qui prend en charge les jeux de propriétés. Consultez la documentation STGFMT pour plus d’informations sur les ID pris en charge pour différentes valeurs STGFMT .

Lorsqu’un fichier est créé 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 de IPropertySetStorage-NTFS.

Si un fichier composé est créé en mode transactionné (en spécifiant STGM_TRANSACTED) et en mode lecture seule (en spécifiant STGM_READ), il est possible d’apporter des modifications à 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, ces modifications seront perdues.

La spécification de STGM_SIMPLE permet une implémentation beaucoup plus rapide d’un objet de fichier composé dans un cas limité, mais fréquemment utilisé, impliquant des applications qui nécessitent une implémentation de fichier composé avec plusieurs flux et aucun stockage. Pour plus d’informations, consultez Constantes STGM. Il n’est pas valide de spécifier cette STGM_TRANSACTED si STGM_SIMPLE est spécifié.

Le mode simple ne prend pas en charge toutes les méthodes sur IStorage. Plus précisément, en mode simple, les méthodes IStorage prises en charge sont CreateStream, Commit et SetClass , ainsi que les méthodes COM IUnknown de QueryInterface, AddRef et Release. En outre, SetElementTimes est pris en charge avec un nom NULL , ce qui permet aux applications de définir des heures sur un stockage racine. Toutes les autres méthodes d’IStorage retournent STG_E_INVALIDFUNCTION.

Si le paramètre grfMode spécifie STGM_TRANSACTED et qu’aucun fichier n’existe encore avec le nom spécifié par le paramètre pwcsName , le fichier est créé immédiatement. Dans un système de fichiers à accès contrôlé, l’appelant doit disposer d’autorisations d’écriture pour le répertoire du système de fichiers dans lequel le fichier composé est créé. Si STGM_TRANSACTED n’est pas spécifié et STGM_CREATE est spécifié, un fichier existant portant le même nom est détruit avant de créer le fichier.

Vous pouvez également utiliser StgCreateStorageEx pour créer un fichier composé temporaire en transmettant une valeur NULL pour le paramètre pwcsName . Toutefois, ces fichiers sont temporaires uniquement dans le sens où ils ont un nom unique fourni par le système, un nom qui n’a probablement aucun sens pour l’utilisateur. L’appelant est responsable de la suppression du fichier temporaire lorsqu’il a terminé de l’utiliser, sauf si STGM_DELETEONRELEASE a été spécifié pour le paramètre grfMode . Pour plus d’informations sur ces indicateurs, consultez Constantes STGM.

Configuration requise


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