IBackgroundCopyJob3::AddFileWithRanges-Methode (bits2_0.h)

Artikel
08/22/2023

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.

Rückgabecode	Beschreibung
S_OK	Erfolg
E_INVALIDARG	Dieser Fehler kann aus einem der folgenden Gründe angezeigt werden: Der RangeCount-Parameter ist null; Sie müssen einen oder mehrere Bereiche angeben. Der Name der lokalen oder Remotedatei ist ungültig. Der Remotedateiname verwendet ein nicht unterstütztes Protokoll. Der lokale Dateiname wurde mithilfe eines relativen Pfads angegeben.
E_NOTIMPL	Sie können diese Methode nicht für Upload- oder Upload-Antwortaufträge aufrufen. Rufen Sie diese Methode nur für Downloadaufträge auf.
E_ACCESSDENIED	Der Benutzer verfügt nicht über die Berechtigung zum Schreiben in das angegebene Verzeichnis auf dem Client.
BG_E_INVALID_RANGE	Einer der Bereiche ist ungültig. Beispielsweise ist InitialOffset auf BG_LENGTH_TO_EOF festgelegt.
BG_E_OVERLAPPING_RANGES	Du kannst keine doppelten oder sich überlappenden Bereiche angeben. Hinweis Die Bereiche werden nach dem Offset des Werts und nicht nach der Länge sortiert. Wenn Bereiche eingegeben werden, die denselben Offset aufweisen, sich aber in umgekehrter Reihenfolge befinden, wird dieser Fehler zurückgegeben. Wenn beispielsweise 100.5 und 100.0 in dieser Reihenfolge eingegeben werden, können Sie die Datei nicht zum Auftrag hinzufügen.
BG_E_TOO_MANY_RANGES_IN_FILE	Die Einstellung MaxRangesPerFile Gruppenrichtlinie bestimmt, wie viele Bereiche Sie für eine Datei angeben können. Das Hinzufügen dieser Bereiche überschreitet den MaxRangesPerFile-Grenzwert.
BG_E_INVALID_STATE	Der Status des Auftrags kann nicht BG_JOB_STATE_CANCELLED oder BG_JOB_STATE_ACKNOWLEDGED sein.

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.

Fehlercode	BESCHREIBUNG
BG_E_INVALID_SERVER_RESPONSE	BITS unterstützt keine Server, die doppelte oder sich überlappende Bereiche konsolidieren.
BG_E_INVALID_RANGE	Einer der Bereiche liegt außerhalb der Grenzen der Remotedatei.
BG_E_INSUFFICIENT_RANGE_SUPPORT	Der Server unterstützt keine Bereiche.

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

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista, Windows XP mit SP2, KB842773 unter Windows Server 2003 und Windows XP
Unterstützte Mindestversion (Server)	Windows Server 2008, Windows Server 2003 mit SP1
Zielplattform	Windows
Kopfzeile	bits2_0.h (Bits.h einschließen)
Bibliothek	Bits.lib
DLL	BitsPrx3.dll