Fonction StgCreateDocfile (coml2api.h)

La fonction StgCreateDocfile crée un objet de stockage de fichiers composés à l’aide de l’implémentation de fichier composé fournie par COM pour l’interface IStorage .

Note Les applications doivent utiliser la nouvelle fonction StgCreateStorageEx au lieu de StgCreateDocfile pour tirer parti des fonctionnalités de stockage structuré améliorées. Cette fonction, StgCreateDocfile, existe toujours pour la compatibilité avec Windows 2000.

 

Syntaxe

HRESULT StgCreateDocfile(
  [in]  const WCHAR *pwcsName,
  [in]  DWORD       grfMode,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Paramètres

[in] pwcsName

Pointeur vers un nom de chaîne Unicode terminé par null pour le fichier composé en cours de création. Il est passé 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 composé temporaire est alloué avec un nom unique.

[in] grfMode

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 traité 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 traité.

[in] reserved

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

[out] ppstgOpen

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

Valeur retournée

StgCreateDocfile 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

La fonction StgCreateDocfile crée un objet de stockage à l’aide de l’implémentation de fichier composé fournie par COM pour l’interface IStorage . Le nom du fichier composé ouvert peut être récupéré en appelant la méthode IStorage ::Stat .

StgCreateDocfile 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 la procédure à suivre. Pour plus d’informations, consultez Constantes STGM.

Si le fichier composé est ouvert en mode traité (le paramètre grfMode spécifie STGM_TRANSACTED) et qu’un fichier portant ce nom existe déjà, le fichier existant n’est pas modifié tant que toutes les modifications en suspens ne sont pas validées. Si le processus appelant n’a pas accès en écriture au fichier existant (en raison du contrôle d’accès dans le système de fichiers), le paramètre grfMode peut uniquement spécifier STGM_READ et non STGM_WRITE ou STGM_READWRITE. Le nouveau fichier composé ouvert résultant peut toujours être écrit dans, mais une opération de validation ultérieure échoue (en mode traité, les autorisations d’écriture sont appliquées au moment de la validation).

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é. Cela peut être utilisé par les applications qui nécessitent une implémentation de fichier composé avec plusieurs flux et aucun stockage. Le mode simple ne prend pas en charge toutes les méthodes sur IStorage. Pour plus d’informations, consultez Constantes STGM.

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 dans le répertoire du système de fichiers dans lequel le fichier composé est créé. Si STGM_TRANSACTED n’est pas spécifié et si STGM_CREATE est spécifié, un fichier existant portant le même nom est détruit avant la création du nouveau fichier.

StgCreateDocfile peut être utilisé 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, probablement un nom qui n’a aucun sens pour l’utilisateur. L’appelant est responsable de la suppression du fichier temporaire lorsqu’il a terminé, sauf si STGM_DELETEONRELEASE a été spécifié pour le paramètre grfMode .

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

Constantes STGM

StgCreateDocFileOnILockBytes

StgCreateStorageEx