Méthode IBackgroundCopyJob3 ::ReplaceRemotePrefix (bits2_0.h)

Article
02/23/2024

Remplace le texte de début de tous les noms distants dans le travail de téléchargement par la chaîne spécifiée.

Syntaxe

HRESULT ReplaceRemotePrefix(
  [in] LPCWSTR OldPrefix,
  [in] LPCWSTR NewPrefix
);

Paramètres

[in] OldPrefix

Chaîne terminée par null qui identifie le texte à remplacer dans le nom distant. Le texte doit commencer au début du nom distant.

[in] NewPrefix

Chaîne terminée par null qui contient le texte de remplacement.

Valeur retournée

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

Code de retour	Description
S_OK	Succès
S_FALSE	Aucune correspondance trouvée.
E_INVALIDARG	L’application de NewPrefix crée une URL non valide ou la nouvelle URL est trop longue (l’URL ne peut pas dépasser 2 200 caractères). Vous pouvez également recevoir ce code de retour si OldPrefix ou NewPrefix est une chaîne vide.
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 utilisez cette méthode pour modifier la partie serveur du nom distant lorsque le serveur n’est pas disponible ou pour permettre aux utilisateurs itinérants de se connecter au serveur le plus proche. Cette méthode modifie tous les noms distants correspondants dans le travail. Pour modifier le nom distant d’un fichier spécifique, utilisez la méthode IBackgroundCopyFile2 ::SetRemoteName .

La méthode ReplaceRemotePrefix effectue une recherche respectant la casse de tous les noms distants du travail. Si le texte de début du nom distant correspond à la chaîne dans OldPrefix, BITS remplace le texte par la chaîne trouvée dans NewPrefix. Par exemple, pour modifier «http://Server/Path/File.ext" ; sur « http://NewServerName/Path/File.ext", définissez OldPrefix sur « http://Server" et NewPrefix à « http://NewServerName". Notez que BITS n’effectue pas de conversions de paramètres régionaux dans la recherche.

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.

Vous pouvez utiliser cette méthode pour modifier les protocoles. Toutefois, l’URL résultante peut ne pas être bien formée. Par exemple, la modification de \Server\Dir\File.ext http://Server\Dir\File.ext par peut ne pas être résolue. Envisagez d’utiliser la méthode IBackgroundCopyFile2 ::SetRemoteName à la place.

Notez que cette méthode peut ne pas trouver d’URL à modifier si vous avez appelé la méthode IBackgroundCopyJobHttpOptions ::SetSecurityFlags et que vous définissez l’indicateur BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT . Cette stratégie remplace l’URL d’origine par l’URL finale redirigée si l’URL est redirigée.

Exemples

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

     IBackgroundCopyJob *pJob;
     IBackgroundCopyJob3 *pJob3 = NULL;

     //Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
     //interface pointer. The IBackgroundCopyJob3 interface contains the ReplaceRemotePrefix method.
     hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
     if (S_OK == hr)
     {
          pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.

          //Identify the old and new remote name text. For example, "http://oldservername" and 
          //"http://newservername". For SMB, specify "\\\\oldservername" and "\\\\newservername".
          hr = pJob3->ReplaceRemotePrefix(L"<OLDSERVERNAMEGOESHERE>", L"<NEWSERVERNAMEGOESHERE>");
          if (S_FALSE == hr)
          {
               wprintf(L"The job does not contain files with a remote name that matches the prefix.\n");
          }
          else if (FAILED(hr))
          {
               //Handle error.
               //Returns E_NOTIMPL if not a download job.
               //Returns E_INVALIDARG if new prefix is empty or the resulting URL is invalid.
          }

          pJob3->Release();
     }
     else
     {
          //Handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
          //running on the computer is less than BITS 2.0.
     }

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 ::SetRemoteName

IBackgroundCopyJob3

Partager via