Método IBackgroundCopyJob3::AddFileWithRanges (bits2_0.h)
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 |
|---|---|
|
Correcto |
|
Puede recibir este error por uno de los siguientes motivos:
|
|
No se puede llamar a este método para cargar o responder trabajos; llame solo a este método para descargar trabajos. |
|
El usuario no tiene permiso para escribir en el directorio especificado en el cliente. |
|
Uno de los intervalos no es válido. Por ejemplo, InitialOffset se establece en BG_LENGTH_TO_EOF. |
|
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.
|
|
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. |
|
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 |