IBackgroundCopyJob::AddFileSet-Methode (bits.h)

Artikel
02/28/2024

Fügt einem Auftrag mehrere Dateien hinzu.

Syntax

HRESULT AddFileSet(
  [in] ULONG        cFileCount,
  [in] BG_FILE_INFO *pFileSet
);

Parameter

[in] cFileCount

Anzahl der Elemente in paFileSet.

[in] pFileSet

Array von BG_FILE_INFO Strukturen, die die lokalen Und Remotedateinamen der zu übertragenden Dateien identifizieren.

Uploadaufträge sind auf eine einzelne Datei beschränkt. Wenn das Array mehr als ein Element enthält oder der Auftrag bereits eine Datei enthält, gibt die Methode BG_E_TOO_MANY_FILES zurück.

Rückgabewert

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

Rückgabecode	Beschreibung
S_OK	Dateien wurden dem Auftrag erfolgreich hinzugefügt.
BG_E_TOO_MANY_FILES	Uploadaufträge dürfen nur eine Datei enthalten. Sie können dem Auftrag nicht mehr als eine Datei hinzufügen. Keine der Dateien im Array wurde dem Auftrag hinzugefügt.
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

Es ist effizienter, beim Hinzufügen mehrerer Dateien zu einem Auftrag die AddFileSet-Methode aufzurufen, als die IBackgroundCopyJob::AddFile-Methode in einer Schleife aufzurufen. Um einem Auftrag eine einzelne Datei hinzuzufügen, rufen Sie die AddFile-Methode auf. 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 mehr als eine 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 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

Im folgenden Beispiel wird gezeigt, wie einem Downloadauftrag mehrere Dateien hinzugefügt werden. Im Beispiel wird davon ausgegangen, dass der IBackgroundCopyJob-Schnittstellenzeiger gültig ist.

HRESULT hr;
IBackgroundCopyJob* pJob;
BG_FILE_INFO* paFiles = NULL;
int idx = 0;
int nCount = 0;  //Number of files to add to the job.
LPWSTR pszLocalName = NULL;
LPWSTR pszRemoteName = NULL;

//Set nCount to the number of files to transfer.

//Allocate a block of memory to contain the array of BG_FILE_INFO structures.
//The BG_FILE_INFO structure contains the local and remote names of the 
//file being transferred.
paFiles = (BG_FILE_INFO*) malloc(sizeof(BG_FILE_INFO) * nCount);
if (NULL == paFiles)
{
  //Handle error
}
else
{
  //Add local and remote file name pairs to the memory block. 
  for (idx=0; idx<nCount; idx++)
  {
    //Set pszLocalName to point to an LPWSTR that contains the local name or
    //allocate memory for pszLocalName and copy the local name to pszLocalName.
    (paFiles+idx)->LocalName = pszLocalName;

    //Set pszRemoteName to point to an LPWSTR that contains the remote name or
    //allocate memory for pszRemoteName and copy the remote name to pszRemoteName.
    (paFiles+idx)->RemoteName = pszRemoteName;
  }

  //Add the files to the job.
  hr = pJob->AddFileSet(nCount, paFiles);
  if (SUCCEEDED(hr))
  {
     //Do Something.
  }

  //Free the memory block for the array of BG_FILE_INFO structures. If you allocated
  //memory for the local and remote file names, loop through the array and free the
  //memory for the file names before you free paFiles.
  free(paFiles);
}

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