Método IBackgroundCopyFile2::SetRemoteName (bits2_0.h)

Cambia el nombre remoto a una nueva dirección URL en un trabajo de descarga.

Sintaxis

HRESULT SetRemoteName(
  [in] LPCWSTR Val
);

Parámetros

[in] Val

Cadena terminada en NULL que contiene el nombre del archivo en el servidor. Para obtener información sobre cómo especificar el nombre remoto, vea la sección Miembro RemoteName y Comentarios de la estructura BG_FILE_INFO .

Valor devuelto

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

Código devuelto	Descripción
S_OK	Correcto
E_INVALIDARG	El nuevo nombre remoto es 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).
E_NOTIMPL	No se puede llamar a este método para cargar o cargar trabajos de respuesta; llame solo a este método 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, llama a este método si desea cambiar el protocolo usado para transferir el archivo (por ejemplo, de SMB a HTTP) o si desea cambiar el nombre de archivo o la ruta de acceso.

Este método no serializa cuando devuelve. Para serializar el cambio, suspenda el trabajo, llame a este método (si cambia varios archivos en el trabajo, use un bucle) y reanude el trabajo. Al llamar al método IBackgroundCopyJob::Resume , se serializa el cambio.

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.

Si el nombre remoto identifica una ruta de acceso de bloque de mensajes de servidor (SMB), en la tabla siguiente se identifican los posibles códigos de error que pueden producirse después de reanudar el trabajo. Estos errores colocan el trabajo en el estado BG_JOB_STATE_ERROR .

Código de error	Descripción
HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND)	No se encontró el directorio.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	No se encontró el archivo.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	El usuario no tiene acceso al archivo especificado en Val.

 

Ejemplos

En el ejemplo siguiente se muestra cómo llamar al método SetRemoteName para cambiar el nombre remoto de un archivo. En el ejemplo se supone que la variable IBackgroundCopyJob, pJob , es válida y el trabajo contiene uno o varios archivos.

     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.

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

IBackgroundCopyJob3::ReplaceRemotePrefix