Método IBackgroundCopyJob3::AddFileWithRanges (bits2_0.h)

Artículo
02/26/2024

Agrega un archivo a un trabajo de descarga y especifica los intervalos del archivo que desea descargar.

Sintaxis

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

Parámetros

[in] RemoteUrl

Cadena terminada en NULL que contiene el nombre del archivo en el servidor. Para obtener información sobre cómo especificar el nombre remoto, vea la sección Miembro RemoteName y Comentarios de la estructura de BG_FILE_INFO .

A partir de BITS 3.0, el protocolo SMB no es compatible con los intervalos.

BITS 2.5 y 2.0: BITS admite el protocolo SMB para rangos.

[in] LocalName

Cadena terminada en NULL que contiene el nombre del archivo en el cliente. Para obtener información sobre cómo especificar el nombre local, vea la sección Miembro LocalName y Comentarios de la estructura de BG_FILE_INFO .

[in] RangeCount

Número de elementos de Ranges.

[in] Ranges

Matriz de una o varias estructuras de BG_FILE_RANGE que especifican los intervalos que se van a descargar. No especifique intervalos duplicados o superpuestos.

Valor devuelto

Este método devuelve los siguientes valores devueltos, así como otros.

Código devuelto	Descripción
S_OK	Correcto
E_INVALIDARG	Puede recibir este error por uno de los siguientes motivos: El parámetro RangeCount es cero; debe especificar uno o varios intervalos. El nombre de archivo local o remoto no es válido. El nombre de archivo remoto usa un protocolo no admitido. El nombre de archivo local se especificó mediante una ruta de acceso relativa.
E_NOTIMPL	No se puede llamar a este método para cargar o responder trabajos; llame solo a este método para descargar trabajos.
E_ACCESSDENIED	El usuario no tiene permiso para escribir en el directorio especificado en el cliente.
BG_E_INVALID_RANGE	Uno de los intervalos no es válido. Por ejemplo, InitialOffset se establece en BG_LENGTH_TO_EOF.
BG_E_OVERLAPPING_RANGES	No se pueden especificar intervalos duplicados o superpuestos. Nota Los intervalos se ordenan por el desplazamiento del valor, no por la longitud. Si se especifican intervalos que tienen el mismo desplazamiento, pero están en orden inverso, se devolverá este error. Por ejemplo, si se especifican 100.5 y 100.0 en ese orden, no podrá agregar el archivo al trabajo.
BG_E_TOO_MANY_RANGES_IN_FILE	El valor de maxRangesPerFile directiva de grupo determina cuántos intervalos puede especificar para un archivo. Al agregar estos intervalos, se supera el límite de MaxRangesPerFile.
BG_E_INVALID_STATE	El estado del trabajo no puede ser BG_JOB_STATE_CANCELLED ni BG_JOB_STATE_ACKNOWLEDGED.

Comentarios

Los intervalos se escriben en el archivo LocalName en el orden especificado. Por ejemplo, si Ranges identifica bytes 100-199, 900-999 y 400-499 del archivo remoto, el archivo local tendrá 300 bytes de longitud. Los bytes 0-99 del archivo local contendrán bytes 100-199 del archivo remoto, los bytes 100-199 del archivo local contendrán bytes 900-999 del archivo remoto y los bytes 200-299 del archivo local contendrán bytes 400-499 del archivo remoto.

En la tabla siguiente se identifican los posibles códigos de error que se pueden producir después de reanudar el trabajo. Estos errores colocan el trabajo en estado BG_JOB_STATE_ERROR.

Código de error	Descripción
BG_E_INVALID_SERVER_RESPONSE	BITS no admite servidores que consolidan intervalos duplicados o superpuestos.
BG_E_INVALID_RANGE	Uno de los intervalos está fuera de los límites del archivo remoto.
BG_E_INSUFFICIENT_RANGE_SUPPORT	El servidor no admite intervalos.

BITS garantiza que la versión de un archivo (en función del tamaño y la fecha del archivo, no del contenido) de que las transferencias sean coherentes; sin embargo, no garantiza que un conjunto de archivos sea coherente. Por ejemplo, si BITS está en medio de descargar el segundo de dos archivos del trabajo en el momento en que los archivos se actualizan en el servidor, BITS reinicia la descarga del segundo archivo; sin embargo, el primer archivo no se descarga de nuevo.

De forma predeterminada, un usuario puede agregar hasta 500 intervalos para un archivo. Este límite no se aplica a administradores o cuentas de servicio. Para cambiar el valor predeterminado, establezca la directiva de grupo MaxRangesPerFile .

Antes de Windows Vista: No hay ningún límite en el número de archivos que un usuario puede agregar a un trabajo.

Para mejorar el rendimiento en las transferencias de archivos habilitadas para Windows BranchCache, se recomienda establecer la longitud del intervalo en al menos 400 bytes.

Ejemplos

En el ejemplo siguiente se muestra cómo llamar al método AddFileWithRanges para especificar los intervalos de un archivo que se van a descargar. En el ejemplo se supone que la variable IBackgroundCopyJob , pJob, es válida.

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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista, Windows XP con SP2,KB842773 en Windows Server 2003 y Windows XP
Servidor mínimo compatible	Windows Server 2008, Windows Server 2003 con SP1
Plataforma de destino	Windows
Encabezado	bits2_0.h (incluya Bits.h)
Library	Bits.lib
Archivo DLL	BitsPrx3.dll