Méthode IBackgroundCopyCallback ::JobError (bits.h)

Article
08/22/2023

BITS appelle votre implémentation de la méthode JobError lorsque l’état du travail passe à BG_JOB_STATE_ERROR.

Syntaxe

HRESULT JobError(
  [in] IBackgroundCopyJob   *pJob,
  [in] IBackgroundCopyError *pError
);

Paramètres

[in] pJob

Contient des informations liées au travail, telles que le nombre d’octets et de fichiers transférés avant que l’erreur ne se produise. Il contient également les méthodes permettant de reprendre et d’annuler le travail. Ne relâchez pas pJob ; BITS libère l’interface lorsque la méthode JobError retourne.

[in] pError

Contient des informations sur l’erreur, telles que le fichier en cours de traitement au moment où l’erreur irrécupérable s’est produite et une description de l’erreur. Ne relâchez pas pError ; BITS libère l’interface lorsque la méthode JobError retourne.

Valeur retournée

Cette méthode doit retourner S_OK ; sinon, BITS continue d’appeler cette méthode jusqu’à ce que S_OK soit retourné. Pour des raisons de performances, vous devez limiter le nombre de fois où vous retournez une valeur autre que S_OK à quelques reprises. En guise d’alternative au retour d’un code d’erreur, envisagez de toujours retourner S_OK et de gérer l’erreur en interne. L’intervalle auquel cette méthode est appelée est arbitraire.

Notez que si cette méthode échoue et que vous avez appelé la méthode IBackgroundCopyJob2 ::SetNotifyCmdLine , la ligne de commande est exécutée et cette méthode n’est plus appelée.

Remarques

Une fois que vous avez déterminé la cause de l’erreur, effectuez l’une des options suivantes :

Pour annuler le travail, appelez la méthode IBackgroundCopyJob ::Cancel . La demande d’annulation n’a aucun effet sur les travaux de chargement si l’erreur s’est produite après le chargement du fichier. Toutefois, si le type de travail est BG_JOB_TYPE_UPLOAD_REPLY et que le chargement a réussi, l’appel de la méthode Cancel annule la demande de données de réponse.
Pour accepter la partie du travail qui a été transférée correctement avant que l’erreur ne se produise, appelez la méthode IBackgroundCopyJob ::Complete . Cette option ne s’applique pas au chargement de travaux ; vous ne pouvez pas effectuer une partie d’un travail de chargement.
Pour terminer le traitement du travail, corrigez le problème, puis appelez la méthode IBackgroundCopyJob ::Resume .

Si le travail reste dans un état d’erreur pendant 90 jours (jobInactivityTimeout par défaut stratégie de groupe), BITS annule le travail et supprime les fichiers temporaires associés ; l’annulation du travail n’affecte pas les fichiers qui ont été correctement chargés.

Les erreurs temporaires ne génèrent pas d’appels à la méthode JobError .

Pour déterminer si la partie du chargement, de la réponse ou de l’application serveur d’un travail de réponse de chargement a échoué, appelez la méthode IBackgroundCopyError ::GetError pour récupérer le contexte dans lequel l’erreur s’est produite. L’application serveur a échoué si le contexte est BG_ERROR_CONTEXT_REMOTE_APPLICATION. Le contexte de chargement et de réponse est BG_ERROR_CONTEXT_REMOTE_FILE. La réponse a échoué si le membre BytesTotal de la structure BG_JOB_REPLY_PROGRESS n’est pas BG_SIZE_UNKNOWN. Sinon, le chargement a échoué.

Note BITS prend en charge jusqu’à quatre notifications simultanées par utilisateur. Si une ou plusieurs applications bloquent le retour des quatre notifications d’un utilisateur, une application s’exécutant en tant qu’utilisateur ne recevra pas de notifications tant qu’une ou plusieurs notifications de blocage ne seront pas retournées. Pour réduire le risque que votre rappel bloque d’autres notifications, gardez votre implémentation courte.