Gestion des erreurs (BITS)

Il existe deux types d’erreurs à gérer dans votre application. La première erreur est un appel de méthode ayant échoué. Chaque méthode retourne une valeur HRESULT . La page de référence de chaque méthode identifie les valeurs de retour qu’elle est la plus susceptible de générer. Pour obtenir des valeurs de retour supplémentaires, consultez Valeurs de retour BITS. Pour obtenir le texte du message associé à la valeur de retour, appelez la méthode IBackgroundCopyManager::GetErrorDescription .

Le deuxième type d’erreur à gérer est un travail dont l’état passe à BG_JOB_STATE_ERROR ou BG_JOB_STATE_TRANSIENT_ERROR. Pour récupérer des informations relatives à ces types d’erreurs, appelez la méthode IBackgroundCopyJob::GetError du travail. La méthode retourne un pointeur d’interface IBackgroundCopyError qui contient des informations que vous utilisez pour déterminer la cause de l’erreur. Vous pouvez également recevoir une notification d’erreur en vous inscrivant pour recevoir une notification d’événement. Pour plus d’informations, consultez Inscription d’un rappel COM.

BITS considère chaque travail comme atomique. Si l’un des fichiers du travail génère une erreur, le travail reste dans un état d’erreur jusqu’à ce que l’erreur soit résolue. Par conséquent, vous ne pouvez pas supprimer le fichier à l’origine de l’erreur du travail. Toutefois, si l’erreur est due à l’indisponibilité du serveur ou à un fichier distant non valide, vous pouvez appeler la méthode IBackgroundCopyJob3::ReplaceRemotePrefix ou IBackgroundCopyFile2::SetRemoteName pour identifier un nouveau serveur ou un nouveau nom de fichier.

Après avoir déterminé la cause de l’erreur, effectuez l’une des options suivantes :

• Annulez le travail en appelant la méthode IBackgroundCopyJob::Cancel .
• Pour un travail de téléchargement, appelez la méthode IBackgroundCopyJob::Complete pour enregistrer les fichiers transférés avec succès avant que l’erreur ne se produise.
• Corrigez l’erreur et appelez la méthode IBackgroundCopyJob::Resume pour terminer le travail.

Pour un travail chargement-réponse, case activée la valeur du membre BytesTotal de la structure BG_JOB_REPLY_PROGRESS pour déterminer si l’erreur s’est produite sur la partie chargement ou réponse du travail. L’erreur s’est produite sur le chargement si la valeur est BG_SIZE_UNKNOWN.

L’exemple suivant montre comment récupérer un pointeur d’interface IBackgroundCopyError . L’exemple suppose que le pointeur d’interface IBackgroundCopyJob est valide.

HRESULT hr = 0;
HRESULT hrError = 0;
IBackgroundCopyJob* pJob;
IBackgroundCopyError* pError = NULL;
IBackgroundCopyFile* pFile = NULL;
WCHAR* pszDescription = NULL;
WCHAR* pszRemoteName = NULL;
BG_ERROR_CONTEXT Context;

hr = pJob->GetError(&pError);
if (SUCCEEDED(hr))
{
  //Retrieve the HRESULT associated with the error. The context tells you
  //where the error occurred, for example, in the transport, queue manager, the 
  //local file, or the remote file.
  pError->GetError(&Context, &hrError);  

  //Retrieve a description associated with the HRESULT value.
  hr = pError->GetErrorDescription(LANGIDFROMLCID(GetThreadLocale()), &pszDescription);
  if (SUCCEEDED(hr))
  {
    if (BG_ERROR_CONTEXT_REMOTE_FILE == Context)
    {
      hr = pError->GetFile(&pFile);  
      if (SUCCEEDED(hr))
      {
        hr = pFile->GetRemoteName(&pszRemoteName);
        if (SUCCEEDED(hr))
        {
          //Do something with the information.
          CoTaskMemFree(pszRemoteName);
        }
        pFile->Release();
      }
    }
    CoTaskMemFree(pszDescription);
  }
  pError->Release();
}
else
{
  //Error information is not available.
}