Méthode IStorage ::CopyTo (objidl.h)
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)
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 |