Metodo IBackgroundCopyJob3::ReplaceRemotePrefix (bits2_0.h)

Articolo
03/14/2023

Sostituisce il testo iniziale di tutti i nomi remoti nel processo di download con la stringa specificata.

Sintassi

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

Parametri

[in] OldPrefix

Stringa con terminazione null che identifica il testo da sostituire nel nome remoto. Il testo deve iniziare all'inizio del nome remoto.

[in] NewPrefix

Stringa con terminazione null contenente il testo sostitutivo.

Valore restituito

Questo metodo restituisce i valori restituiti seguenti, nonché altri.

Codice restituito	Descrizione
S_OK	Operazione riuscita
S_FALSE	Non è stata trovata alcuna corrispondenza.
E_INVALIDARG	L'applicazione di NewPrefix crea un URL non valido o il nuovo URL è troppo lungo (l'URL non può superare i 2.200 caratteri). È anche possibile ricevere questo codice restituito se OldPrefix o NewPrefix è una stringa vuota.
E_NOTIMPL	Non è possibile chiamare questo metodo per caricare o caricare processi di risposta; chiamare questo metodo solo per i processi di download.
BG_E_INVALID_STATE	Lo stato del processo non può essere BG_JOB_STATE_CANCELLED o BG_JOB_STATE_ACKNOWLEDGED.

Commenti

In genere, si usa questo metodo per modificare la parte del server del nome remoto quando il server non è disponibile o per consentire agli utenti mobili di connettersi al server più vicino. Questo metodo modifica tutti i nomi remoti corrispondenti nel processo. Per modificare il nome remoto di un file specifico, usare il metodo IBackgroundCopyFile2::SetRemoteName .

Il metodo ReplaceRemotePrefix esegue una ricerca con distinzione tra maiuscole e minuscole di tutti i nomi remoti del processo. Se il testo iniziale del nome remoto corrisponde alla stringa in OldPrefix, BITS sostituisce il testo con la stringa trovata in NewPrefix. Ad esempio, per modificare "http://Server/Path/File.ext" su ";, impostare OldPrefix su "http://Server"http://NewServerName/Path/File.ext" e NewPrefix su "http://NewServerName". Si noti che BITS non esegue conversioni delle impostazioni locali nella ricerca.

Se il timestamp o la dimensione del file del nuovo nome remoto è diverso dal nome remoto precedente o il nuovo server non supporta la ripresa del checkpoint (per i nomi remoti HTTP), BITS riavvia il download. In caso contrario, il trasferimento riprende dalla stessa posizione del nuovo server. BITS non riavvia già i file trasferiti.

È possibile usare questo metodo per modificare i protocolli. Tuttavia, l'URL risultante potrebbe non essere ben formato. Ad esempio, la modifica da \Server\Dir\File.ext potrebbe http://Server\Dir\File.ext non essere risolta. È consigliabile usare il metodo IBackgroundCopyFile2::SetRemoteName .

Si noti che questo metodo potrebbe non trovare URL da modificare se si chiama il metodo IBackgroundCopyJobHttpOptions::SetSecurityFlags e impostare il flag di BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT . Questo criterio modifica l'URL originale nell'URL finale, reindirizzato se l'URL viene reindirizzato.

Esempio

Nell'esempio seguente viene illustrato come chiamare il metodo ReplaceRemotePrefix per modificare il nome del server di un URL. L'esempio presuppone che la variabile IBackgroundCopyJob , pJob, sia valida e il processo contenga uno o più file.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista, Windows XP con SP2,KB842773 in Windows Server 2003 e Windows XP
Server minimo supportato	Windows Server 2008, Windows Server 2003 con SP1
Piattaforma di destinazione	Windows
Intestazione	bits2_0.h (includere Bits.h)
Libreria	Bits.lib
DLL	BitsPrx3.dll

Vedi anche

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3

Condividi tramite