IBackgroundCopyFile2 ::SetRemoteName, méthode (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 Membre RemoteName et Notes de la structure BG_FILE_INFO .

Valeur retournée

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

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 d’accès 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 de 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 déjà les fichiers 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 avoir repris le travail. Ces erreurs placent le travail dans l’état BG_JOB_STATE_ERROR .

Examples

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.

Spécifications

Voir aussi

IBackgroundCopyFile2

IBackgroundCopyJob3 ::ReplaceRemotePrefix