IBackgroundCopyJob::AddFile-Methode (bits.h)

Artikel
02/23/2024

Fügt dem Auftrag eine einzelne Datei hinzu.

Syntax

HRESULT AddFile(
  [in] LPCWSTR RemoteUrl,
  [in] LPCWSTR LocalName
);

Parameter

[in] RemoteUrl

Null-beendete Zeichenfolge, die den Namen der Datei auf dem Server enthält. Informationen zum Angeben des Remotenamens finden Sie im Abschnitt RemoteName-Member und Hinweise der BG_FILE_INFO-Struktur .

[in] LocalName

Null-beendete Zeichenfolge, die den Namen der Datei auf dem Client enthält. Informationen zum Angeben des lokalen Namens finden Sie im Abschnitt LocalName-Member und Hinweise der BG_FILE_INFO-Struktur .

Rückgabewert

Diese Methode gibt die folgenden HRESULT-Werte sowie andere zurück.

Rückgabecode	Beschreibung
S_OK	Die Datei wurde dem Auftrag erfolgreich hinzugefügt.
BG_E_TOO_MANY_FILES	Uploadaufträge dürfen nur eine Datei enthalten. Sie können dem Auftrag keine weitere Datei hinzufügen.
BG_E_TOO_MANY_FILES_IN_JOB	Die Einstellung MaxFilesPerJob Gruppenrichtlinie bestimmt, wie viele Dateien ein Auftrag enthalten kann. Das Hinzufügen der Datei zum Auftrag überschreitet den MaxFilesPerJob-Grenzwert.
E_INVALIDARG	Dieser Fehler kann aus einem der folgenden Gründe angezeigt werden: Der lokale Dateiname oder der Remotedateiname ist ungültig. Der Remotedateiname verwendet ein nicht unterstütztes Protokoll. Der lokale Dateiname wurde mithilfe eines relativen Pfads angegeben.
E_ACCESSDENIED	Der Benutzer verfügt nicht über die Berechtigung zum Schreiben in das angegebene Verzeichnis auf dem Client.

Hinweise

Um einem Auftrag mehrere Dateien gleichzeitig hinzuzufügen, rufen Sie die IBackgroundCopyJob::AddFileSet-Methode auf. Es ist effizienter, die AddFileSet-Methode aufzurufen, wenn einem Auftrag mehrere Dateien hinzugefügt werden, als die AddFile-Methode in einer Schleife aufzurufen. Weitere Informationen finden Sie unter Hinzufügen von Dateien zu einem Auftrag.

Um einem Auftrag, aus dem BITS Datenbereiche aus der Datei herunterlädt, eine Datei hinzuzufügen, rufen Sie die IBackgroundCopyJob3::AddFileWithRanges-Methode auf.

Uploadaufträge dürfen nur eine Datei enthalten. Wenn Sie eine zweite Datei hinzufügen, gibt die Methode BG_E_TOO_MANY_FILES zurück.

Bei Downloads garantiert BITS, dass die Version einer Datei (basierend auf Der Dateigröße und dem Datum, nicht dem Inhalt), die übertragen wird, konsistent ist; es garantiert jedoch nicht, dass eine Gruppe von Dateien konsistent ist. Wenn BITS sich beispielsweise gerade beim Herunterladen der zweiten von zwei Dateien im Auftrag zu dem Zeitpunkt befindet, zu dem die Dateien auf dem Server aktualisiert werden, startet BITS den Download der zweiten Datei neu. Die erste Datei wird jedoch nicht erneut heruntergeladen.

Beachten Sie, dass Sie eine neue URL für jede neue Version der Datei erstellen sollten, wenn Sie die Datei besitzen, die vom Server heruntergeladen wird. Wenn Sie dieselbe URL für neue Versionen der Datei verwenden, können einige Proxyserver veraltete Daten aus ihrem Cache bereitstellen, da sie nicht beim ursprünglichen Server überprüfen, ob die Datei veraltet ist.

Bei Uploads generiert BITS einen Fehler, wenn sich die lokale Datei ändert, während die Datei übertragen wird. Der Fehlercode wird BG_E_FILE_CHANGED und der Kontext BG_ERROR_CONTEXT_LOCAL_FILE.

BITS überträgt die Dateien innerhalb eines Auftrags sequenziell. Wenn beim Übertragen einer Datei ein Fehler auftritt, wechselt der Auftrag in einen Fehlerzustand, und es werden keine weiteren Dateien innerhalb des Auftrags verarbeitet, bis der Fehler behoben ist.

Standardmäßig kann ein Benutzer einem Auftrag bis zu 200 Dateien hinzufügen. Dieser Grenzwert gilt nicht für Administratoren oder Dienstkonten. Um die Standardeinstellung zu ändern, legen Sie die Gruppenrichtlinien MaxFilesPerJob fest.

Vor Windows Vista: Es gibt keine Begrenzung für die Anzahl von Dateien, die ein Benutzer einem Auftrag hinzufügen kann.

Informationen zur Skalierbarkeit finden Sie unter Bewährte Methoden bei der Verwendung von BITS.

Beispiele

Ein Beispiel zum Hinzufügen einer einzelnen Datei zu einem Auftrag finden Sie unter Hinzufügen von Dateien zu einem Auftrag.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP
Unterstützte Mindestversion (Server)	Windows Server 2003
Zielplattform	Windows
Kopfzeile	bits.h
Bibliothek	Bits.lib
DLL	QmgrPrxy.dll