IBackgroundCopyJob3::AddFileWithRanges-Methode (bits2_0.h)

Fügt eine Datei zu einem Downloadauftrag 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
);

Die 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"- 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 "- 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 herunterzuladenden Bereiche angeben. Geben Sie keine doppelten oder überlappenden Bereiche an.

Rückgabewert

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

Bemerkungen

Die Bereiche werden in die LocalName-Datei in der angegebenen Reihenfolge geschrieben. Wenn Bereiche beispielsweise Bytes 100-199, 900-999 und 400-499 der Remotedatei identifiziert, beträgt die lokale Datei 300 Bytes lang. Byte 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 nach dem Fortsetzen des Auftrags auftreten können. Diese Fehler platzieren den Auftrag im BG_JOB_STATE_ERROR Zustand.

BITS garantiert, dass die Version einer Datei (basierend auf Dateigröße und Datum, nicht Inhalt) konsistent ist; Es garantiert jedoch nicht, dass eine Reihe von Dateien konsistent ist. Wenn BITS sich beispielsweise in der Mitte des Downloads der zweiten von zwei Dateien im Auftrag befindet, wenn die Dateien auf dem Server aktualisiert werden, 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 den Standardwert zu ändern, legen Sie die Gruppenrichtlinie "MaxRangesPerFile " fest.

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

Um eine bessere Leistung bei Windows BranchCache-fähigen Dateiübertragungen zu erzielen, empfiehlt es sich, die Bereichslänge auf mindestens 400 Bytes festzulegen.

Examples

Das folgende Beispiel zeigt, wie die AddFileWithRanges-Methode aufgerufen wird, um die Bereiche einer herunterzuladenden Datei anzugeben. Im Beispiel wird davon ausgegangen, dass die Variable "IBackgroundCopyJob ", pJob, 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

Siehe auch

BG_FILE_RANGE

IBackgroundCopyFile2::GetFileRanges

IBackgroundCopyJob3

IBackgroundCopyJob::AddFile