Partager via


Méthode IBackgroundCopyFile2 ::SetRemoteName (bits2_0.h)

Remplace le nom distant par une nouvelle URL dans un travail de téléchargement.

Syntaxe

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

Paramètres

[in] Val

Chaîne terminée par null qui contient le nom du fichier sur le serveur. Pour plus d’informations sur la spécification du nom distant, consultez la section RemoteName member et Remarks de la structure BG_FILE_INFO .

Valeur retournée

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

Code de retour Description
S_OK
Succès
E_INVALIDARG
Le nouveau nom distant est une URL non valide ou la nouvelle URL est trop longue (l’URL ne peut pas dépasser 2 200 caractères).
E_NOTIMPL
Vous ne pouvez pas appeler cette méthode pour les travaux de chargement ou de chargement-réponse ; Appelez cette méthode uniquement pour les travaux de téléchargement.
BG_E_INVALID_STATE
L’état du travail ne peut pas être BG_JOB_STATE_CANCELLED ou BG_JOB_STATE_ACKNOWLEDGED.

Remarques

En règle générale, vous appelez cette méthode si vous souhaitez modifier le protocole utilisé pour transférer le fichier (par exemple, de SMB à HTTP) ou si vous souhaitez modifier le nom ou le chemin du fichier.

Cette méthode ne sérialise pas lorsqu’elle est retournée. Pour sérialiser la modification, suspendez le travail, appelez cette méthode (si vous modifiez plusieurs fichiers dans le travail, utilisez une boucle) et reprenez le travail. L’appel de la méthode IBackgroundCopyJob ::Resume sérialise la modification.

Si l’horodatage ou la taille du fichier du nouveau nom distant est différente du nom distant précédent ou si le nouveau serveur ne prend pas en charge la reprise du point de contrôle (pour les noms distants HTTP), BITS redémarre le téléchargement. Sinon, le transfert reprend à partir de la même position sur le nouveau serveur. BITS ne redémarre pas les fichiers déjà transférés.

Si le nom distant identifie un chemin SMB (Server Message Block), le tableau suivant identifie les codes d’erreur possibles qui peuvent se produire après la reprise du travail. Ces erreurs placent le travail dans l’état BG_JOB_STATE_ERROR .

Code d'erreur Description
HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) Le répertoire est introuvable.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND) Ce fichier est introuvable.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED) L’utilisateur n’a pas accès au fichier spécifié dans Val.
 

Exemples

L’exemple suivant montre comment appeler la méthode SetRemoteName pour modifier le nom distant d’un fichier. L’exemple suppose que la variable IBackgroundCopyJob , pJob, est valide et que le travail contient un ou plusieurs fichiers.

     IBackgroundCopyJob *pJob;
     IEnumBackgroundCopyFiles* pFiles = NULL;
     IBackgroundCopyFile* pFile = NULL;
     IBackgroundCopyFile2* pFile2 = NULL;
     WCHAR* pRemoteFileName = NULL;
     ULONG cFileCount = 0;

     hr = pJob->Suspend();
     hr = pJob->EnumFiles(&pFiles);
     if (SUCCEEDED(hr))
     {
          //Get the count of files in the job. 
          hr = pFiles->GetCount(&cFileCount);

          //Enumerate the files in the job.
          for (ULONG idx=0; idx<cFileCount; idx++)
          {
               hr = pFiles->Next(1, &pFile, NULL);
               if (S_OK == hr)
               {
                    //Get the local name of the file.
                    hr = pFile->GetRemoteName(&pRemoteFileName);
                    if (SUCCEEDED(hr))
                    {
                         //Determine if you want to replace the remote name of this file.
                         if (<CONDITIONGOESHERE>)
                         {
                              //Need to query the IBackgroundCopyFile interface for an IBackgroundCopyFile2
                              //interface pointer. The IBackgroundCopyFile2 interface contains the SetRemoteName method.
                              hr = pFile->QueryInterface(__uuidof(IBackgroundCopyFile2), (void**)&pFile2);
                              if (S_OK == hr)
                              {
                                   hr = pFile2->SetRemoteName(L"<NEWURLGOESHERE>");
                                   if (FAILED(hr))
                                   {
                                        //Handle error. 
                                        //Returns E_NOTIMPL if not a download job.
                                        //Returns E_INVALIDARG if invalid URL.
                                   }
                              }
                              else
                              {
                                   //handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
                                   //running on the computer is less than BITS 2.0.
                              }
                         }
                         CoTaskMemFree(pRemoteFileName); 
                    }    
                    pFile->Release(); 
                    pFile = NULL;
               }
               else
               {
                    //Handle error
                    break;
               }
          }

          pFiles->Release();
          pFiles = NULL;
     }

     hr = pJob->Resume(); //Force the job to serialize.


Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista, Windows XP avec SP2 KB842773 sur Windows Server 2003 et Windows XP
Serveur minimal pris en charge Windows Server 2008, Windows Server 2003 avec SP1
Plateforme cible Windows
En-tête bits2_0.h (include Bits.h)
Bibliothèque Bits.lib
DLL BitsPrx3.dll

Voir aussi

IBackgroundCopyFile2

IBackgroundCopyJob3 ::ReplaceRemotePrefix