Registrieren eines COM-Rückrufs
Anstatt Änderungen am Status eines Auftrags zu erhalten, können Sie sich registrieren, um eine Benachrichtigung zu erhalten, wenn sich der Status des Auftrags ändert. Zum Empfangen von Benachrichtigungen müssen Sie die IBackgroundCopyCallback2-Schnittstelle implementieren. Die -Schnittstelle enthält die folgenden Methoden, die BITS abhängig von Ihrer Registrierung aufruft:
Ein Beispiel, das die IBackgroundCopyCallback2-Schnittstelle implementiert, finden Sie im Beispielcode im Thema IBackgroundCopyCallback-Schnittstelle.
Die IBackgroundCopyCallback2-Schnittstelle stellt eine Benachrichtigung bereit, wenn eine Datei übertragen wird. In der Regel verwenden Sie diese Methode, um die Datei zu überprüfen, sodass die Datei für Peers zum Herunterladen verfügbar ist. Andernfalls ist die Datei erst für Peers verfügbar, wenn Sie die IBackgroundCopyJob::Complete-Methode aufrufen. Rufen Sie zum Überprüfen der Datei die IBackgroundCopyFile3::SetValidationState-Methode auf.
Es gibt zwei Methoden zum Registrieren eines COM-Rückrufs: Registrieren eines Rückrufobjekts oder Registrieren einer Rückrufklassen-ID. Die Verwendung eines Rückrufobjekts ist einfacher und reduziert den Mehraufwand. Die Verwendung einer Rückruf-CLSID ist zuverlässiger, aber komplizierter. Sie können entweder oder beides oder keines von beiden registrieren. BITS verwendet ein Rückrufobjekt, sofern vorhanden und kann weiterhin aufgerufen werden. Wenn dies fehlschlägt, wird auf die Instanziierung eines neuen Objekts basierend auf einer angegebenen Klassen-ID zurückfallen.
Registrieren eines Rückrufobjekts
Um Ihre Implementierung bei BITS zu registrieren, rufen Sie die IBackgroundCopyJob::SetNotifyInterface-Methode auf. Um anzugeben, welche Methoden BITS aufruft, rufen Sie die IBackgroundCopyJob::SetNotifyFlags-Methodeauf.
Die Benachrichtigungsschnittstelle wird ungültig, wenn Ihre Anwendung beendet wird. BITS bleibt die Benachrichtigungsschnittstelle nicht erhalten. Daher sollte der Initialisierungsprozess Ihrer Anwendung vorhandene Aufträge registrieren, für die Sie eine Benachrichtigung erhalten möchten. Wenn Sie Zustands- und Fortschrittsinformationen erfassen müssen, die seit der letzten Ausführung der Anwendung aufgetreten sind, sollten Sie während der Anwendungsin initialisierung Status- und Statusinformationen erhalten.
Vor dem Beenden sollte Ihre Anwendung den Rückrufschnittstellenzeiger löschen (SetNotifyInterface(NULL)). Es ist effizienter, den Rückrufzeiger zu löschen, als BITS feststellen zu lassen, dass er nicht mehr gültig ist.
Beachten Sie, dass, wenn mehr als eine Anwendung die SetNotifyInterface-Methode aufruft, um die Benachrichtigungsschnittstelle für den Auftrag festlegen, die letzte Anwendung, die die SetNotifyInterface-Methode aufruft, die Benachrichtigungen erhält– die anderen Anwendungen keine Benachrichtigungen erhalten.
Das folgende Beispiel zeigt, wie Sie sich für Benachrichtigungen registrieren. Im Beispiel wird davon ausgegangen, dass der IBackgroundCopyJob-Schnittstellenzeiger gültig ist. Weitere Informationen zur CNotifyInterface-Beispielklasse, die im folgenden Beispiel verwendet wird, finden Sie in der IBackgroundCopyCallback-Schnittstelle.
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.
}
}
Registrieren einer Rückruf-CLSID
Um eine Rückruf-CLSID bei BITS zu registrieren, rufen Sie die IBackgroundCopyJob5::SetProperty-Methode mit der BITS JOB PROPERTY NOTIFICATION _ _ _ _ CLSID PropertyId auf. Um anzugeben, welche Methoden BITS aufruft, rufen Sie die IBackgroundCopyJob::SetNotifyFlags-Methode auf.
Sie müssen sicherstellen, dass die Benachrichtigungs-CLSID bei einem OUT-of-Process-COM-Server registriert ist, bevor Sie die CLSID bei einem BITS-Auftrag registrieren. Die Implementierung eines COM-Servers ist deutlich komplizierter als das Definieren und Übergeben eines Rückrufobjekts, bietet jedoch mehrere wichtige Vorteile. Mit einem COM-Server kann BITS die Zuordnung zwischen einem BITS-Auftrag und dem Code Ihrer Anwendung über Systemneustarts hinweg und bei großen oder langlebigen Aufträgen verwalten. Mit einem COM-Server kann Ihre Anwendung auch vollständig heruntergefahren werden, während BITS weiterhin Übertragungen im Hintergrund ausführen, was die Akku-, CPU- und Arbeitsspeicherauslastung des Systems verbessern kann.
Um eine Benachrichtigung zu senden, die Sie für den Empfang registriert haben, versucht BITS zunächst, die entsprechende Methode eines vorhandenen Rückrufobjekts auf aufruft, das Sie möglicherweise angefügt haben. Wenn kein vorhandenes Objekt vorhanden ist oder das vorhandene Objekt getrennt wurde (in der Regel als Ergebnis des Anwendungsabbruchs), rufen BITS CoCreateInstance mithilfe der Benachrichtigungs-CLSID auf, um ein neues Rückrufobjekt zu instanziieren, und verwendet dieses Objekt für alle weiteren Rückrufe, bis es getrennt wird oder durch einen neuen Aufruf von IBackgroundCopyJob::SetNotifyInterfaceersetzt wird.
Im Gegensatz zu Rückrufobjekten wird die Rückruf-CLSID zusammen mit den entsprechenden BITS-Auftrag(en) beibehalten, wenn der BITS-Dienst oder das System heruntergefahren und neu gestartet wird. Ihre Anwendung kann vor dem Beenden (oder zu einem anderen Zeitpunkt) jede zuvor festgelegte Benachrichtigungs-CLSID löschen, indem sie eine neue Benachrichtigungs-CLSID von GUID NULL übergibt. Möglicherweise möchte Ihre Anwendung die Benachrichtigungs-CLSID jedoch lieber registriert lassen, wenn sich Ihre Anwendung registriert hat, damit COM sie als Reaktion auf _ CoCreateInstance-Anforderungen für Ihre CLSID starten kann. Beachten Sie, dass, wenn mehr als eine Anwendung die BITS JOB PROPERTY NOTIFICATION _ _ _ _ CLSID-Eigenschaft aufruft, die letzte CLSID, die festgelegt werden soll, die ist, die BITS zum Instanziieren von Rückrufobjekten verwendet. Die anderen CLSIDs werden nicht instanziiert. Wenn eine Anwendung eine CLSID registriert und eine andere ein Rückrufobjekt registriert, gelten entsprechend die üblichen Regeln für das Rückrufobjekt, das Vorrang hat, und die CLSID wird nur verwendet, wenn das Rückrufobjekt gelöscht oder getrennt wird.
Das folgende Beispiel zeigt, wie Sie sich für CLSID-Benachrichtigungen registrieren. Im Beispiel wird davon ausgegangen, dass der IBackgroundCopyJob5-Schnittstellenzeiger gültig ist und dass Ihre Anwendung bereits als Out-of-Process-COM-Server registriert wurde, der die CNotifyInterface-Klasse implementiert. Weitere Informationen zur CNotifyInterface-Beispielklasse, die im folgenden Beispiel verwendet wird, finden Sie in der IBackgroundCopyCallback-Schnittstelle.
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.
}