Bagikan melalui

Mendaftarkan Panggilan Balik COM

  • Artikel

Alih-alih melakukan polling untuk perubahan status pekerjaan, Anda dapat mendaftar untuk menerima pemberitahuan saat status pekerjaan berubah. Untuk menerima pemberitahuan, Anda harus menerapkan antarmuka IBackgroundCopyCallback2. Antarmuka berisi metode berikut yang dipanggil BITS, tergantung pada pendaftaran Anda:

Untuk contoh yang mengimplementasikan antarmuka IBackgroundCopyCallback2, lihat kode contoh dalam topik antarmuka IBackgroundCopyCallback.

Antarmuka IBackgroundCopyCallback2 menyediakan pemberitahuan saat file ditransfer. Biasanya, Anda menggunakan metode ini untuk memvalidasi file, sehingga file tersedia untuk diunduh oleh serekan; jika tidak, file tidak tersedia untuk rekan-rekan sampai Anda memanggil metode IBackgroundCopyJob::Complete . Untuk memvalidasi file, panggil metode IBackgroundCopyFile3::SetValidationState.

Ada dua metode untuk mendaftarkan panggilan balik COM: mendaftarkan objek panggilan balik, atau mendaftarkan ID kelas panggilan balik. Menggunakan objek panggilan balik lebih sederhana dan overhead lebih rendah; menggunakan CLSID panggilan balik lebih dapat diandalkan, tetapi lebih rumit. Anda dapat mendaftar baik, baik, atau tidak sama sekali – BITS akan menggunakan objek panggilan balik jika ada dan masih dapat dipanggil, dan akan kembali untuk membuat instans objek baru berdasarkan ID kelas yang disediakan jika gagal.

Mendaftarkan Objek Panggilan Balik

Untuk mendaftarkan implementasi Anda dengan BITS, panggil metode IBackgroundCopyJob::SetNotifyInterface. Untuk menentukan metode panggilan BITS mana, panggil metode IBackgroundCopyJob::SetNotifyFlags.

Antarmuka pemberitahuan menjadi tidak valid ketika aplikasi Anda berakhir; BITS tidak mempertahankan antarmuka pemberitahuan. Akibatnya, proses inisialisasi aplikasi Anda harus mendaftarkan pekerjaan yang ada yang ingin Anda terima pemberitahuannya. Jika Anda perlu mengambil informasi status dan kemajuan yang terjadi sejak terakhir kali aplikasi Anda dijalankan, polling untuk informasi status dan kemajuan selama inisialisasi aplikasi.

Sebelum keluar, aplikasi Anda harus menghapus penunjuk antarmuka panggilan balik (SetNotifyInterface(NULL)). Lebih efisien untuk menghapus pointer panggilan balik daripada membiarkan BITS menemukan bahwa itu tidak lagi valid.

Perhatikan bahwa jika lebih dari satu aplikasi memanggil metode SetNotifyInterface untuk mengatur antarmuka pemberitahuan untuk pekerjaan tersebut, aplikasi terakhir untuk memanggil metode SetNotifyInterface adalah yang akan menerima pemberitahuan—aplikasi lain tidak akan menerima pemberitahuan.

Contoh berikut menunjukkan cara mendaftar untuk pemberitahuan. Contoh mengasumsikan penunjuk antarmuka IBackgroundCopyJob valid. Untuk detail tentang kelas contoh CNotifyInterface yang digunakan dalam contoh berikut, lihat antarmuka IBackgroundCopyCallback.

HRESULT hr;
IBackgroundCopyJob* pJob;
CNotifyInterface *pNotify = new CNotifyInterface();

if (pNotify)
{
    hr = pJob->SetNotifyInterface(pNotify);
    if (SUCCEEDED(hr))
    {
        hr = pJob->SetNotifyFlags(BG_NOTIFY_JOB_TRANSFERRED | 
                                  BG_NOTIFY_JOB_ERROR );
    }
    pNotify->Release();
    pNotify = NULL;

    if (FAILED(hr))
    {
        //Handle error - unable to register callbacks.
    }
}

Mendaftarkan Callback CLSID

