Penanganan Kesalahan (BITS)

Ada dua jenis kesalahan yang harus ditangani di aplikasi Anda. Kesalahan pertama adalah panggilan metode yang gagal. Setiap metode mengembalikan nilai HRESULT. Halaman referensi untuk setiap metode mengidentifikasi nilai pengembalian yang kemungkinan besar akan dihasilkan. Untuk nilai pengembalian tambahan, lihat Nilai Pengembalian BITS. Untuk mendapatkan teks pesan yang terkait dengan nilai pengembalian, panggil metodeIBackgroundCopyManager::GetErrorDescription.

Jenis kesalahan kedua yang harus ditangani adalah pekerjaan yang status nya transisi ke BG_JOB_STATE_ERROR atau BG_JOB_STATE_TRANSIENT_ERROR. Untuk mengambil informasi yang terkait dengan jenis kesalahan ini, gunakan metode IBackgroundCopyJob::GetError pada tugas tersebut. Metode ini mengembalikan penunjuk antarmuka IBackgroundCopyError yang berisi informasi yang Anda gunakan untuk menentukan penyebab kesalahan. Anda juga dapat menerima pemberitahuan kesalahan dengan mendaftar untuk menerima pemberitahuan peristiwa. Untuk detailnya, lihat Mendaftarkan panggilan balik COM.

BITS menganggap setiap pekerjaan sebagai atomik. Jika salah satu file dalam pekerjaan menghasilkan kesalahan, pekerjaan tetap dalam status kesalahan hingga kesalahan diselesaikan. Dengan demikian, Anda tidak dapat menghapus file yang menyebabkan error dari tugas. Namun, jika kesalahan disebabkan oleh server yang tidak tersedia atau file jarak jauh yang tidak valid, Anda dapat memanggil metode IBackgroundCopyJob3::ReplaceRemotePrefix atau IBackgroundCopyFile2::SetRemoteName untuk mengidentifikasi server atau nama file baru.

Setelah menentukan penyebab kesalahan, lakukan salah satu opsi berikut:

• Batalkan pekerjaan dengan memanggil metode IBackgroundCopyJob::Cancel.
• Untuk pekerjaan pengunduhan, panggil metode IBackgroundCopyJob::Complete untuk menyimpan file yang berhasil ditransfer sebelum kesalahan terjadi.
• Perbaiki kesalahan dan panggil metode IBackgroundCopyJob::Lanjutkan untuk menyelesaikan pekerjaan.

Untuk pekerjaan pengunggahan balasan, periksa nilai BytesTotal anggota struktur BG_JOB_REPLY_PROGRESS untuk menentukan apakah kesalahan terjadi pada bagian unggahan atau balasan pekerjaan. Kesalahan terjadi pada unggahan jika nilainya BG_SIZE_UNKNOWN.

Contoh berikut menunjukkan cara mengambil penunjuk antarmuka IBackgroundCopyError. Contoh ini mengasumsikan bahwa penunjuk antarmuka IBackgroundCopyJob adalah valid.

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