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

Article
08/22/2023

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

Partager via