Manipulando erros (BITS)

Há dois tipos de erros para manipular em seu aplicativo. O primeiro erro é uma chamada de método com falha. Cada método retorna um valor HRESULT . A página de referência para cada método identifica os valores de retorno que é mais provável de gerar. Para obter valores de retorno adicionais, consulte Valores de retorno do BITS. Para obter o texto da mensagem associado ao valor de retorno, chame o método IBackgroundCopyManager::GetErrorDescription.

O segundo tipo de erro a ser manipulado é um trabalho cujo estado faz a transição para BG_JOB_STATE_ERROR ou BG_JOB_STATE_TRANSIENT_ERROR. Para recuperar informações relacionadas a esses tipos de erros, chame o método IBackgroundCopyJob::GetError do trabalho. O método retorna um ponteiro de interface IBackgroundCopyError que contém informações que você usa para determinar a causa do erro. Você também pode receber notificação de erro registrando-se para receber notificação de evento. Para obter detalhes, consulte Registrando um retorno de chamada COM.

A BITS considera cada trabalho atômico. Se um dos arquivos no trabalho gerar um erro, o trabalho permanecerá em um estado de erro até que o erro seja resolvido. Assim, você não pode excluir o arquivo que está causando o erro do trabalho. No entanto, se o erro for causado pelo servidor não estar disponível ou um arquivo remoto inválido, você pode chamar o método IBackgroundCopyJob3::ReplaceRemotePrefix ou IBackgroundCopyFile2::SetRemoteName para identificar um novo servidor ou nome de arquivo.

Depois de determinar a causa do erro, execute uma das seguintes opções:

• Cancele o trabalho chamando o método IBackgroundCopyJob::Cancel.
• Para um trabalho de download, chame o método IBackgroundCopyJob::Complete para salvar os arquivos transferidos com êxito antes que o erro ocorresse.
• Corrija o erro e chame o método IBackgroundCopyJob::Resume para concluir o trabalho.

Para um trabalho de upload-resposta, verifique o valor do membro BytesTotal da estrutura BG_JOB_REPLY_PROGRESS para determinar se o erro ocorreu na parte de upload ou resposta do trabalho. O erro ocorreu no carregamento se o valor for BG_SIZE_UNKNOWN.

O exemplo a seguir mostra como recuperar um ponteiro de interface IBackgroundCopyError. O exemplo assume que o ponteiro da interface IBackgroundCopyJob é válido.

HRESULT hr = 0;
HRESULT hrError = 0;
IBackgroundCopyJob* pJob;
IBackgroundCopyError* pError = NULL;
IBackgroundCopyFile* pFile = NULL;
WCHAR* pszDescription = NULL;
WCHAR* pszRemoteName = NULL;
BG_ERROR_CONTEXT Context;

hr = pJob->GetError(&pError);
if (SUCCEEDED(hr))
{
  //Retrieve the HRESULT associated with the error. The context tells you
  //where the error occurred, for example, in the transport, queue manager, the 
  //local file, or the remote file.
  pError->GetError(&Context, &hrError);  

  //Retrieve a description associated with the HRESULT value.
  hr = pError->GetErrorDescription(LANGIDFROMLCID(GetThreadLocale()), &pszDescription);
  if (SUCCEEDED(hr))
  {
    if (BG_ERROR_CONTEXT_REMOTE_FILE == Context)
    {
      hr = pError->GetFile(&pFile);  
      if (SUCCEEDED(hr))
      {
        hr = pFile->GetRemoteName(&pszRemoteName);
        if (SUCCEEDED(hr))
        {
          //Do something with the information.
          CoTaskMemFree(pszRemoteName);
        }
        pFile->Release();
      }
    }
    CoTaskMemFree(pszDescription);
  }
  pError->Release();
}
else
{
  //Error information is not available.
}