StgCreateStorageEx, fonction (coml2api.h)

Article
11/20/2024

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 la fonction StgOpenStorageEx à la place.

Les applications écrites pour Windows 2000, Windows Server 2003 et Windows XP doivent utiliser StgCreateStorageEx au lieu de StgCreateDocfile pour tirer parti des fonctionnalités de stockage structuré Windows 2000 et Windows XP améliorées.

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 passé sans interprétation au système de fichiers. Il peut s’agir d’un nom relatif ou d’une NULL. Si NULL, un fichier temporaire est alloué avec un nom unique. SiNULL, la taille de la 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 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 d’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 du secteur du fichier, spécifiée dans pStgOptions, n’est pas un multiple entier de la taille du secteur physique du disque sous-jacent, cette opération échoue.
Toutes les autres valeurs de stgfmt	Doit être 0.

[in] pStgOptions

Le paramètre pStgOptions n’est valide que si le paramètre stgfmt est défini sur 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 du 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. SiNULL, l'ulSectorSize membre doit être défini sur 512 ou 4096. Si la valeur est 4096, STGM_SIMPLE ne peut pas être spécifiée 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 aux listes de contrôle d’accès d’être définies lors de la création du fichier. S’il n'NULL, doit être un pointeur vers la structure SECURITY_ATTRIBUTES. Consultez createFile pour plus d’informations sur la définition des listes de contrôle d’accès sur les fichiers.

Windows Server 2003, Windows 2000 Server, Windows XP et Windows 2000 Professionnel : 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 en cas d’échec de l’opération.

Valeur de retour

Cette fonction peut également retourner toutes les erreurs système de fichiers ou 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 permet de créer une copie. Cette fonction fonctionne indirectement avec l’API de duplication 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 super-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. Consultez la section Configuration requise suivante pour plus d’informations sur les plateformes prises en charge.

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

Lorsqu’un nouveau 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 indiquent comment continuer. Pour plus d’informations sur ces valeurs, consultez constantes STGM. Il n’est pas valide, en mode direct, pour 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 du jeu de propriétés d’un fichier prenant en charge les jeux de propriétés. Consultez la documentation STGFMT pour plus d’informations sur les ID qui sont 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 IPropertySetStorage-NTFS implémentation.

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 fournit 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ée avec plusieurs flux et aucun stockage. Pour plus d’informations, consultez constantes STGM. Il n’est pas valide de spécifier que STGM_TRANSACTED si STGM_SIMPLE est spécifiée.

Le mode simple ne prend pas en charge toutes les méthodes sur IStorage. Plus précisément, en mode simple, les méthodes de IStorage prises en charge sont CreateStream, Commitet SetClass ainsi que les méthodes com IUnknown de QueryInterface, AddRef et Release. En outre, SetElementTimes est pris en charge avec un nom de NULL , ce qui permet aux applications de définir des heures sur un stockage racine. Toutes les autres méthodes de IStorage retourner 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 contrôlé par l’accès, 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 que STGM_CREATE est spécifié, un fichier existant portant le même nom est détruit avant de créer le nouveau 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 qui est probablement sans signification pour l’utilisateur. L’appelant est chargé de supprimer le fichier temporaire lorsqu’il est terminé, sauf si STGM_DELETEONRELEASE a été spécifié pour le paramètre grfMode. Pour plus d’informations sur ces indicateurs, consultez constantes STGM.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	coml2api.h (include Objbase.h)
bibliothèque	Ole32.lib
DLL	Ole32.dll