Tratamento de erros (BITS)

Há dois tipos de erros para lidar em seu aplicativo. O primeiro erro é uma chamada de método com falha. Cada método retorna um HRESULT valor. A página de referência para cada método identifica os valores de retorno que é mais provável 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étodoIBackgroundCopyManager::GetErrorDescription.

O segundo tipo de erro a ser tratado é um trabalho cujo estado transita 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 da tarefa. O método retorna um ponteiro de interface IBackgroundCopyError que contém informações que tu usas 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.

Os BITS consideram cada tarefa como atómica. 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 da tarefa. No entanto, se o erro for causado pelo servidor não estar disponível ou por um arquivo remoto inválido, você pode chamar o IBackgroundCopyJob3::ReplaceRemotePrefix ou método 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 BytesTotal membro da estrutura BG_JOB_REPLY_PROGRESS para determinar se o erro ocorreu na parte de upload ou resposta do trabalho. O erro ocorreu durante o carregamento se o valor for BG_SIZE_UNKNOWN.

O exemplo a seguir mostra como recuperar um ponteiro de interface IBackgroundCopyError. O exemplo pressupõe que o ponteiro de 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.
}