Método IBackgroundCopyJob3::AddFileWithRanges (bits2_0.h)
Adiciona um arquivo a um trabalho de download e especifica os intervalos do arquivo que você deseja baixar.
Sintaxe
HRESULT AddFileWithRanges(
[in] LPCWSTR RemoteUrl,
[in] LPCWSTR LocalName,
[in] DWORD RangeCount,
[in] BG_FILE_RANGE [] Ranges
);
Parâmetros
[in] RemoteUrl
Cadeia de caracteres terminada em nulo que contém o nome do arquivo no servidor. Para obter informações sobre como especificar o nome remoto, consulte a seção Membro remoteName e Comentários da estrutura BG_FILE_INFO .
A partir do BITS 3.0, não há suporte para o protocolo SMB para intervalos.
BITS 2.5 e 2.0: O BITS dá suporte ao protocolo SMB para intervalos.
[in] LocalName
Cadeia de caracteres terminada em nulo que contém o nome do arquivo no cliente. Para obter informações sobre como especificar o nome local, consulte a seção LocalName member and Remarks da estrutura BG_FILE_INFO .
[in] RangeCount
Número de elementos em Intervalos.
[in] Ranges
Matriz de uma ou mais estruturas de BG_FILE_RANGE que especificam os intervalos a serem baixados. Não especifique intervalos duplicados ou sobrepostos.
Retornar valor
Esse método retorna os seguintes valores retornados, bem como outros.
| Código de retorno | Descrição |
|---|---|
|
Êxito |
|
Você pode receber esse erro por um dos seguintes motivos:
|
|
Você não pode chamar esse método para trabalhos de upload ou upload-reply; chame esse método apenas para trabalhos de download. |
|
O usuário não tem permissão para gravar no diretório especificado no cliente. |
|
Um dos intervalos é inválido. Por exemplo, InitialOffset é definido como BG_LENGTH_TO_EOF. |
|
Você não pode especificar intervalos duplicados ou sobrepostos.
Nota Os intervalos são classificados pelo deslocamento do valor, não pelo comprimento. Se forem inseridos intervalos que tenham o mesmo deslocamento, mas estiverem em ordem inversa, esse erro será retornado. Por exemplo, se 100.5 e 100.0 forem inseridos nessa ordem, você não poderá adicionar o arquivo ao trabalho.
|
|
A configuração de Política de Grupo MaxRangesPerFile determina quantos intervalos você pode especificar para um arquivo. Adicionar esses intervalos excede o limite de MaxRangesPerFile. |
|
O estado do trabalho não pode ser BG_JOB_STATE_CANCELLED ou BG_JOB_STATE_ACKNOWLEDGED. |
Comentários
Os intervalos são gravados no arquivo LocalName na ordem fornecida. Por exemplo, se Ranges identificar bytes 100-199, 900-999 e 400-499 do arquivo remoto, o arquivo local terá 300 bytes de comprimento. Bytes 0-99 do arquivo local conterão bytes 100-199 do arquivo remoto, bytes 100-199 do arquivo local conterão bytes 900-999 do arquivo remoto e bytes 200-299 do arquivo local conterão bytes 400-499 do arquivo remoto.
A tabela a seguir identifica possíveis códigos de erro que podem ocorrer depois que você retoma o trabalho. Esses erros colocam o trabalho no estado BG_JOB_STATE_ERROR.
| Código do erro | Descrição |
|---|---|
| BG_E_INVALID_SERVER_RESPONSE | O BITS não dá suporte a servidores que consolidam intervalos duplicados ou sobrepostos. |
| BG_E_INVALID_RANGE | Um dos intervalos está fora dos limites do arquivo remoto. |
| BG_E_INSUFFICIENT_RANGE_SUPPORT | O servidor não dá suporte a intervalos. |
O BITS garante que a versão de um arquivo (com base no tamanho e na data do arquivo, não no conteúdo) que ele transfere será consistente; no entanto, isso não garante que um conjunto de arquivos seja consistente. Por exemplo, se o BITS estiver no meio do download do segundo de dois arquivos no trabalho no momento em que os arquivos são atualizados no servidor, o BITS reiniciará o download do segundo arquivo; no entanto, o primeiro arquivo não é baixado novamente.
Por padrão, um usuário pode adicionar até 500 intervalos para um arquivo. Esse limite não se aplica a administradores ou contas de serviço. Para alterar o padrão, defina a política de grupo MaxRangesPerFile .
Antes do Windows Vista: Não há limite para o número de arquivos que um usuário pode adicionar a um trabalho.
Para melhorar o desempenho em transferências de arquivos habilitadas para Windows BranchCache, é recomendável definir o comprimento do intervalo como pelo menos 400 bytes.
Exemplos
O exemplo a seguir mostra como chamar o método AddFileWithRanges para especificar os intervalos de um arquivo a ser baixado. O exemplo pressupõe que a variável IBackgroundCopyJob , pJob, seja 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 | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista, Windows XP com SP2,KB842773 no Windows Server 2003 e Windows XP |
| Servidor mínimo com suporte | Windows Server 2008, Windows Server 2003 com SP1 |
| Plataforma de Destino | Windows |
| Cabeçalho | bits2_0.h (inclua Bits.h) |
| Biblioteca | Bits.lib |
| DLL | BitsPrx3.dll |