Méthode IRootStorage ::SwitchToFile (objidl.h)

Article
02/29/2024

La méthode SwitchToFile copie le fichier actuel associé à l’objet de stockage dans un nouveau fichier. Le nouveau fichier est ensuite utilisé pour l’objet de stockage et toutes les modifications non validées.

Syntaxe

HRESULT SwitchToFile(
  LPOLESTR pszFile
);

Paramètres

pszFile

Pointeur vers une chaîne terminée par null qui spécifie le nom de fichier du nouveau fichier. Il ne peut pas s’agir du nom d’un fichier existant. Si la valeur est NULL, cette méthode crée un fichier temporaire avec un nom unique, et vous pouvez appeler IStorage ::Stat pour récupérer le nom du fichier temporaire.

Valeur retournée

Cette méthode peut retourner l’une de ces valeurs.

Code de retour	Description
S_OK	Le fichier a été copié avec succès.
STG_E_MEDIUMFULL	Le fichier n’a pas été copié en raison d’un espace insuffisant sur le périphérique de stockage.
STG_E_ACCESSDENIED	Le fichier n’a pas été copié, car l’appelant n’est pas autorisé à accéder au périphérique de stockage.
STG_E_INVALIDPOINTER	Le fichier n’a pas été copié, car le pointeur pszFile n’est pas valide.
STG_E_FILEALREADYEXISTS	Le fichier n’a pas été copié, car le nouveau nom de fichier (pszFile) pointe vers un fichier existant.

Remarques

La méthode IRootStorage ::SwitchToFile copie le fichier associé à l’objet de stockage. Un conteneur COM appelle SwitchToFile pour effectuer un enregistrement complet sur un fichier en situation de faible mémoire. En règle générale, cette opération est effectuée uniquement après l’échec d’une opération d’enregistrement normale et complète (c’est-à-dire, enregistrer dans un fichier temporaire, supprimer le fichier d’origine, renommer le fichier temporaire) avec une erreur E_OUTOFMEMORY.

Il est erroné d’appeler la méthode SwitchToFile si l’objet de stockage ou tout élément qu’il contient a été marshalé dans un autre processus. Avant d’appeler SwitchToFile, le conteneur doit appeler la méthode IPersistStorage ::HandsOffStorage pour tout élément dans l’objet de stockage chargé ou en cours d’exécution. La méthode HandsOffStorage force l’élément à relâcher ses pointeurs de stockage et à passer en mode de stockage pratique. Le conteneur doit également libérer tous les pointeurs vers les flux ou les stockages contenus dans ce stockage racine. Une fois l’opération d’enregistrement complète terminée, le conteneur retourne les éléments contenus en mode de stockage normal.

Remarques aux implémenteurs

Si vous implémentez vos propres objets de stockage, les méthodes IRootStorage (y compris QueryInterface, AddRef et Release) ne doivent pas consommer de handles de mémoire ou de fichier supplémentaires.

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	objidl.h
Bibliothèque	Uuid.lib
DLL	Ole32.dll