Adicionando arquivos a um trabalho

Um trabalho contém um ou mais arquivos que você deseja transferir. Use um dos seguintes métodos para adicionar arquivos a um trabalho:

IBackgroundCopyJob::AddFile

Adiciona um único arquivo a um trabalho.

IBackgroundCopyJob::AddFileSet

Adiciona um ou mais arquivos a um trabalho. Se você estiver adicionando vários arquivos, é mais eficiente chamar esse método do que chamar o método AddFile em um loop.

IBackgroundCopyJob3::AddFileWithRanges

Adiciona um único arquivo a um trabalho. Use esse método se desejar baixar intervalos de dados de um arquivo. Você pode usar esse método somente para trabalhos de download.

Ao adicionar um arquivo a um trabalho, você especifica o nome remoto e o nome local do arquivo. Para obter detalhes sobre o formato dos nomes de arquivo local e remoto, consulte a estrutura BG_FILE_INFO.

Um trabalho de carregamento pode conter apenas um arquivo. Os métodos IBackgroundCopyJob::AddFile e IBackgroundCopyJob::AddFileSet retornam BG_E_TOO_MANY_FILES se você tentar adicionar mais de um arquivo a um trabalho de carregamento. Se você precisar carregar mais de um arquivo, considere usar um arquivo CAB ou ZIP.

Para trabalhos de download, o BITS limita o número de arquivos que um usuário pode adicionar a um trabalho a 200 arquivos e o número de intervalos de um arquivo a 500 intervalos. Esses limites não se aplicam a administradores ou serviços. Para alterar esses limites padrão, consulte Diretivas de Grupo.

O proprietário do trabalho ou um usuário com privilégios de administrador pode adicionar arquivos ao trabalho a qualquer momento antes de chamar o método IBackgroundCopyJob::Complete ou o método IBackgroundCopyJob::Cancel.

Se você precisar alterar o nome remoto do arquivo depois de adicionar o arquivo ao trabalho, poderá chamar o método IBackgroundCopyJob3::ReplaceRemotePrefix ou o método IBackgroundCopyFile2::SetRemoteName. Use o método ReplaceRemotePrefix para alterar a parte do servidor do nome remoto quando o servidor não estiver disponível ou para permitir que os usuários móveis se conectem ao servidor mais próximo. Use o método SetRemoteName para alterar o protocolo usado para transferir o arquivo ou para alterar o nome ou caminho do arquivo.

O BITS cria um arquivo temporário no diretório de destino e usa o arquivo temporário para a transferência de arquivos. Para obter o nome do arquivo temporário, chame o método IBackgroundCopyFile3::GetTemporaryName. O BITS altera o nome do arquivo temporário para o nome do arquivo de destino quando você chama o método Complete. O BITS não especifica um descritor de segurança quando cria o arquivo temporário (o arquivo herda as informações da ACL do diretório de destino). Se os dados transferidos forem confidenciais, o aplicativo deverá especificar uma ACL apropriada no diretório de destino para impedir o acesso não autorizado.

Para manter as informações de proprietário e ACL com o arquivo transferido, chame o método IBackgroundCopyJob3::SetFileACLFlags.

O proprietário do trabalho (o usuário que criou o trabalho ou o administrador que assumiu a propriedade do trabalho) deve ter permissões para o arquivo no servidor, bem como o cliente. Por exemplo, para baixar um arquivo, o usuário deve ter permissões de leitura no servidor e permissões de gravação no diretório local no cliente.

O exemplo a seguir mostra como adicionar um único arquivo ao trabalho. O exemplo assume que o ponteiro da interface IBackgroundCopyJob, pJob , é 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.
}

O exemplo a seguir mostra como adicionar vários arquivos ao trabalho. O exemplo assume que o ponteiro da interface IBackgroundCopyJob, pJob , é válido e os nomes locais e remotos vêm de uma lista na interface do usuário.

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);
}