IBackgroundCopyJob3::AddFileWithRanges-Methode (bits2_0.h)

Fügt einem Downloadauftrag eine Datei hinzu und gibt die Bereiche der Datei an, die Sie herunterladen möchten.

Syntax

HRESULT AddFileWithRanges(
  [in] LPCWSTR          RemoteUrl,
  [in] LPCWSTR          LocalName,
  [in] DWORD            RangeCount,
  [in] BG_FILE_RANGE [] Ranges
);

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 .

Ab BITS 3.0 wird das SMB-Protokoll für Bereiche nicht unterstützt.

BITS 2.5 und 2.0: BITS unterstützt das SMB-Protokoll für Bereiche.

[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 .

[in] RangeCount

Anzahl der Elemente in Bereichen.

[in] Ranges

Array einer oder mehrerer BG_FILE_RANGE Strukturen, die die bereiche angeben, die heruntergeladen werden sollen. Geben Sie keine doppelten oder überlappenden Bereiche an.

Rückgabewert

Diese Methode gibt die folgenden Rückgabewerte sowie andere rückgabewerte zurück.

Hinweise

Die Bereiche werden in der angegebenen Reihenfolge in die LocalName-Datei geschrieben. Wenn Ranges beispielsweise bytes 100-199, 900-999 und 400-499 der Remotedatei identifiziert, ist die lokale Datei 300 Bytes lang. Bytes 0-99 der lokalen Datei enthalten Bytes 100-199 der Remotedatei, Bytes 100-199 der lokalen Datei enthalten Bytes 900-999 der Remotedatei und Bytes 200-299 der lokalen Datei enthalten Bytes 400-499 der Remotedatei.

In der folgenden Tabelle sind mögliche Fehlercodes aufgeführt, die auftreten können, nachdem Sie den Auftrag fortgesetzt haben. Diese Fehler versetzen den Auftrag in den BG_JOB_STATE_ERROR Zustand.

BITS garantiert, 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 beispielsweise gerade die zweite von zwei Dateien im Auftrag zum Zeitpunkt der Aktualisierung der Dateien auf dem Server herunter lädt, startet BITS den Download der zweiten Datei neu. Die erste Datei wird jedoch nicht erneut heruntergeladen.

Standardmäßig kann ein Benutzer bis zu 500 Bereiche für eine Datei hinzufügen. Dieser Grenzwert gilt nicht für Administratoren oder Dienstkonten. Um die Standardeinstellung zu ändern, legen Sie die MaxRangesPerFile-Gruppenrichtlinie fest.

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

Für eine bessere Leistung bei Windows BranchCache-fähigen Dateiübertragungen wird empfohlen, die Bereichslänge auf mindestens 400 Byte festzulegen.

Beispiele

Im folgenden Beispiel wird gezeigt, wie die AddFileWithRanges-Methode aufgerufen wird , um die Bereiche einer herunterzuladenden Datei anzugeben. Im Beispiel wird davon ausgegangen, dass die IBackgroundCopyJob-VariablepJob gültig ist.

    IBackgroundCopyJob *pJob;
    IBackgroundCopyJob3 *pJob3 = NULL;
    DWORD dwRangeCount = 3;                  //Number of elements in Ranges.
    BG_FILE_RANGE Ranges[] = {24, 17,        //Array of ranges to download (offset and length).
                              111, BG_LENGTH_TO_EOF,
                              83, 7
                             };

    //Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
    //interface pointer. The IBackgroundCopyJob3 interface contains the AddFileWithRanges method.
    hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
    if (S_OK == hr)
    {
         pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.

         //Add a file to the job and specify the ranges from the file to download.
         hr = pJob3->AddFileWithRanges(L"<REMOTENAMEGOESHERE>", L"<LOCALNAMEGOESHERE>",
                                       dwRangeCount, Ranges);
         if (FAILED(hr))
         {
              //Handle error.
              //Returns E_NOTIMPL if not a download job.
              //Returns E_INVALIDARG if dwRangeCount is zero or the remote or local name is invalid.
              //Returns BG_E_INVALID_RANGE if one of the ranges is invalid.
              //Returns BG_E_OVERLAPPING_RANGES if you specify overlapping or duplicate ranges.
         }

          pJob3->Release(); //Release the interface if you are done with it.
     }
    else
    {
         //Handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
         //running on the computer is less than BITS 2.0.
    }

Anforderungen

Weitere Informationen

BG_FILE_RANGE

IBackgroundCopyFile2::GetFileRanges

IBackgroundCopyJob3

IBackgroundCopyJob::AddFile