Méthode IBackgroundCopyJob2 ::SetNotifyCmdLine (bits1_5.h)

Article
08/22/2023

Spécifie un programme à exécuter si le travail entre dans l’état BG_JOB_STATE_ERROR ou BG_JOB_STATE_TRANSFERRED . BITS exécute le programme dans le contexte de l’utilisateur qui a appelé cette méthode.

Syntaxe

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

Paramètres

[in] Program

Chaîne terminée par null qui contient le programme à exécuter. Le paramètre pProgram est limité à MAX_PATH caractères, à l’exception de la terminaison null. Vous devez spécifier un chemin d’accès complet au programme ; la méthode n’utilise pas le chemin de recherche pour localiser le programme.

Pour supprimer la notification de ligne de commande, définissez pProgram et pParameters sur NULL. La méthode échoue si pProgram a la valeur NULL et que pParameters n’est pas NULL.

[in] Parameters

Chaîne terminée par null qui contient les paramètres du programme dans pProgram. Le premier paramètre doit être le programme dans pProgram (utilisez des guillemets si le chemin utilise des noms de fichiers longs). Le paramètre pParameters est limité à 4 000 caractères, sans compter la fin null. Ce paramètre peut être NULL.

Valeur retournée

Cette méthode retourne les valeurs HRESULT suivantes, ainsi que d’autres.

Code de retour	Description
S_OK	Réussite.
BG_E_INVALID_STATE	L’état du travail ne peut pas être BG_JOB_STATE_CANCELLED ou BG_JOB_STATE_ACKNOWLEDGED.
BG_E_STRING_TOO_LONG	La chaîne pProgram ou pParameters est trop longue.

Remarques

BITS appelle la fonction CreateProcessAsUser pour lancer le programme.

Votre programme doit retourner un code de sortie de zéro. Si votre programme ne retourne pas de code de sortie de zéro, BITS vérifie l’état du travail. Si le programme n’a pas annulé ou terminé le travail, BITS appelle à nouveau le programme après l’expiration du délai minimal de nouvelle tentative spécifié pour le travail.

BITS 1.5 et versions antérieures : BITS n’appelle le programme qu’une seule fois.

Pour exécuter un script, spécifiez WScript.exe (inclure le chemin d’accès complet à WScript.exe) dans pProgram. Le paramètre pParameters doit inclure WScript.exe, le nom du script et tous les arguments.

Si votre programme nécessite des informations liées au travail, vous devez passer ces informations en tant qu’arguments. N’incluez pas de variables d’environnement, telles que %system32%, dans pProgram ou pParameters ; elles ne sont pas développées.

Vous devez inclure le chemin complet du programme. Si l’un des arguments de pParameters inclut un chemin qui utilise des noms de fichiers longs, comme le nom du module, utilisez des guillemets autour du chemin.

Si le programme que vous souhaitez exécuter utilise le fichier de réponse ou de téléchargement, le programme doit appeler la méthode IBackgroundCopyJob ::Complete pour rendre les fichiers disponibles pour le client.

Appelez la méthode IBackgroundCopyJob ::SetNotifyFlags pour spécifier quand exécuter le programme. Vous pouvez demander l’exécution de la ligne de commande uniquement pour les événements d’erreur de travail ou transférés, et non pour les événements de modification de travail. Notez que BITS exécute toujours la ligne de commande même si vous appelez la méthode SetNotifyCmdLine après que l’événement s’est produit.

Si le travail BITS se trouve dans un contexte de compte de service (par exemple, networkservice/localsystem/localservice), aucune forme de rappel de ligne de commande ne s’exécute.

Si vous appelez à la fois la méthode SetNotifyCmdLine et la méthode IBackgroundCopyJob ::SetNotifyInterface , BITS exécute la ligne de commande uniquement si l’interface de notification devient non valide ou si la méthode de notification que BITS appelle retourne un code d’échec. Par exemple, si la méthode de notification appelée par BITS retourne un E_FAIL, BITS exécute la ligne de commande. Toutefois, si la méthode de notification retourne S_OK, BITS n’exécute pas la ligne de commande. Si la méthode de notification et la demande d’exécution de ligne de commande échouent, BITS envoie à nouveau la notification après l’expiration de la période minimale de nouvelle tentative.

Notez que l’appel de la méthode IBackgroundCopyJob ::TakeOwnership supprime la notification de ligne de commande du travail.

Exemples

Pour obtenir un exemple qui appelle la méthode SetNotifyCmdLine , consultez Inscription à l’exécution d’un programme.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2003
Plateforme cible	Windows
En-tête	bits1_5.h (incluez Bits.h)
Bibliothèque	Bits.lib
DLL	BitsPrx2.dll
Composant redistribuable	BITS 1.5 sur Windows XP

Voir aussi

IBackgroundCopyJob2 ::GetNotifyCmdLine

IBackgroundCopyJob ::SetNotifyFlags

IBackgroundCopyJob ::SetNotifyInterface

Partager via