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

Reemplaza el texto inicial de todos los nombres remotos del trabajo de descarga por la cadena especificada.

Sintaxis

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

Parámetros

[in] OldPrefix

Cadena terminada en NULL que identifica el texto que se va a reemplazar en el nombre remoto. El texto debe comenzar al principio del nombre remoto.

[in] NewPrefix

Cadena terminada en NULL que contiene el texto de reemplazo.

Valor devuelto

Este método devuelve los siguientes valores devueltos, así como otros.

Código devuelto	Descripción
S_OK	Correcto
S_FALSE	No se encontraron coincidencias.
E_INVALIDARG	La aplicación de NewPrefix crea una dirección URL no válida o la nueva dirección URL es demasiado larga (la dirección URL no puede superar los 2200 caracteres). También puede recibir este código de retorno si OldPrefix o NewPrefix es una cadena vacía.
E_NOTIMPL	No se puede llamar a este método para cargar o responder trabajos; llame a este método solo para los trabajos de descarga.
BG_E_INVALID_STATE	El estado del trabajo no puede ser BG_JOB_STATE_CANCELLED ni BG_JOB_STATE_ACKNOWLEDGED.

Comentarios

Normalmente, se usa este método para cambiar la parte del servidor del nombre remoto cuando el servidor no está disponible o para permitir que los usuarios móviles se conecten al servidor más cercano. Este método cambia todos los nombres remotos coincidentes en el trabajo. Para cambiar el nombre remoto de un archivo específico, use el método IBackgroundCopyFile2::SetRemoteName .

El método ReplaceRemotePrefix realiza una búsqueda con distinción entre mayúsculas y minúsculas de todos los nombres remotos del trabajo. Si el texto inicial del nombre remoto coincide con la cadena en OldPrefix, BITS reemplaza el texto por la cadena que se encuentra en NewPrefix. Por ejemplo, para cambiar "http://Server/Path/File.ext" en "http://NewServerName/Path/File.ext", establezca OldPrefix en "http://Server" y NewPrefix en "http://NewServerName". Tenga en cuenta que BITS no realiza conversiones de configuración regional en la búsqueda.

Si la marca de tiempo o el tamaño de archivo del nuevo nombre remoto es diferente del nombre remoto anterior o el nuevo servidor no admite la reanudación del punto de control (para nombres remotos HTTP), BITS reinicia la descarga. De lo contrario, la transferencia se reanuda desde la misma posición en el nuevo servidor. BITS no reinicia los archivos ya transferidos.

Puede usar este método para cambiar los protocolos. Sin embargo, es posible que la dirección URL resultante no esté bien formada. Por ejemplo, cambiar de \Server\Dir\File.ext a http://Server\Dir\File.ext puede que no se resuelva. Considere la posibilidad de usar el método IBackgroundCopyFile2::SetRemoteName en su lugar.

Tenga en cuenta que es posible que este método no encuentre direcciones URL para cambiar si llamó al método IBackgroundCopyJobHttpOptions::SetSecurityFlags y estableció la marca BG_HTTP_REDIRECT_POLICY_ALLOW_REPORT . Esta directiva cambia la dirección URL original a la dirección URL redirigida final si se redirige la dirección URL.

Ejemplos

En el ejemplo siguiente se muestra cómo llamar al método ReplaceRemotePrefix para cambiar el nombre del servidor de una dirección URL. En el ejemplo se supone que la variable IBackgroundCopyJob , pJob, es válida y el trabajo contiene uno o varios archivos.

     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

Requisito	Value
Cliente mínimo compatible	Windows Vista, Windows XP con SP2,KB842773 en Windows Server 2003 y Windows XP
Servidor mínimo compatible	Windows Server 2008, Windows Server 2003 con SP1
Plataforma de destino	Windows
Encabezado	bits2_0.h (incluya Bits.h)
Library	Bits.lib
Archivo DLL	BitsPrx3.dll

Consulte también

IBackgroundCopyFile2::SetRemoteName

IBackgroundCopyJob3