COM-visszahívás regisztrálása

Ahelyett, hogy lekérdezéseket végezne a feladat állapotváltozásairól, regisztrálhat, hogy értesítést kapjon, amikor a feladat állapota megváltozik. Az értesítés fogadásához implementálnia kell az IBackgroundCopyCallback2 felületet. A felület a következő metódusokat tartalmazza, amelyeket a BITS a regisztrációtól függően hív meg:

• MunkaÁthelyezve
• JobError
• MódosításMunka
• ÁtvitelKész

Az IBackgroundCopyCallback2 felületet implementáló példakód az IBackgroundCopyCallback felület témakörében található.

Az IBackgroundCopyCallback2 felület értesítést küld egy fájl átviteléről. Általában ezzel a módszerrel ellenőrzi a fájlt, hogy a fájl elérhető legyen a partnerek számára a letöltéshez; ellenkező esetben a fájl nem érhető el a társtársak számára, amíg meg nem hívja a IBackgroundCopyJob::Complete metódust. A fájl érvényesítéséhez hívja meg a IBackgroundCopyFile3::SetValidationState metódust.

A COM-visszahívások regisztrálására két módszer létezik: visszahívási objektum regisztrálása vagy visszahívási osztályazonosító regisztrálása. A visszahívási objektum használata egyszerűbb és alacsonyabb többletterhelést jelent; A visszahívási CLSID használata megbízhatóbb, de bonyolultabb. Regisztrálhat mindkettőt vagy egyiket sem – a BITS visszahívási objektumot fog használni, ha létezik, és továbbra is meghívható, és ha ez nem sikerül, a rendszer visszavált egy új objektum példányosítására egy megadott osztályazonosító alapján.

Visszahívási objektum regisztrálása

Az implementáció BITS-ben való regisztrálásához hívja meg a IBackgroundCopyJob::SetNotifyInterface metódust. A BITS-hívások metódusainak megadásához hívja meg a IBackgroundCopyJob::SetNotifyFlagsmetódust.

Az értesítési felület az alkalmazás leállásakor érvénytelenné válik; A BITS nem megőrzi az értesítési felületet. Ennek eredményeképpen az alkalmazás inicializálási folyamatának regisztrálnia kell a meglévő feladatokat, amelyekről értesítést szeretne kapni. Ha az alkalmazás legutóbbi futtatása óta történt állapot- és folyamatinformációkat kell rögzítenie, az alkalmazás inicializálása során lekérdezheti az állapot- és folyamatinformációkat.

A kilépés előtt az alkalmazásnak törölnie kell a visszahívási felület mutatóját (SetNotifyInterface(NULL)). Hatékonyabb törölni a visszahívási mutatót, mint megvárni, hogy a BITS felismerje, hogy az már nem érvényes.

Vegye figyelembe, hogy ha egynél több alkalmazás hívja meg a SetNotifyInterface metódust a feladat értesítési felületének beállításához, akkor a SetNotifyInterface metódust az utolsó alkalmazás hívja meg, amely értesítéseket fog kapni – a többi alkalmazás nem kap értesítéseket.

Az alábbi példa bemutatja, hogyan regisztrálhat értesítésekre. A példa feltételezi, hogy az IBackgroundCopyJob felület mutatója érvényes. Az alábbi példában használt CNotifyInterface példaosztály részleteiért lásd az IBackgroundCopyCallback felületet.

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

Visszahívási CLSID regisztrálása

Ha visszahívási CLSID-t szeretne regisztrálni a BITS-sel, hívja meg a IBackgroundCopyJob5::SetProperty metódust a BITS_JOB_PROPERTY_NOTIFICATION_CLSID PropertyId azonosítóval. A BITS-hívások metódusainak megadásához hívja meg a IBackgroundCopyJob::SetNotifyFlags metódust.

Mielőtt a CLSID-t BITS-feladattal regisztrálja, győződjön meg arról, hogy az értesítés CLSID-azonosítója egy folyamaton kívüli COM-kiszolgálón van regisztrálva. A COM-kiszolgáló implementálása lényegesen bonyolultabb, mint egy visszahívási objektum definiálása és átadása, de számos fontos előnyt kínál. A COM-kiszolgáló lehetővé teszi, hogy a BITS fenntartsa a BITS-feladatok és az alkalmazás kódjának társítását a rendszer újraindításai között, valamint a nagy vagy hosszú élettartamú feladatok esetében. A COM-kiszolgáló lehetővé teszi, hogy az alkalmazás teljesen leálljon, miközben a BITS továbbra is végrehajtja az átviteleket a háttérben, ami javíthatja a rendszer akkumulátor-, PROCESSZOR- és memóriahasználatát.

Az értesítés biztosítása érdekében, amelyre regisztráltak, a BITS először megkísérli meghívni bármelyik, az Ön által csatolt visszahívási objektum meglévő megfelelő módszerét. Ha nincs meglévő objektum, vagy ha a meglévő objektum leválasztódott (általában az alkalmazás leállása miatt), a BITS a notification CLSID használatával hívja meg a CoCreateInstance-t egy új visszahívási objektum példányosítására, és ezt az objektumot fogja használni minden további visszahíváshoz, amíg újra le nem válik, vagy amíg egy új hívással az IBackgroundCopyJob::SetNotifyInterface fel nem váltja.

A visszahívási objektumokkal ellentétben a visszahívási CLSID megmarad a megfelelő BITS-feladat(ok) mellett, ha a BITS szolgáltatás vagy a rendszer le van állítva és újraindul. Előfordulhat, hogy az alkalmazás a kilépés előtt (vagy bármely más időpontban) törli a korábban beállított értesítési CLSID-t a GUID_NULL új értesítési CLSID-jének átadásával, de az alkalmazás inkább a CLSID-t hagyja regisztrálva, ha az alkalmazás regisztrálta, hogy a COM elindítsa azt a CLSID-hez tartozó CoCreateInstance-kérelmekre válaszul. Vegye figyelembe, hogy ha egynél több alkalmazás állítja be a hívásokat a BITS_JOB_PROPERTY_NOTIFICATION_CLSID tulajdonsághoz, az utolsó beállítandó CLSID az, amelyet a BITS a visszahívási objektumok példányosítására használ – a többi CLSID nem lesz példányosítva. Hasonlóképpen, ha az egyik alkalmazás regisztrál egy CLSID-t, a másik pedig egy visszahívási objektumot, a visszahívási objektumra vonatkozó szokásos szabályok érvényesek, és a CLSID csak akkor használható, ha a visszahívási objektum ki van törölve vagy megszakad.

Az alábbi példa bemutatja, hogyan regisztrálhat a CLSID-értesítésekre. A példa feltételezi, hogy az IBackgroundCopyJob5 felület mutatója érvényes, és hogy az alkalmazás már regisztrálva van a CNotifyInterface osztályt implementáló folyamaton kívüli COM-kiszolgálóként. Az alábbi példában használt CNotifyInterface példaosztály részleteiért lásd az IBackgroundCopyCallback felületet.

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