Untuk mendaftarkan CLSID panggilan balik dengan BITS, panggil metode IBackgroundCopyJob5::SetProperty dengan BITS_JOB_PROPERTY_NOTIFICATION_CLSID PropertyId. Untuk menentukan metode panggilan BITS mana, panggil metode IBackgroundCopyJob::SetNotifyFlags.

Anda harus memastikan bahwa pemberitahuan CLSID terdaftar ke server COM yang tidak diproses sebelum mendaftarkan CLSID dengan pekerjaan BITS. Menerapkan server COM secara signifikan lebih rumit daripada menentukan dan meneruskan objek panggilan balik, tetapi menawarkan beberapa keuntungan penting. Server COM memungkinkan BITS untuk mempertahankan hubungan antara pekerjaan BITS dan kode aplikasi Anda di seluruh reboot sistem, dan untuk pekerjaan besar atau berumur panjang. Server COM juga memungkinkan aplikasi Anda untuk dimatikan sepenuhnya sementara BITS terus menjalankan transfer di latar belakang, yang dapat meningkatkan penggunaan baterai, CPU, dan memori sistem.

Untuk memberikan pemberitahuan yang telah Anda daftarkan untuk diterima, BITS terlebih dahulu mencoba memanggil metode yang sesuai dari objek panggilan balik yang ada yang mungkin telah Anda lampirkan. Jika tidak ada objek yang ada, atau jika objek yang ada telah terputus (biasanya sebagai akibat dari penghentian aplikasi Anda), BITS akan memanggil CoCreateInstance menggunakan CLSID pemberitahuan untuk membuat instans objek panggilan balik baru, dan akan menggunakan objek tersebut untuk panggilan balik lebih lanjut sampai terputus atau digantikan oleh panggilan baru ke IBackgroundCopyJob:: SetNotifyInterface.

Tidak seperti objek panggilan balik, CLSID panggilan balik dipertahankan bersama pekerjaan BITS yang sesuai jika layanan BITS atau sistem dimatikan dan dimulai ulang. Aplikasi Anda dapat menghapus CLSID pemberitahuan yang ditetapkan sebelumnya sebelum keluar (atau di lain waktu) dengan meneruskan CLSID pemberitahuan baru GUID_NULL, tetapi aplikasi Anda mungkin lebih suka membiarkan CLSID pemberitahuan terdaftar jika aplikasi Anda telah mendaftar untuk memulai COM sebagai respons terhadap permintaan CoCreateInstance untuk CLSID Anda. Perhatikan bahwa jika lebih dari satu aplikasi mengatur panggilan properti BITS_JOB_PROPERTY_NOTIFICATION_CLSID , CLSID terakhir yang akan diatur adalah yang akan digunakan BITS untuk membuat instans objek panggilan balik - CLSID lainnya tidak akan dibuat. Demikian pula, jika satu aplikasi mendaftarkan CLSID dan yang lain mendaftarkan objek panggilan balik, aturan biasa untuk objek panggilan balik yang lebih diutamakan berlaku, dan CLSID tidak akan digunakan kecuali objek panggilan balik dibersihkan atau menjadi terputus.

Contoh berikut menunjukkan cara mendaftar untuk pemberitahuan CLSID. Contoh mengasumsikan penunjuk antarmuka IBackgroundCopyJob5 valid, dan bahwa aplikasi Anda telah terdaftar sebagai Server COM di luar proses yang mengimplementasikan kelas CNotifyInterface. Untuk detail tentang kelas contoh CNotifyInterface yang digunakan dalam contoh berikut, lihat antarmuka IBackgroundCopyCallback.

HRESULT hr; 
IBackgroundCopyJob5* job; 
BITS_JOB_PROPERTY_VALUE propertyValue; 
propertyValue.ClsID = __uuidof(CNotifyInterface); 

hr = job->SetProperty(BITS_JOB_PROPERTY_NOTIFICATION_CLSID, propertyValue); 
if (SUCCEEDED(hr)) 
{ 
    hr = job->SetNotifyFlags(BG_NOTIFY_JOB_TRANSFERRED |  
                             BG_NOTIFY_JOB_ERROR); 
} 

if (FAILED(hr)) 
{ 
    // Handle error - unable to register callbacks. 
}