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 AddFile método em um loop.

IBackgroundCopyJob3::AddFileWithRanges

Adiciona um único arquivo a um trabalho. Use esse método se quiser baixar intervalos de dados de um arquivo. Você pode usar esse método apenas 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 locais e remotos, 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 precisar de carregar mais do que um ficheiro, considere utilizar um ficheiro 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. Estes 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 precisar alterar o nome remoto do arquivo depois de adicioná-lo ao trabalho, você pode chamar o método IBackgroundCopyJob3::ReplaceRemotePrefix ou o métodoIBackgroundCopyFile2::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 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 do arquivo ou caminho.

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étodoIBackgroundCopyFile3::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 arquivo temporário (o arquivo herda as informações da ACL do diretório de destino). Se os dados transferidos forem confidenciais, o aplicativo deve especificar uma ACL apropriada no diretório de destino para impedir o acesso não autorizado.

Para manter as informações do proprietário e da ACL com o arquivo transferido, chame o 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 para 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 pressupõe que o ponteiro de 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 pressupõe que o ponteiro de 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);
}