Hinzufügen von Dateien zu einem Auftrag

Ein Auftrag enthält mindestens eine Datei, die Sie übertragen möchten. Verwenden Sie eine der folgenden Methoden, um einem Auftrag Dateien hinzuzufügen:

IBackgroundCopyJob::AddFile

Fügt einem Auftrag eine einzelne Datei hinzu.

IBackgroundCopyJob::AddFileSet

Fügt einem Auftrag mindestens eine Datei hinzu. Wenn Sie mehrere Dateien hinzufügen, ist es effizienter, diese Methode aufzurufen, als die AddFile-Methode in einer Schleife aufzurufen.

IBackgroundCopyJob3::AddFileWithRanges

Fügt einem Auftrag eine einzelne Datei hinzu. Verwenden Sie diese Methode, wenn Sie Datenbereiche aus einer Datei herunterladen möchten. Sie können diese Methode nur für Downloadaufträge verwenden.

Wenn Sie einem Auftrag eine Datei hinzufügen, geben Sie den Remotenamen und den lokalen Namen der Datei an. Ausführliche Informationen zum Format der lokalen Und Remotedateinamen finden Sie in der BG_FILE_INFO-Struktur .

Ein Uploadauftrag darf nur eine Datei enthalten. Die Methoden IBackgroundCopyJob::AddFile und IBackgroundCopyJob::AddFileSet geben BG_E_TOO_MANY_FILES zurück, wenn Sie versuchen, einem Uploadauftrag mehrere Dateien hinzuzufügen. Wenn Sie mehrere Dateien hochladen müssen, sollten Sie eine CAB- oder ZIP-Datei verwenden.

Bei Downloadaufträgen begrenzt BITS die Anzahl der Dateien, die ein Benutzer einem Auftrag hinzufügen kann, auf 200 Dateien und die Anzahl der Bereiche für eine Datei auf 500 Bereiche. Diese Grenzwerte gelten nicht für Administratoren oder Dienste. Informationen zum Ändern dieser Standardgrenzwerte finden Sie unter Gruppenrichtlinien.

Der Besitzer des Auftrags oder ein Benutzer mit Administratorrechten kann dem Auftrag jederzeit Dateien hinzufügen, bevor die IBackgroundCopyJob::Complete-Methode oder die IBackgroundCopyJob::Cancel-Methode aufgerufen wird.

Wenn Sie den Remotenamen der Datei ändern müssen, nachdem Sie die Datei dem Auftrag hinzugefügt haben, können Sie die IBackgroundCopyJob3::ReplaceRemotePrefix-Methode oder die IBackgroundCopyFile2::SetRemoteName-Methode aufrufen. Verwenden Sie die ReplaceRemotePrefix-Methode , um den Serverteil des Remotenamens zu ändern, wenn der Server nicht verfügbar ist, oder um Roamingbenutzern eine Verbindung mit dem nächstgelegenen Server zu ermöglichen. Verwenden Sie die SetRemoteName-Methode , um das Protokoll zu ändern, das zum Übertragen der Datei verwendet wird, oder um den Dateinamen oder Pfad zu ändern.

BITS erstellt eine temporäre Datei im Zielverzeichnis und verwendet die temporäre Datei für die Dateiübertragung. Um den temporären Dateinamen abzurufen, rufen Sie die IBackgroundCopyFile3::GetTemporaryName-Methode auf. BITS ändert den temporären Dateinamen in den Namen der Zieldatei, wenn Sie die Complete-Methode aufrufen. BITS gibt beim Erstellen der temporären Datei keinen Sicherheitsdeskriptor an (die Datei erbt die ACL-Informationen aus dem Zielverzeichnis). Wenn die übertragenen Daten vertraulich sind, sollte die Anwendung eine geeignete ACL für das Zielverzeichnis angeben, um unbefugten Zugriff zu verhindern.

Um die Besitzer- und ACL-Informationen mit der übertragenen Datei beizubehalten, rufen Sie die IBackgroundCopyJob3::SetFileACLFlags-Methode auf.

Der Besitzer des Auftrags (der Benutzer, der den Auftrag erstellt hat, oder der Administrator, der den Besitz des Auftrags übernommen hat ) muss über Berechtigungen für die Datei auf dem Server und dem Client verfügen. Um beispielsweise eine Datei herunterzuladen, muss der Benutzer über Leseberechtigungen auf dem Server und Schreibberechtigungen für das lokale Verzeichnis auf dem Client verfügen.

Das folgende Beispiel zeigt, wie sie dem Auftrag eine einzelne Datei hinzufügen. Im Beispiel wird davon ausgegangen, dass der IBackgroundCopyJob-Schnittstellenzeiger pJob gültig ist.

HRESULT hr;
IBackgroundCopyJob* pJob;

//Replace parameters with variables that contain valid paths.
hr = pJob->AddFile(L"https://ServerName/Path/File.Ext", L"d:\\Path\\File.Ext");
if (SUCCEEDED(hr))
{
  //Do something.
}

Im folgenden Beispiel wird gezeigt, wie dem Auftrag mehrere Dateien hinzugefügt werden. Im Beispiel wird davon ausgegangen, dass der IBackgroundCopyJob-Schnittstellenzeiger pJob gültig ist und die lokalen namen und die Remotenamen aus einer Liste in der Benutzeroberfläche stammen.

HRESULT hr;
IBackgroundCopyJob* pJob;
BG_FILE_INFO* paFiles = NULL;
ULONG idx = 0;
ULONG nCount = 0;            //Set to the number of files to add to the job.
LPWSTR pszLocalName = NULL;  //Comes from the list in the user interface.
LPWSTR pszRemoteName = NULL; //Comes from the list in the user interface.

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