Gestione degli errori (BITS)

Esistono due tipi di errori da gestire nell'applicazione. Il primo errore è una chiamata al metodo non riuscita. Ogni metodo restituisce un valore HRESULT . La pagina di riferimento per ogni metodo identifica i valori restituiti che è più probabile generare. Per altri valori restituiti, vedere Valori restituiti BITS. Per ottenere il testo del messaggio associato al valore restituito, chiamare il metodo IBackgroundCopyManager::GetErrorDescription.

Il secondo tipo di errore da gestire è un processo il cui stato passa a BG_JOB_STATE_ERROR o BG_JOB_STATE_TRANSIENT_ERROR. Per recuperare informazioni correlate a questi tipi di errori, chiamare il metodo IBackgroundCopyJob::GetError del processo. Il metodo restituisce un puntatore all'interfaccia IBackgroundCopyError che contiene informazioni utilizzate per determinare la causa dell'errore. È anche possibile ricevere una notifica di errore registrandosi per ricevere la notifica degli eventi. Per informazioni dettagliate, vedere Registrazione di un callback COM.

BITS considera ogni processo atomico. Se uno dei file nel processo genera un errore, il processo rimane in uno stato di errore fino a quando l'errore non viene risolto. Pertanto, non è possibile eliminare il file che causa l'errore dal processo. Tuttavia, se l'errore è causato dal server non disponibile o da un file remoto non valido, è possibile chiamare il metodo IBackgroundCopyJob3::ReplaceRemotePrefix o IBackgroundCopyFile2::SetRemoteName per identificare un nuovo server o un nuovo nome file.

Dopo aver determinato la causa dell'errore, eseguire una delle opzioni seguenti:

• Annullare il processo chiamando il metodo IBackgroundCopyJob::Cancel.
• Per un processo di download, chiamare il metodo IBackgroundCopyJob::Complete per salvare i file trasferiti correttamente prima che si sia verificato l'errore.
• Correggere l'errore e chiamare il metodo IBackgroundCopyJob::Resume per completare il processo.

Per un processo di caricamento-risposta, controllare il valore del membro BytesTotal della struttura BG_JOB_REPLY_PROGRESS per determinare se si è verificato l'errore nella parte di caricamento o risposta del processo. Errore durante il caricamento se il valore è BG_SIZE_UNKNOWN.

Nell'esempio seguente viene illustrato come recuperare un puntatore all'interfaccia IBackgroundCopyError . Nell'esempio si presuppone che il puntatore all'interfaccia IBackgroundCopyJob sia valido.

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.
}