Metodo IBackgroundCopyJob3::AddFileWithRanges (bits2_0.h)

  • Articolo

Aggiunge un file a un processo di download e specifica gli intervalli del file da scaricare.

Sintassi

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

Parametri

[in] RemoteUrl

Stringa con terminazione null contenente il nome del file nel server. Per informazioni sulla specifica del nome remoto, vedere la sezione RemoteName member and Notes della struttura BG_FILE_INFO .

A partire da BITS 3.0, il protocollo SMB non è supportato per gli intervalli.

BITS 2.5 e 2.0: BITS supporta il protocollo SMB per gli intervalli.

[in] LocalName

Stringa con terminazione null contenente il nome del file nel client. Per informazioni sulla specifica del nome locale, vedere la sezione LocalName member and Notes della struttura BG_FILE_INFO .

[in] RangeCount

Numero di elementi in Intervalli.

[in] Ranges

Matrice di una o più strutture BG_FILE_RANGE che specificano gli intervalli da scaricare. Non specificare intervalli duplicati o sovrapposti.

Valore restituito

Questo metodo restituisce i valori restituiti seguenti, nonché altri.

Codice restituito Descrizione
S_OK
 Operazione riuscita
E_INVALIDARG
 È possibile ricevere questo errore per uno dei motivi seguenti:
  • Il parametro RangeCount è zero; è necessario specificare uno o più intervalli.
  • Il nome del file locale o remoto non è valido.
  • Il nome del file remoto usa un protocollo non supportato.
  • Il nome del file locale è stato specificato usando un percorso relativo.
E_NOTIMPL
 Non è possibile chiamare questo metodo per caricare o caricare processi di risposta; chiamare solo questo metodo per scaricare i processi.
E_ACCESSDENIED
 L'utente non dispone dell'autorizzazione per scrivere nella directory specificata nel client.
BG_E_INVALID_RANGE
 Uno degli intervalli non è valido. Ad esempio, InitialOffset è impostato su BG_LENGTH_TO_EOF.
BG_E_OVERLAPPING_RANGES
 Non è possibile specificare intervalli duplicati o sovrapposti.
Nota Gli intervalli vengono ordinati in base all'offset del valore, non alla lunghezza. Se gli intervalli vengono immessi con lo stesso offset, ma sono in ordine inverso, verrà restituito questo errore. Ad esempio, se 100.5 e 100.0 vengono immessi in tale ordine, non sarà possibile aggiungere il file al processo.
 
BG_E_TOO_MANY_RANGES_IN_FILE
 L'impostazione maxRangesPerFile Criteri di gruppo determina il numero di intervalli che è possibile specificare per un file. L'aggiunta di questi intervalli supera il limite MaxRangesPerFile.
BG_E_INVALID_STATE
 Lo stato del processo non può essere BG_JOB_STATE_CANCELLED o BG_JOB_STATE_ACKNOWLEDGED.

Commenti

Gli intervalli vengono scritti nel file LocalName nell'ordine specificato. Ad esempio, se Gli intervalli identificano byte 100-199, 900-999 e 400-499 del file remoto, il file locale sarà di 300 byte. Byte 0-99 del file locale conterrà byte 100-199 del file remoto, byte 100-199 del file locale conterrà byte 900-999 del file remoto e byte 200-299 del file locale conterrà byte 400-499 del file remoto.

La tabella seguente identifica i possibili codici di errore che possono verificarsi dopo aver ripreso il processo. Questi errori inserisce il processo nello stato di BG_JOB_STATE_ERROR.

Codice di errore Descrizione
BG_E_INVALID_SERVER_RESPONSE BITS non supporta i server che consolidano intervalli duplicati o sovrapposti.
BG_E_INVALID_RANGE Uno degli intervalli è esterno ai limiti del file remoto.
BG_E_INSUFFICIENT_RANGE_SUPPORT Il server non supporta gli intervalli.
 

BITS garantisce che la versione di un file (in base alle dimensioni e alla data del file, non al contenuto) sia coerente; tuttavia, non garantisce che un set di file sarà coerente. Ad esempio, se BITS si trova al centro del download del secondo di due file nel processo al momento in cui i file vengono aggiornati nel server, BITS riavvia il download del secondo file; tuttavia, il primo file non viene scaricato di nuovo.

Per impostazione predefinita, un utente può aggiungere fino a 500 intervalli per un file. Questo limite non si applica agli amministratori o agli account di servizio. Per modificare il valore predefinito, impostare i criteri di gruppo MaxRangesPerFile .

Prima di Windows Vista: Non esiste alcun limite al numero di file che un utente può aggiungere a un processo.

Per prestazioni migliori nei trasferimenti di file abilitati per Windows BranchCache, è consigliabile impostare la lunghezza dell'intervallo su almeno 400 byte.

Esempio

Nell'esempio seguente viene illustrato come chiamare il metodo AddFileWithRanges per specificare gli intervalli di un file da scaricare. L'esempio presuppone che la variabile IBackgroundCopyJob , pJob, sia valida.

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

Requisiti

Requisito Valore
Client minimo supportato Windows Vista, Windows XP con SP2,KB842773 in Windows Server 2003 e Windows XP
Server minimo supportato Windows Server 2008, Windows Server 2003 con SP1
Piattaforma di destinazione Windows
Intestazione bits2_0.h (includere Bits.h)
Libreria Bits.lib
DLL BitsPrx3.dll

Vedi anche

BG_FILE_RANGE

IBackgroundCopyFile2::GetFileRanges

IBackgroundCopyJob3

IBackgroundCopyJob::AddFile