Een COM-callback registreren
In plaats van te wachten op voor wijzigingen in de status van een taak, kunt u zich registreren om een melding te ontvangen zodra de status van de taak verandert. Als u een melding wilt ontvangen, moet u de IBackgroundCopyCallback2-interface implementeren. De interface bevat de volgende methoden die BITS aanroept, afhankelijk van uw registratie:
Zie de voorbeeldcode in het interfaceonderwerp IBackgroundCopyCallback voor een voorbeeld dat de IBackgroundCopyCallback2 interface implementeert.
De interface IBackgroundCopyCallback2 geeft een melding wanneer een bestand wordt overgedragen. Normaal gesproken gebruikt u deze methode om het bestand te valideren, zodat het bestand beschikbaar is voor peers om te downloaden; anders is het bestand pas beschikbaar voor peers als u de methode IBackgroundCopyJob::Complete aanroept. Als u het bestand wilt valideren, roept u de methode IBackgroundCopyFile3::SetValidationState aan.
Er zijn twee methoden voor het registreren van een COM-callback: het registreren van een callback-object of het registreren van een callback-klasse-id. Het gebruik van een callback-object is eenvoudiger en heeft minder overhead. Het gebruik van een callback CLSID is betrouwbaarder, maar ingewikkelder. U kunt geen van beide, één van beide of beide registreren – BITS gebruikt een callback-object als er een bestaat en nog steeds kan worden aangeroepen, en valt terug op het instantiëren van een nieuw object op basis van een opgegeven klasse-ID als dat mislukt.
Een callback-object registreren
Als u uw implementatie wilt registreren bij BITS, roept u de methode IBackgroundCopyJob::SetNotifyInterface aan. Als u wilt opgeven welke methoden BITS aanroepen, roept u de methode IBackgroundCopyJob::SetNotifyFlags aan.
De meldingsinterface wordt ongeldig wanneer uw toepassing wordt beëindigd; BITS blijft de meldingsinterface niet behouden. Als gevolg hiervan moet het initialisatieproces van uw toepassing bestaande taken registreren waarvoor u een melding wilt ontvangen. Als u status- en voortgangsgegevens wilt vastleggen die zijn opgetreden sinds de laatste keer dat uw toepassing werd uitgevoerd, moet u tijdens de initialisatie van de toepassing peilen naar status- en voortgangsgegevens.
Voordat u het programma afsluit, moet de aanduiding voor de callback-interface (SetNotifyInterface(NULL)) worden gewist. Het is efficiënter om de callbackaanwijzer te wissen dan BITS te laten detecteren dat deze niet langer geldig is.
Houd er rekening mee dat als meer dan één toepassing de methode SetNotifyInterface aanroept om de meldingsinterface voor de taak in te stellen, de laatste toepassing voor het aanroepen van de methode SetNotifyInterface de methode is die meldingen ontvangt. De andere toepassingen ontvangen geen meldingen.
In het volgende voorbeeld ziet u hoe u zich registreert voor meldingen. In het voorbeeld wordt ervan uitgegaan dat de IBackgroundCopyJob interfaceaanwijzer geldig is. Zie de interface IBackgroundCopyCallback voor meer informatie over de CNotifyInterface-voorbeeldklasse die in het volgende voorbeeld wordt gebruikt.
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.
}
}
Een Callback CLSID registreren
Als u een callback-CLSID wilt registreren bij BITS, roept u de methode IBackgroundCopyJob5::SetProperty aan met de BITS_JOB_PROPERTY_NOTIFICATION_CLSID PropertyId. Als u wilt opgeven welke methoden BITS aanroept, gebruikt u de methode IBackgroundCopyJob::SetNotifyFlags.
Zorg ervoor dat de notificatie CLSID is geregistreerd bij een COM-server die buiten het proces draait voordat u de CLSID registreert bij een BITS-taak. Het implementeren van een COM-server is aanzienlijk ingewikkelder dan het definiëren en doorgeven van een callback-object, maar biedt verschillende belangrijke voordelen. Met een COM-server kan BITS de koppeling tussen een BITS-taak en de code van uw toepassing behouden voor het opnieuw opstarten van het systeem en voor grote of langdurige taken. Met een COM-server kan uw toepassing ook volledig worden afgesloten terwijl BITS de overdrachten op de achtergrond blijft uitvoeren, wat het batterij-, CPU- en geheugengebruik van het systeem kan verbeteren.
Als u een melding wilt opgeven die u hebt geregistreerd om te ontvangen, probeert BITS eerst de bijbehorende methode aan te roepen van een bestaand callback-object dat u mogelijk hebt gekoppeld. Als er geen bestaand object is of als dat bestaande object is verbroken (meestal als gevolg van het beëindigen van uw toepassing), roept BITS CoCreateInstance aan met behulp van de melding CLSID om een nieuw callback-object te instantiëren en gebruikt dit object voor verdere callbacks totdat deze wordt verbroken of wordt vervangen door een nieuwe aanroep naar IBackgroundCopyJob:: SetNotifyInterface.
In tegenstelling tot callback-objecten worden callback CLSID naast de bijbehorende BITS-taken opgeslagen als de BITS-service of het systeem wordt afgesloten en opnieuw opgestart. Uw toepassing kan een eerder ingestelde notificatie CLSID wissen voordat u afsluit (of op een ander moment) door een nieuwe notificatie CLSID van GUID_NULL door te geven, maar uw toepassing kan ervoor kiezen om de notificatie CLSID geregistreerd te laten als uw toepassing is geregistreerd om COM te laten starten als reactie op CoCreateInstance-aanvragen voor uw CLSID. Houd er rekening mee dat als meer dan één toepassing de eigenschap BITS_JOB_PROPERTY_NOTIFICATION_CLSID aanroept, de laatste CLSID die moet worden ingesteld, het object is dat BITS gebruikt om callback-objecten te instantiëren. De andere CLSID's worden niet geïnstantieerd. Als een toepassing een CLSID registreert en een andere een callback-object registreert, zijn de gebruikelijke regels van toepassing dat het callback-object voorrang heeft, en de CLSID wordt niet gebruikt tenzij het callback-object gewist of ontkoppeld wordt.
In het volgende voorbeeld ziet u hoe u zich registreert voor CLSID-meldingen. In het voorbeeld wordt ervan uitgegaan dat de IBackgroundCopyJob5- interfaceaanwijzer geldig is en dat uw toepassing al is geregistreerd als een niet-verwerkte COM-server waarmee de CNotifyInterface-klasse wordt geïmplementeerd. Zie de interface IBackgroundCopyCallback voor meer informatie over de CNotifyInterface-voorbeeldklasse die in het volgende voorbeeld wordt gebruikt.
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.
}