États du travail BITS
Il existe quatre classes d’états BITS : démarrage, action, transféré et final. Au fur et à mesure qu’un travail s’exécute, il effectue la transition entre les états dans les différentes classes d’état. Une fois qu’un travail est dans un état final, il ne sort pas de l’état final et n’apparaît pas dans une énumération de travaux.
Méthodes de changement d’état
Il existe quatre méthodes de changement d’état sur un travail : Annuler, Terminer, Reprendre et Suspendre. Tant qu’un travail n’est pas dans un état final, vous pouvez appeler n’importe quelle méthode de changement d’état.
La méthode Suspend est utilisée pour basculer un travail à l’état SUSPENDED. Lorsqu’un travail est suspendu, tous ses transferts sont arrêtés et ne reprendront pas tant que vous n’appelez pas Cv. Un travail déjà suspendu restera simplement suspendu.
La méthode Resume est utilisée pour démarrer un travail suspendu. Les travaux dans un état d’erreur ou d’erreur temporaire seront configurés pour être retentés. Les travaux qui se trouvent actuellement dans un état d’action restent dans cet état.
La méthode Cancel est utilisée pour annuler un travail. L’état passe à annulé. Les fichiers en cours de transfert ne seront pas terminés. Tous les fichiers entièrement transférés et partiellement transférés seront supprimés.
La méthode Complete termine un transfert. Tous les fichiers entièrement téléchargés seront conservés ; les fichiers qui ne sont pas entièrement transférés seront supprimés.
Vous devez appeler Annuler ou Terminer pour déplacer votre travail vers un état final et être nettoyé. Les travaux qui ne sont pas passés à un état final gaspillent des ressources système. BITS finit par annuler automatiquement les anciens travaux. JobInactivityTimeout par défaut consiste à annuler les travaux après 90 jours.
État initial
L’état de départ est SUSPENDED. À partir de là, vous pouvez ajouter des fichiers au travail et définir des propriétés de travail et de fichier. Pour démarrer le transfert d’un travail, appelez Cv sur le travail. Si vous reprenez un travail sans fichiers, il retourne un code d’erreur BG_E_EMPTY et le travail reste suspendu.
États d’action
Les états QUEUED, CONNECTING et TRANSFERRING indiquent l’activité interne actuelle de votre travail. Un travail qui est QUEUED est prêt à être planifié, peut-être en attente du planificateur BITS ou en attente de la connexion de l’utilisateur. Un travail qui se connecte tente de se connecter au serveur pour commencer à transférer des fichiers. Un travail qui est TRANSFERRING charge ou télécharge activement vos fichiers.
L’état D’ERREUR TEMPORAIRE signifie que le travail a essayé et n’a pas pu transférer le fichier. Cela peut être pour des raisons de stratégie réseau ; le travail peut être bloqué, car le réseau actuel est trop coûteux. Il peut également être bloqué pour des raisons système telles que l’économiseur de batterie ou le mode jeu, ou parce qu’il n’y a pas de connectivité Internet.
Les travaux dans l’état d’erreur temporaire sont retentés automatiquement par BITS, le cas échéant. BITS inclut une valeur MinimumRetryDelay et NoProgressTimeout pour contrôler le moment où un travail est retenté et quand BITS cesse finalement de réessayer.
États transférés
Les états transférés se produisent lorsqu’il n’y a plus de transfert à effectuer. Vous devez annuler ou terminer un travail dans cet état. Vous pouvez également ajouter d’autres fichiers à transférer et appeler Resume(), mais ce n’est pas une pratique courante.
L’état ERROR se produit lorsqu’un transfert est effectué (il ne sera pas retenté), mais qu’il n’a pas entièrement réussi. Tous les fichiers doivent être transférés pour réussir ; si l’un d’entre elles a échoué définitivement, le travail sera en erreur. Vous devez généralement appeler Annuler ou Terminer pour déplacer le travail dans un état final. La différence pratique est que lorsque vous appelez Cancel, tout fichier transféré avec succès est supprimé, mais si vous appelez Complete, tout fichier transféré avec succès ne sera pas supprimé.
Les raisons d’être dans un état ERROR incluent
- Rester trop longtemps dans un état d’ERREUR TEMPORAIRE (au-delà du paramètre NoProgressTimeout ).
- Obtention d’une erreur de BG_E_TOKEN_REQUIRED et besoin d’aide pour les jetons d’assistance
Il est courant de reconfigurer une tâche ERROR, puis d’appeler Cv pour réessayer le travail. Par exemple, votre application peut avoir besoin de mettre à jour le nom distant d’un fichier via SetRemoteName.
L’état TRANSFERED se produit lorsqu’un transfert est effectué et qu’il a réussi. Vous devez appeler Complete pour finaliser le travail ; pour les travaux de téléchargement, les fichiers téléchargés ne seront disponibles qu’après avoir appelé Terminé. L’exception à cette règle est les travaux qui sont les travaux hautes performances (et vous devez toujours appeler Complete).
États finaux
Une fois qu’un travail est dans un état final, vous ne pouvez appeler aucune des méthodes de changement d’état. Le travail sera RECONNU après avoir appelé Complete() et tous les fichiers téléchargés terminés seront disponibles. Le travail sera CANCELLED après avoir appelé Cancel() et tous les fichiers téléchargés seront supprimés.
Cycle de vie d’un travail BITS
Le cycle de vie d’un travail BITS commence lorsque vous créez un travail. Un travail est un conteneur qui contient un ou plusieurs fichiers à transférer. Un travail a également des propriétés qui spécifient la façon dont BITS transfère les fichiers et interagit avec votre application. Par exemple, vous pouvez spécifier la priorité du travail, si le travail est un travail de chargement ou de téléchargement, et pour quels événements vous souhaitez recevoir une notification.
Après avoir créé le travail, ajoutez un ou plusieurs fichiers (les travaux de chargement ne peuvent contenir qu’un seul fichier) au travail et modifiez l’une des valeurs de propriété en fonction de votre application. Lorsque vous ajoutez un fichier au travail, spécifiez le nom local (client) et distant (serveur) du fichier. Le nom de fichier distant doit utiliser le protocole HTTP, HTTPS ou SMB. Les fichiers au sein d’un travail sont traités séquentiellement (premier entrant, premier sorti).
BITS interrompt automatiquement les travaux lorsqu’ils sont créés. Vous devez reprendre le travail pour l’activer dans la file d’attente de transfert. Vous pouvez suspendre ou reprendre un travail à tout moment. La reprise du travail déplace le travail de l’état suspendu à l’état mis en file d’attente. Le travail reste dans l’état mis en file d’attente jusqu’à ce que le planificateur détermine que c’est au tour du travail de transférer des fichiers. Tous les travaux de premier plan s’exécutent simultanément avec un travail en arrière-plan. BITS traite les fichiers dans les travaux de premier plan en série.
Lorsqu’il s’agit d’un transfert de fichiers, le travail passe à l’état de connexion tandis que BITS se connecte au serveur distant (spécifié dans le nom de fichier distant). Si BITS est en mesure de se connecter au serveur distant, le travail passe à l’état de transfert où il reste jusqu’à ce que sa tranche de temps se termine, que le transfert soit terminé, qu’une erreur se produise ou que l’application suspend le travail.
Le travail se déplace entre les états mis en file d’attente, de connexion et de transfert jusqu’à ce que BITS transfère tous les fichiers du travail. À ce stade, le travail passe à l’état transféré. BITS utilise la planification par tourniquet (round robin) pour planifier des travaux qui se trouvent au même niveau de priorité. Chaque travail a une tranche de temps pour traiter ses fichiers. Si le travail ne se termine pas pendant sa tranche de temps, le travail revient à l’état mis en file d’attente et le travail suivant dans la file d’attente est activé. Cela empêche les travaux volumineux de bloquer les travaux plus petits. Les travaux sont traités en grande partie sur la base du premier entré, premier sorti (FIFO) ; Toutefois, BITS ne peut pas garantir le traitement FIFO en raison de la planification de tourniquets, des erreurs de travail et des redémarrages de service.
Les fichiers transférés ne sont pas disponibles pour le client tant que l’application n’appelle pas la méthode IBackgroundCopyJob::Complete pour transférer la propriété des fichiers de BITS à l’utilisateur. Les travaux de chargement sont également définis sur l’état transféré lorsque le fichier est correctement reçu par le serveur. Les travaux de chargement-réponse sont définis sur l’état transféré une fois que le fichier a été correctement envoyé au serveur et que la réponse de l’application serveur a été transférée au client.
Si une erreur se produit, le travail passe à l’état d’erreur irrécupérable ou temporaire. Les erreurs irrécupérables sont des erreurs dont BITS ne peut pas récupérer ou qui nécessitent une intervention pour corriger. Si l’application est en mesure de corriger l’erreur, l’application reprend le travail et BITS déplace le travail vers l’état mis en file d’attente. Les erreurs temporaires sont des erreurs qui peuvent se résoudre elles-mêmes. BITS retente les travaux dans l’état d’erreur temporaire jusqu’à ce que le transfert réussisse ou que le travail expire. Le travail expire lorsqu’aucune progression n’est effectuée dans une période spécifiée par l’application. Si le travail expire, BITS déplace le travail à l’état d’erreur irrécupérable.
Pour plus d’informations sur les états du travail, consultez BG_JOB_STATE.