IVssBackupComponents::AddNewTarget-Methode (vsbackup.h)

Artikel
08/27/2023

Die AddNewTarget-Methode wird von einem Anforderer während eines Wiederherstellungsvorgangs verwendet, um anzugeben, dass die Sicherungsanwendung die Wiederherstellung von Dateien an einem neuen Speicherort plant.

Syntax

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
);

Parameter

[in] writerId

Globally Unique Identifier (GUID) der Writer-Klasse, die die Dateien enthält, die ein neues Ziel empfangen sollen.

[in] ct

Gibt den Typ der Komponente an. Mögliche Rückgabewerte finden Sie in der Dokumentation für VSS_COMPONENT_TYPE .

[in] wszLogicalPath

Breite Null-Zeichenfolge, die den logischen Pfad der Komponente enthält, die die Dateien enthält, die ein neues Wiederherstellungsziel empfangen sollen. Weitere Informationen finden Sie unter Logisches Pathing von Komponenten.

Der Wert der Zeichenfolge, die den hier verwendeten logischen Pfad enthält, sollte der gleiche sein wie beim Hinzufügen der Komponente zum Sicherungssatz mithilfe von IVssBackupComponents::AddComponent.

Der logische Pfad kann NULL sein.

Es gibt keine Einschränkungen für die Zeichen, die in einem logischen Pfad ohne NULL angezeigt werden können.

[in] wszComponentName

Breite Zeichenfolge mit Null-Beendigung, die den Namen der Komponente enthält, die die Dateien enthält, die ein neues Wiederherstellungsziel empfangen sollen.

Die Zeichenfolge sollte nicht NULL sein und denselben Komponentennamen enthalten, der beim Hinzufügen der Komponente zum Sicherungssatz mithilfe von IVssBackupComponents::AddComponent verwendet wurde.

Es gibt keine Einschränkungen für die Zeichen, die in einem logischen Pfad ohne NULL angezeigt werden können.

[in] wszPath

Breite NULL-Zeichenfolge, die den Namen des Verzeichnisses oder der Verzeichnishierarchie enthält, die die Dateien enthält, die ein neues Wiederherstellungsziel empfangen sollen.

Das Verzeichnis kann ein lokales Verzeichnis auf dem VSS-Computer oder ein Dateifreigabeverzeichnis auf einem Remotedateiserver sein.

Der Pfad kann Umgebungsvariablen (z. B. %SystemRoot%) enthalten, aber keine Feldhalterzeichen enthalten. UNC-Pfade werden unterstützt.

Es ist nicht erforderlich, dass der Pfad mit einem umgekehrten Schrägstrich ("") endet. Anwendungen, die diese Informationen abrufen, müssen überprüft werden.

[in] wszFileName

Breite Null-Zeichenfolge, die die Dateispezifikation der Dateien enthält, um ein neues Wiederherstellungsziel zu empfangen.

Eine Dateispezifikation kann keine Verzeichnisspezifikationen enthalten (z. B. keine umgekehrten Schrägstriche), kann aber den enthalten. und * Platzhalterzeichen.

[in] bRecursive

Boolescher Wert, der angibt, ob nur die Dateien in dem von wszPath definierten Verzeichnis und der von wszFileName bereitgestellten Dateispezifikation ein neues Wiederherstellungsziel erhalten sollen oder ob alle Dateien in der von wszPath definierten Hierarchie und übereinstimmend mit der von wszFileName bereitgestellten Dateispezifikation ein neues Wiederherstellungsziel erhalten sollen.

Informationen zum Durchlaufen eingebundener Ordner finden Sie unter Arbeiten mit eingebundenen Ordnern und Analysepunkten.

[in] wszAlternatePath

Breite Null-Zeichenfolge mit Null-Endung, die den vollqualifizierten Pfad des neuen Wiederherstellungszielverzeichnisses enthält.

Das Verzeichnis kann ein lokales Verzeichnis auf dem VSS-Computer oder ein Dateifreigabeverzeichnis auf einem Remotedateiserver sein.

