Aggiunta di file a un processo

Un processo contiene uno o più file da trasferire. Usare uno dei metodi seguenti per aggiungere file a un processo:

IBackgroundCopyJob::AddFile

Aggiunge un singolo file a un processo.

IBackgroundCopyJob::AddFileSet

Aggiunge uno o più file a un processo. Se si aggiungono più file, è più efficiente chiamare questo metodo che chiamare il metodo AddFile in un ciclo.

IBackgroundCopyJob3::AddFileWithRanges

Aggiunge un singolo file a un processo. Utilizzare questo metodo se si desidera scaricare intervalli di dati da un file. È possibile usare questo metodo solo per i processi di download.

Quando si aggiunge un file a un processo, specificare il nome remoto e il nome locale del file. Per informazioni dettagliate sul formato dei nomi di file locali e remoti, vedere la struttura BG_FILE_INFO.

Un processo di caricamento può contenere un solo file. I metodi IBackgroundCopyJob::AddFile e IBackgroundCopyJob::AddFileSet restituiscono BG_E_TOO_MANY_FILES se si tenta di aggiungere più file a un processo di caricamento. Se è necessario caricare più file, è consigliabile usare un file CAB o ZIP.

Per i processi di download, BITS limita il numero di file che un utente può aggiungere a un processo a 200 file e il numero di intervalli per un file a 500 intervalli. Questi limiti non si applicano agli amministratori o ai servizi. Per modificare questi limiti predefiniti, vedere Criteri di gruppo.

Il proprietario del processo o di un utente con privilegi di amministratore può aggiungere file al processo in qualsiasi momento prima di chiamare il metodo IBackgroundCopyJob::Complete o il metodo IBackgroundCopyJob::Cancel.

Se è necessario modificare il nome remoto del file dopo aver aggiunto il file al processo, è possibile chiamare il metodo IBackgroundCopyJob3::ReplaceRemotePrefix o il metodo IBackgroundCopyFile2::SetRemoteName. Utilizzare il metodo ReplaceRemotePrefix per modificare la parte del server del nome remoto quando il server non è disponibile o consentire agli utenti mobili di connettersi al server più vicino. Utilizzare il metodo SetRemoteName per modificare il protocollo utilizzato per trasferire il file o per modificare il nome o il percorso del file.

BITS crea un file temporaneo nella directory di destinazione e usa il file temporaneo per il trasferimento di file. Per ottenere il nome del file temporaneo, chiamare il metodo IBackgroundCopyFile3::GetTemporaryName. BITS modifica il nome del file temporaneo nel nome del file di destinazione quando si chiama il metodo Complete. BITS non specifica un descrittore di sicurezza quando crea il file temporaneo ( il file eredita le informazioni ACL dalla directory di destinazione). Se i dati trasferiti sono sensibili, l'applicazione deve specificare un ACL appropriato nella directory di destinazione per impedire l'accesso non autorizzato.

Per mantenere le informazioni sul proprietario e sull'elenco di controllo di accesso con il file trasferito, chiamare il metodo IBackgroundCopyJob3::SetFileACLFlags.

Il proprietario del processo (l'utente che ha creato il processo o l'amministratore che ha preso la proprietà del processo) deve disporre delle autorizzazioni per il file nel server e per il client. Ad esempio, per scaricare un file, l'utente deve disporre delle autorizzazioni di lettura per il server e le autorizzazioni di scrittura per la directory locale nel client.

Nell'esempio seguente viene illustrato come aggiungere un singolo file al processo. Nell'esempio si presuppone che il puntatore all'interfaccia IBackgroundCopyJob , pJob, sia valido.

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.
}

Nell'esempio seguente viene illustrato come aggiungere più file al processo. Nell'esempio si presuppone che il puntatore all'interfaccia IBackgroundCopyJob, pJob , sia valido e i nomi locali e remoti provengano da un elenco nell'interfaccia utente.

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