Méthode IVssBackupComponents ::AddNewTarget (vsbackup.h)

Article
03/03/2024

La méthode AddNewTarget est utilisée par un demandeur lors d’une opération de restauration pour indiquer que l’application de sauvegarde prévoit de restaurer des fichiers à un nouvel emplacement.

Syntaxe

HRESULT AddNewTarget(
  [in] VSS_ID             writerId,
  [in] VSS_COMPONENT_TYPE ct,
  [in] LPCWSTR            wszLogicalPath,
  [in] LPCWSTR            wszComponentName,
  [in] LPCWSTR            wszPath,
  [in] LPCWSTR            wszFileName,
  [in] bool               bRecursive,
  [in] LPCWSTR            wszAlternatePath
);

Paramètres

[in] writerId

Identificateur global unique (GUID) de la classe writer contenant les fichiers qui doivent recevoir une nouvelle cible.

[in] ct

Identifie le type du composant. Reportez-vous à la documentation pour VSS_COMPONENT_TYPE pour connaître les valeurs de retour possibles.

[in] wszLogicalPath

Chaîne de caractères larges terminées par null contenant le chemin logique du composant contenant les fichiers qui doivent recevoir une nouvelle cible de restauration. Pour plus d’informations, consultez Chemin d’accès logique des composants.

La valeur de la chaîne contenant le chemin logique utilisé ici doit être la même que celle utilisée lorsque le composant a été ajouté au jeu de sauvegarde à l’aide d’IVssBackupComponents ::AddComponent.

Le chemin logique peut être NULL.

Il n’existe aucune restriction sur les caractères qui peuvent apparaître dans un chemin logique non NULL .

[in] wszComponentName

Chaîne de caractères larges terminées par null contenant le nom du composant contenant les fichiers qui doivent recevoir une nouvelle cible de restauration.

La chaîne ne doit pas avoir la valeur NULL et doit contenir le même nom de composant que celui utilisé lorsque le composant a été ajouté au jeu de sauvegarde à l’aide d’IVssBackupComponents ::AddComponent.

Il n’existe aucune restriction sur les caractères qui peuvent apparaître dans un chemin logique non NULL .

[in] wszPath

Chaîne de caractères larges terminée par null contenant le nom du répertoire ou de la hiérarchie de répertoires contenant les fichiers à recevoir une nouvelle cible de restauration.

Le répertoire peut être un répertoire local sur l’ordinateur VSS ou un répertoire de partage de fichiers sur un serveur de fichiers distant.

Le chemin d’accès peut contenir des variables d’environnement (par exemple, %SystemRoot%) mais ne peut pas contenir de caractères génériques. Les chemins UNC sont pris en charge.

Il n’est pas obligatoire que le chemin se termine par une barre oblique inverse (« »). Il appartient aux applications qui récupèrent ces informations de case activée.

[in] wszFileName

Chaîne de caractères larges terminée par null contenant la spécification de fichier des fichiers à recevoir une nouvelle cible de restauration.

Une spécification de fichier ne peut pas contenir de spécifications de répertoire (par exemple, aucune barre oblique inverse), mais peut contenir le ? et * caractères génériques.

[in] bRecursive

Boolean indiquant si seuls les fichiers du répertoire défini par wszPath et correspondant à la spécification de fichier fournie par wszFileName doivent recevoir une nouvelle cible de restauration, ou si tous les fichiers de la hiérarchie définie par wszPath et correspondant à la spécification de fichier fournie par wszFileName doivent recevoir une nouvelle cible de restauration.

Pour plus d’informations sur la traversée des dossiers montés, consultez Utilisation des dossiers montés et répare des points.

[in] wszAlternatePath

Chaîne de caractères larges terminée par null contenant le chemin complet du nouveau répertoire cible de restauration.

Le répertoire peut être un répertoire local sur l’ordinateur VSS ou un répertoire de partage de fichiers sur un serveur de fichiers distant.

Les chemins UNC sont pris en charge.

Valeur retournée

Voici les codes de retour valides pour cette méthode.

Valeur	Signification
S_OK	Ajout réussi de la nouvelle cible de restauration.
E_INVALIDARG	L’une des valeurs de paramètre n’est pas valide.
E_OUTOFMEMORY	L’appelant n’a pas de mémoire ou d’autres ressources système.
VSS_E_BAD_STATE	L’objet de composants de sauvegarde n’est pas initialisé ou cette méthode a été appelée lors d’une opération de restauration.
VSS_E_INVALID_XML_DOCUMENT	Le document XML n’est pas valide. Consultez le journal des événements pour plus d’informations. Pour plus d’informations, consultez Gestion des événements et des erreurs sous VSS.
VSS_E_OBJECT_NOT_FOUND	Le composant n’existe pas ou le chemin d’accès et la spécification de fichier ne correspondent pas à une spécification de composant et de fichier dans le composant.
VSS_E_UNEXPECTED	Erreur inattendue. Le code d’erreur est enregistré dans le fichier journal des erreurs. Pour plus d’informations, consultez Gestion des événements et des erreurs sous VSS. Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge tant que Windows Server 2008 R2 et Windows 7. E_UNEXPECTED est utilisé à la place.

Remarques

Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP et Windows Server 2003 : Les partages de fichiers distants ne sont pas pris en charge tant que Windows 8 et Windows Server 2012.

Le nom du composant spécifié en tant qu’argument de AddNewTarget (wszComponentName) doit correspondre à un composant qui a déjà été ajouté au document Composants de sauvegarde.

Par conséquent, wszComponentName peut être le nom de n’importe quel composant explicitement inclus dans le document Composants de sauvegarde.

L’ajout d’une nouvelle cible pour le fichier dans un sous-composant doit être effectué à l’aide du nom du composant qui définit le jeu de composants contenant le sous-composant.

Lors de la spécification d’un fichier ou de fichiers dont la cible de restauration est modifiée, un demandeur doit s’assurer que la combinaison de chemin d’accès, de spécification de fichier et d’indicateur de récursivité (wszPath, wszFileSpec et bRecursive, respectivement) fournie à AddNewTarget doit correspondre à celle de l’un des jeux de fichiers ajoutés à un composant à l’aide d’IVssCreateWriterMetadata ::AddFilesToFileGroup, IVssCreateWriterMetadata ::AddDatabaseFiles, ou IVssCreateWriterMetadata ::AddDatabaseLogFiles.

Lorsqu’un demandeur appelle AddNewTarget, il doit le faire avant d’appeler IVssBackupComponents ::P reRestore. Pour plus d’informations, consultez Vue d’ensemble de la préparation de la restauration.

Les informations de chemin d’accès et de descripteur de fichier peuvent être obtenues à partir du document de métadonnées writer à l’aide de l’objet IVssWMFiledesc retourné par IVssWMComponent ::GetFile, IVssWMComponent ::GetDatabaseFile ou IVssWMComponent ::GetDatabaseLogFile. L’objet IVssWMComponent est obtenu à partir de Writer Metadata Document par la méthode IVssExamineWriterMetadata ::GetComponent.

Les enregistreurs peuvent déterminer si les fichiers ont été restaurés à de nouveaux emplacements à l’aide des méthodes IVssComponent ::GetNewTargetCount et IVssComponent ::GetNewTarget .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	vsbackup.h (inclure VsBackup.h, Vss.h, VsWriter.h)
Bibliothèque	VssApi.lib