IBackgroundCopyJob2::SetNotifyCmdLine-Methode (bits1_5.h)

Artikel
08/22/2023

Gibt ein Programm an, das ausgeführt werden soll, wenn der Auftrag in den BG_JOB_STATE_ERROR- oder BG_JOB_STATE_TRANSFERRED-Zustand wechselt. BITS führt das Programm im Kontext des Benutzers aus, der diese Methode aufgerufen hat.

Syntax

HRESULT SetNotifyCmdLine(
  [in] LPCWSTR Program,
  [in] LPCWSTR Parameters
);

Parameter

[in] Program

Null-beendete Zeichenfolge, die das auszuführende Programm enthält. Der pProgram-Parameter ist auf MAX_PATH Zeichen beschränkt, ohne den NULL-Abschlusszeichen. Sie sollten einen vollständigen Pfad zum Programm angeben. Die -Methode verwendet nicht den Suchpfad, um das Programm zu finden.

Um die Befehlszeilenbenachrichtigung zu entfernen, legen Sie pProgram und pParameters auf NULL fest. Die Methode schlägt fehl, wenn pProgramNULL und pParameters ungleich NULL ist.

[in] Parameters

Null-beendete Zeichenfolge, die die Parameter des Programms in pProgram enthält. Der erste Parameter muss das Programm in pProgram sein (verwenden Sie Anführungszeichen, wenn der Pfad lange Dateinamen verwendet). Der pParameters-Parameter ist auf 4.000 Zeichen beschränkt, ohne den NULL-Abschlusszeichen. Dieser Parameter kann NULL sein.

Rückgabewert

Diese Methode gibt die folgenden HRESULT-Werte sowie andere zurück.

Rückgabecode	Beschreibung
S_OK	Erfolg.
BG_E_INVALID_STATE	Der Status des Auftrags kann nicht BG_JOB_STATE_CANCELLED oder BG_JOB_STATE_ACKNOWLEDGED sein.
BG_E_STRING_TOO_LONG	Die pProgram - oder pParameters-Zeichenfolge ist zu lang.

Hinweise

BITS ruft die CreateProcessAsUser-Funktion auf, um das Programm zu starten.

Ihr Programm sollte den Exitcode 0 (null) zurückgeben. Wenn Ihr Programm den Exitcode 0 (null) nicht zurückgibt, überprüft BITS den Status des Auftrags. Wenn das Programm den Auftrag nicht abgebrochen oder abgeschlossen hat, ruft BITS das Programm erneut auf, nachdem die für den Auftrag angegebene minimale Wiederholungsverzögerung abläuft.

BITS 1.5 und früher: BITS ruft das Programm nur einmal auf.

Um ein Skript auszuführen, geben Sie in pProgram WScript.exe an (schließen Sie den vollständigen Pfad zu WScript.exe ein). Der pParameters-Parameter sollte WScript.exe, den Skriptnamen und alle Argumente enthalten.

Wenn Für Ihr Programm auftragsbezogene Informationen erforderlich sind, müssen Sie diese Informationen als Argumente übergeben. Schließen Sie keine Umgebungsvariablen wie %system32%, in pProgram oder pParameters ein , da sie nicht erweitert sind.

Sie sollten den vollständigen Pfad zum Programm einschließen. Wenn eines der Argumente in pParameters einen Pfad enthält, der lange Dateinamen verwendet, z. B. den Modulnamen, verwenden Sie Anführungszeichen um den Pfad.

Wenn das Programm, das Sie ausführen möchten, die Antwort- oder Downloaddatei verwendet, muss das Programm die IBackgroundCopyJob::Complete-Methode aufrufen, um die Dateien für den Client verfügbar zu machen.

Rufen Sie die IBackgroundCopyJob::SetNotifyFlags-Methode auf, um anzugeben, wann das Programm ausgeführt werden soll. Sie können die Befehlszeilenausführung nur für Auftragsfehler oder übertragene Ereignisse anfordern, nicht für Auftragsänderungsereignisse. Beachten Sie, dass BITS weiterhin die Befehlszeile ausführt, auch wenn Sie die SetNotifyCmdLine-Methode aufrufen, nachdem das Ereignis eintritt.

Wenn sich der BITS-Auftrag in einem Dienstkontokontext (d. h. networkservice/localsystem/localservice) befindet, wird keine Form des Befehlszeilenrückrufs ausgeführt.

Wenn Sie sowohl die SetNotifyCmdLine-Methode als auch die IBackgroundCopyJob::SetNotifyInterface-Methode aufrufen, führt BITS die Befehlszeile nur aus, wenn die Benachrichtigungsschnittstelle ungültig wird oder die von BITS aufgerufene Benachrichtigungsmethode einen Fehlercode zurückgibt. Wenn die von BITS aufgerufene Benachrichtigungsmethode beispielsweise einen E_FAIL zurückgibt, führt BITS die Befehlszeile aus. Wenn die Benachrichtigungsmethode jedoch S_OK zurückgibt, führt BITS die Befehlszeile nicht aus. Wenn sowohl die Benachrichtigungsmethode als auch die Befehlszeilenausführungsanforderung fehlschlagen, sendet BITS die Benachrichtigung nach Ablauf der mindesten Wiederholungsdauer erneut.

Beachten Sie, dass beim Aufrufen der IBackgroundCopyJob::TakeOwnership-Methode die Befehlszeilenbenachrichtigung aus dem Auftrag entfernt wird.

Beispiele

Ein Beispiel, das die SetNotifyCmdLine-Methode aufruft , finden Sie unter Registrieren zum Ausführen eines Programms.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2003
Zielplattform	Windows
Kopfzeile	bits1_5.h (Bits.h einschließen)
Bibliothek	Bits.lib
DLL	BitsPrx2.dll
Verteilbare Komponente	BITS 1.5 unter Windows XP

Weitere Informationen

IBackgroundCopyJob2::GetNotifyCmdLine

IBackgroundCopyJob::SetNotifyFlags

IBackgroundCopyJob::SetNotifyInterface

Share via