Agregar archivos a un trabajo

Un trabajo contiene uno o varios archivos que desea transferir. Use uno de los métodos siguientes para agregar archivos a un trabajo:

IBackgroundCopyJob::AddFile

Agrega un único archivo a un trabajo.

IBackgroundCopyJob::AddFileSet

Agrega uno o varios archivos a un trabajo. Si va a agregar varios archivos, es más eficaz llamar a este método que llamar al método AddFile en un bucle.

IBackgroundCopyJob3::AddFileWithRanges

Agrega un único archivo a un trabajo. Use este método si desea descargar intervalos de datos de un archivo. Este método solo se puede usar para los trabajos de descarga.

Al agregar un archivo a un trabajo, especifique el nombre remoto y el nombre local del archivo. Para obtener más información sobre el formato de los nombres de archivo locales y remotos, consulte la estructura BG_FILE_INFO .

Un trabajo de carga solo puede contener un archivo. Los métodos IBackgroundCopyJob::AddFile e IBackgroundCopyJob::AddFileSet devuelven BG_E_TOO_MANY_FILES si intenta agregar más de un archivo a un trabajo de carga. Si necesita cargar más de un archivo, considere la posibilidad de usar un archivo CAB o ZIP.

Para los trabajos de descarga, BITS limita el número de archivos que un usuario puede agregar a un trabajo a 200 archivos y el número de intervalos de un archivo a 500 intervalos. Estos límites no se aplican a los administradores o servicios. Para cambiar estos límites predeterminados, consulte Directivas de grupo.

El propietario del trabajo o un usuario con privilegios de administrador pueden agregar archivos al trabajo en cualquier momento antes de llamar al método IBackgroundCopyJob::Complete o al método IBackgroundCopyJob::Cancel .

Si necesita cambiar el nombre remoto del archivo después de agregar el archivo al trabajo, puede llamar al método IBackgroundCopyJob3::ReplaceRemotePrefix o al método IBackgroundCopyFile2::SetRemoteName . Use el método ReplaceRemotePrefix 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. Use el método SetRemoteName para cambiar el protocolo utilizado para transferir el archivo o para cambiar el nombre de archivo o la ruta de acceso.

BITS crea un archivo temporal en el directorio de destino y usa el archivo temporal para la transferencia de archivos. Para obtener el nombre de archivo temporal, llame al método IBackgroundCopyFile3::GetTemporaryName . BITS cambia el nombre de archivo temporal al nombre de archivo de destino cuando se llama al método Complete . BITS no especifica un descriptor de seguridad cuando crea el archivo temporal (el archivo hereda la información de ACL del directorio de destino). Si los datos transferidos son confidenciales, la aplicación debe especificar una ACL adecuada en el directorio de destino para evitar el acceso no autorizado.

Para mantener la información del propietario y la ACL con el archivo transferido, llame al método IBackgroundCopyJob3::SetFileACLFlags .

El propietario del trabajo (el usuario que creó el trabajo o el administrador que tomó posesión del trabajo) debe tener permisos para el archivo en el servidor, así como para el cliente. Por ejemplo, para descargar un archivo, el usuario debe tener permisos de lectura en el servidor y permisos de escritura en el directorio local del cliente.

En el ejemplo siguiente se muestra cómo agregar un único archivo al trabajo. En el ejemplo se supone que el puntero de la interfaz IBackgroundCopyJob , pJob, es válido.

HRESULT hr;
IBackgroundCopyJob* pJob;

//Replace parameters with variables that contain valid paths.
hr = pJob->AddFile(L"https://ServerName/Path/File.Ext", L"d:\\Path\\File.Ext");
if (SUCCEEDED(hr))
{
  //Do something.
}

En el ejemplo siguiente se muestra cómo agregar varios archivos al trabajo. En el ejemplo se supone que el puntero de la interfaz IBackgroundCopyJob , pJob, es válido y los nombres locales y remotos proceden de una lista de la interfaz de usuario.

HRESULT hr;
IBackgroundCopyJob* pJob;
BG_FILE_INFO* paFiles = NULL;
ULONG idx = 0;
ULONG nCount = 0;            //Set to the number of files to add to the job.
LPWSTR pszLocalName = NULL;  //Comes from the list in the user interface.
LPWSTR pszRemoteName = NULL; //Comes from the list in the user interface.

//Set nCount to the number of files to transfer.

//Allocate a block of memory to contain the array of BG_FILE_INFO structures.
//The BG_FILE_INFO structure contains the local and remote names of the 
//file being transferred.
paFiles = (BG_FILE_INFO*) malloc(sizeof(BG_FILE_INFO) * nCount);
if (NULL == paFiles)
{
  //Handle error
}
else
{
  //Add local and remote file name pairs to the memory block. 
  for (idx=0; idx<nCount; idx++)
  {
    //Set pszLocalName to point to an LPWSTR that contains the local name or
    //allocate memory for pszLocalName and copy the local name to pszLocalName.
    (paFiles+idx)->LocalName = pszLocalName;

    //Set pszRemoteName to point to an LPWSTR that contains the remote name or
    //allocate memory for pszRemoteName and copy the remote name to pszRemoteName.
    (paFiles+idx)->RemoteName = pszRemoteName;
  }

  //Add the files to the job.
  hr = pJob->AddFileSet(nCount, paFiles);
  if (SUCCEEDED(hr))
  {
     //Do Something.
  }

  //Free the memory block for the array of BG_FILE_INFO structures. If you allocated
  //memory for the local and remote file names, loop through the array and free the
  //memory for the file names before you free paFiles.
  free(paFiles);
}