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

Substitui o texto inicial de todos os nomes remotos no trabalho de download pela cadeia de caracteres especificada.

Sintaxe

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

Parâmetros

[in] OldPrefix

Cadeia de caracteres terminada em nulo que identifica o texto a ser substituído no nome remoto. O texto deve começar no início do nome remoto.

[in] NewPrefix

Cadeia de caracteres terminada em nulo que contém o texto de substituição.

Retornar valor

Esse método retorna os seguintes valores retornados, bem como outros.

Comentários

Normalmente, você usa esse método para alterar a parte do servidor do nome remoto quando o servidor não está disponível ou para permitir que os usuários móveis se conectem ao servidor mais próximo. Esse método altera todos os nomes remotos correspondentes no trabalho. Para alterar o nome remoto de um arquivo específico, use o método IBackgroundCopyFile2::SetRemoteName .

O método ReplaceRemotePrefix executa uma pesquisa que diferencia maiúsculas de minúsculas de todos os nomes remotos no trabalho. Se o texto inicial do nome remoto corresponder à cadeia de caracteres em OldPrefix, o BITS substituirá o texto pela cadeia de caracteres encontrada em NewPrefix. Por exemplo, para alterar "http://Server/Path/File.ext" como "http://NewServerName/Path/File.ext", defina OldPrefix como "http://Server" e NewPrefix como "http://NewServerName". Observe que o BITS não executa conversões de localidade na pesquisa.

Se o carimbo de data/hora ou o tamanho do arquivo do novo nome remoto for diferente do nome remoto anterior ou o novo servidor não oferecer suporte à retomada de ponto de verificação (para nomes remotos HTTP), o BITS reiniciará o download. Caso contrário, a transferência será retomada da mesma posição no novo servidor. O BITS não reinicia arquivos já transferidos.

Você pode usar esse método para alterar protocolos. No entanto, a URL resultante pode não estar bem formada. Por exemplo, alterar de \Server\Dir\File.ext para http://Server\Dir\File.ext pode não resolve. Considere usar o método IBackgroundCopyFile2::SetRemoteName .

Observe que esse método pode não encontrar URLs a serem alteradas se você tiver chamado o método IBackgroundCopyJobHttpOptions::SetSecurityFlags e definir o sinalizador BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT . Essa política altera a URL original para a URL final redirecionada se a URL for redirecionada.

Exemplos

O exemplo a seguir mostra como chamar o método ReplaceRemotePrefix para alterar o nome do servidor de uma URL. O exemplo pressupõe que a variável IBackgroundCopyJob , pJob, seja válida e o trabalho contenha um ou mais arquivos.

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

Requisitos

Confira também

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3