Méthode IStorage ::CopyTo (objidl.h)

  • Article

La méthode CopyTo copie l’intégralité du contenu d’un objet de stockage ouvert vers un autre objet de stockage.

Syntaxe

HRESULT CopyTo(
  [in] DWORD     ciidExclude,
  [in] const IID *rgiidExclude,
  [in] SNB       snbExclude,
  [in] IStorage  *pstgDest
);

Paramètres

[in] ciidExclude

Nombre d’éléments dans le tableau pointé vers rgiidExclude. Si rgiidExclude a la valeur NULL, ciidExclude est ignoré.

[in] rgiidExclude

Tableau d’identificateurs d’interface (IID) que l’appelant connaît et ne souhaite pas copier, ou que l’objet de stockage ne prend pas en charge, mais dont l’état sera copié par la suite explicitement. Le tableau peut inclure IStorage, indiquant que seuls les objets de flux doivent être copiés, et IStream, indiquant que seuls les objets de stockage doivent être copiés. Une longueur de tableau de zéro indique que seul l’état exposé par l’objet IStorage doit être copié ; toutes les autres interfaces de l’objet doivent être ignorées. La transmission de la valeur NULL indique que toutes les interfaces de l’objet doivent être copiées.

[in] snbExclude

Bloc de nom de chaîne (reportez-vous à SNB) qui spécifie un bloc d’objets de stockage ou de flux qui ne doivent pas être copiés dans la destination. Ces éléments ne sont pas créés à la destination. Si IID_IStorage se trouve dans le tableau rgiidExclude , ce paramètre est ignoré. Ce paramètre peut avoir la valeur NULL.

[in] pstgDest

Pointeur vers l’objet de stockage ouvert dans lequel cet objet de stockage doit être copié. L’objet de stockage de destination peut être une implémentation différente de l’interface IStorage de l’objet de stockage source. Par conséquent, IStorage ::CopyTo peut utiliser uniquement des méthodes accessibles au public de l’objet de stockage de destination. Si pstgDest est ouvert en mode traité, il peut être rétabli en appelant sa méthode IStorage ::Revert .

Valeur retournée

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

Code de retour Description
S_OK L’objet de stockage a été correctement copié.
E_PENDING Stockage asynchrone uniquement : une partie ou la totalité des données à copier n’est actuellement pas disponible.
STG_E_ACCESSDENIED L’objet de stockage de destination est un enfant de l’objet de stockage source.
STG_E_INSUFFICIENTMEMORY La copie n’a pas été effectuée en raison d’un manque de mémoire.
STG_E_INVALIDPOINTER Le pointeur spécifié pour l’objet de stockage n’était pas valide.
STG_E_INVALIDPARAMETER L’un des paramètres n’était pas valide.
STG_E_TOOMANYOPENFILES La copie n’a pas été effectuée, car il y a trop de fichiers ouverts.
STG_E_REVERTED L’objet de stockage a été invalidé par une opération de restauration au-dessus de lui dans l’arborescence des transactions.
STG_E_MEDIUMFULL La copie n’a pas été effectuée, car le support de stockage est plein.

Remarques

Cette méthode fusionne les éléments contenus dans l’objet de stockage source avec ceux déjà présents dans la destination. La disposition de l’objet de stockage de destination peut différer de l’objet de stockage source.

Le processus de copie est récursif, appelant IStorage ::CopyTo et IStream ::CopyTo sur les éléments imbriqués à l’intérieur de la source.

Lors de la copie d’un flux sur un flux existant portant le même nom, le flux existant est d’abord supprimé, puis remplacé par le flux source. Lors de la copie d’un stockage sur un stockage existant portant le même nom, le stockage existant n’est pas supprimé. Par conséquent, après l’opération de copie, l’IStorage de destination contient des éléments plus anciens, sauf s’ils ont été remplacés par des éléments plus récents portant le même nom.

Un objet de stockage peut exposer d’autres interfaces qu’IStorage, notamment IRootStorage, IPropertyStorage ou IPropertySetStorage. Le paramètre rgiidExclude permet d’exclure l’une ou l’ensemble de ces interfaces supplémentaires de l’opération de copie.

Un appelant avec une copie plus récente ou plus efficace d’un objet de sous-stockage ou de flux existant peut vouloir exclure les versions actuelles de ces objets de l’opération de copie. Les paramètres snbExclude et rgiidExclude fournissent deux façons d’exclure des objets de stockage des stockages ou des flux existants.

Remarque à l’attention des appelants

La façon la plus courante d’utiliser la méthode IStorage ::CopyTo consiste à copier tout de la source vers la destination, comme dans la plupart des opérations d’enregistrement complet et d’enregistrement en tant que.

L’exemple de code suivant montre comment tout copier de l’objet de stockage source vers l’objet de stockage de destination.

pstg->CopyTo(0, Null, Null, pstgDest)
Note Pour compacter un fichier de document, appelez CopyTo sur l’objet de stockage racine et copiez vers un nouvel 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 objidl.h
Bibliothèque Uuid.lib
DLL Ole32.dll

Voir aussi

IStorage - Implémentation de fichiers composés

IStorage ::MoveElementTo

IStorage ::Revert