Obsługa błędów (BITS)

Istnieją dwa typy błędów do obsługi w aplikacji. Pierwszy błąd to nieudane wywołanie metody. Każda metoda zwraca wartość HRESULT. Strona referencyjna dla każdej metody identyfikuje zwracane wartości, które najprawdopodobniej wygeneruje. Aby uzyskać dodatkowe wartości zwracane, zapoznaj się z wartościami zwracanymi BITS . Aby uzyskać tekst komunikatu skojarzony z wartością zwracaną, wywołaj metodę IBackgroundCopyManager::GetErrorDescription.

Drugim typem błędu do obsługi jest zadanie, którego stan przechodzi do BG_JOB_STATE_ERROR lub BG_JOB_STATE_TRANSIENT_ERROR. Aby pobrać informacje związane z tymi typami błędów, wywołaj metodę IBackgroundCopyJob::GetError. Metoda zwraca wskaźnik interfejsu IBackgroundCopyError zawierający informacje używane do określenia przyczyny błędu. Możesz również otrzymywać powiadomienie o błędzie, rejestrując się, aby otrzymywać powiadomienia o zdarzeniach. Aby uzyskać szczegółowe informacje, zobacz sekcję Rejestrowanie wywołania zwrotnego COM.

Usługa BITS traktuje każde zadanie jako atomowe. Jeśli jeden z plików w zadaniu generuje błąd, zadanie pozostaje w stanie błędu, dopóki błąd nie zostanie rozwiązany. W związku z tym nie można usunąć pliku, który powoduje błąd z zadania. Jeśli jednak błąd jest spowodowany niedostępnym serwerem lub nieprawidłowym plikiem zdalnym, możesz wywołać metodę IBackgroundCopyJob3::ReplaceRemotePrefix lub IBackgroundCopyFile2::SetRemoteName, aby zidentyfikować nową nazwę serwera lub pliku.

Po określeniu przyczyny błędu wykonaj jedną z następujących opcji:

• Anuluj zadanie, wywołując metodę IBackgroundCopyJob::Cancel.
• W przypadku zadania pobierania wywołaj metodę IBackgroundCopyJob::Complete, aby zapisać pliki, które zostały pomyślnie przeniesione przed wystąpieniem błędu.
• Napraw błąd i wywołaj metodę IBackgroundCopyJob::Resume, aby zakończyć zadanie.

W przypadku zadania typu "upload-reply" sprawdź wartość elementu członkowskiego BytesTotal w strukturze BG_JOB_REPLY_PROGRESS, aby określić, czy błąd wystąpił w części przesyłania czy odpowiedzi zadania. Wystąpił błąd podczas przekazywania, jeśli wartość jest BG_SIZE_UNKNOWN.

W poniższym przykładzie pokazano, jak pobrać wskaźnik interfejsu IBackgroundCopyError. W przykładzie przyjęto założenie, że wskaźnik interfejsu IBackgroundCopyJob jest prawidłowy.

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