UNC-Pfade werden unterstützt.

Rückgabewert

Im Folgenden sind die gültigen Rückgabecodes für diese Methode aufgeführt.

Wert	Bedeutung
S_OK	Das neue Wiederherstellungsziel wurde erfolgreich hinzugefügt.
E_INVALIDARG	Einer der Parameterwerte ist ungültig.
E_OUTOFMEMORY	Der Aufrufer verfügt nicht über Arbeitsspeicher oder andere Systemressourcen.
VSS_E_BAD_STATE	Das Sicherungskomponentenobjekt wird nicht initialisiert, oder diese Methode wurde während eines Wiederherstellungsvorgangs aufgerufen.
VSS_E_INVALID_XML_DOCUMENT	Das XML-Dokument ist ungültig. Überprüfen Sie das Ereignisprotokoll auf Details. Weitere Informationen finden Sie unter Ereignis- und Fehlerbehandlung unter VSS.
VSS_E_OBJECT_NOT_FOUND	Die Komponente ist nicht vorhanden, oder die Pfad- und Dateispezifikation stimmen nicht mit einer Komponente und Dateispezifikation in der Komponente überein.
VSS_E_UNEXPECTED	Unerwarteter Fehler. Der Fehlercode wird in der Fehlerprotokolldatei protokolliert. Weitere Informationen finden Sie unter Ereignis- und Fehlerbehandlung unter VSS. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird erst unter Windows Server 2008 R2 und Windows 7 unterstützt. stattdessen wird E_UNEXPECTED verwendet.

Hinweise

Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP und Windows Server 2003: Remotedateifreigaben werden erst unterstützt, wenn Windows 8 und Windows Server 2012.

Der als Argument für AddNewTarget (wszComponentName) angegebene Komponentenname muss mit einer Komponente übereinstimmen, die bereits dem Dokument Sicherungskomponenten hinzugefügt wurde.

Daher kann wszComponentName der Name einer beliebigen Komponente sein, die explizit im Dokument Sicherungskomponenten enthalten ist.

Das Hinzufügen eines neuen Ziels für die Datei in einer Unterkomponente muss unter Verwendung des Namens der Komponente erfolgen, die den Komponentensatz definiert, der den Unterkomponentensatz enthält.

Wenn Sie eine Datei oder Dateien angeben, die ihr Wiederherstellungsziel ändern sollen, ein Anforderer muss sicherstellen, dass die Kombination aus Pfad, Dateispezifikation und Rekursionsflag (wszPath, wszFileSpec bzw . bRecursive) für AddNewTarget mit der einer der Dateisätze übereinstimmen muss, die einer Komponente mithilfe von IVssCreateWriterMetadata::AddFilesToFileGroup, IVssCreateWriterMetadata::AddDatabaseFiles hinzugefügt wurden, oder IVssCreateWriterMetadata::AddDatabaseLogFiles.

Wenn ein Anforderer AddNewTarget aufruft, muss dies vor dem Aufruf von IVssBackupComponents::P reRestore erfolgen. Weitere Informationen finden Sie unter Übersicht über die Vorbereitung der Wiederherstellung.

Pfad- und Dateideskriptorinformationen können aus dem Writer Metadata Document mithilfe des IVssWMFiledesc-Objekts abgerufen werden, das von IVssWMComponent::GetFile, IVssWMComponent::GetDatabaseFile oder IVssWMComponent::GetDatabaseLogFile zurückgegeben wird. Das IVssWMComponent-Objekt wird von der IVssExamineWriterMetadata::GetComponent-Methode aus Writer Metadata Document abgerufen.

Writer können feststellen, ob Dateien an neuen Speicherorten wiederhergestellt wurden, indem sie die Methoden IVssComponent::GetNewTargetCount und IVssComponent::GetNewTarget verwenden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	vsbackup.h (einschließlich VsBackup.h, Vss.h, VsWriter.h)
Bibliothek	VssApi.lib