Metodo IBackgroundCopyJob::AddFileSet (bits.h)

Articolo
08/22/2023

Aggiunge più file a un processo.

Sintassi

HRESULT AddFileSet(
  [in] ULONG        cFileCount,
  [in] BG_FILE_INFO *pFileSet
);

Parametri

[in] cFileCount

Numero di elementi in paFileSet.

[in] pFileSet

Matrice di strutture BG_FILE_INFO che identificano i nomi di file locali e remoti dei file da trasferire.

I processi di caricamento sono limitati a un singolo file. Se la matrice contiene più di un elemento o il processo contiene già un file, il metodo restituisce BG_E_TOO_MANY_FILES.

Valore restituito

Questo metodo restituisce i valori HRESULT seguenti, nonché altri.

Codice restituito	Descrizione
S_OK	I file sono stati aggiunti correttamente al processo.
BG_E_TOO_MANY_FILES	I processi di caricamento possono contenere solo un file; non è possibile aggiungere più file al processo. Nessuno dei file nella matrice è stato aggiunto al processo.
BG_E_TOO_MANY_FILES_IN_JOB	L'impostazione maxFilesPerJob Criteri di gruppo determina il numero di file che un processo può contenere. L'aggiunta del file al processo supera il limite MaxFilesPerJob.
E_INVALIDARG	È possibile ricevere questo errore per uno dei motivi seguenti: Il nome del file locale o remoto non è valido. Il nome del file remoto usa un protocollo non supportato. Il nome del file locale è stato specificato usando un percorso relativo.
E_ACCESSDENIED	L'utente non dispone dell'autorizzazione per scrivere nella directory specificata nel client.

Commenti

È più efficiente chiamare il metodo AddFileSet quando si aggiungono più file a un processo che per chiamare il metodo IBackgroundCopyJob::AddFile in un ciclo. Per aggiungere un singolo file a un processo, chiamare il metodo AddFile . Per altre informazioni, vedere Aggiunta di file a un processo.

Per aggiungere un file a un processo da cui BITS scarica intervalli di dati dal file, chiamare il metodo IBackgroundCopyJob3::AddFileWithRanges .

I processi di caricamento possono contenere solo un file. Se si aggiungono più file, il metodo restituisce BG_E_TOO_MANY_FILES.

Per i download, BITS garantisce che la versione di un file (in base alle dimensioni e alla data del file, non al contenuto) che il trasferimento sarà coerente; tuttavia, non garantisce che un set di file sarà coerente. Ad esempio, se BITS si trova al centro del download del secondo di due file al momento dell'aggiornamento dei file nel server, BITS riavvia il download del secondo file; tuttavia, il primo file non viene scaricato di nuovo.

Si noti che se si possiede il file scaricato dal server, è necessario creare un nuovo URL per ogni nuova versione del file. Se si usa lo stesso URL per le nuove versioni del file, alcuni server proxy possono servire dati non aggiornati dalla cache perché non verificano con il server originale se il file non è aggiornato.

Per i caricamenti, BITS genera un errore se il file locale viene modificato durante il trasferimento del file. Il codice di errore è BG_E_FILE_CHANGED e il contesto è BG_ERROR_CONTEXT_LOCAL_FILE.

BITS trasferisce i file all'interno di un processo in sequenza. Se si verifica un errore durante il trasferimento di un file, il processo passa a uno stato di errore e non vengono elaborati più file all'interno del processo finché non viene risolto l'errore.

Per impostazione predefinita, un utente può aggiungere fino a 200 file a un processo. Questo limite non si applica agli amministratori o agli account di servizio. Per modificare il valore predefinito, impostare i criteri di gruppo MaxFilesPerJob .

Prima di Windows Vista: Non esiste alcun limite al numero di file che un utente può aggiungere a un processo.

Per i problemi di scalabilità, vedere Procedure consigliate per l'uso di BITS.

Esempio

Nell'esempio seguente viene illustrato come aggiungere più file a un processo di download. L'esempio presuppone che il puntatore dell'interfaccia IBackgroundCopyJob sia valido.

HRESULT hr;
IBackgroundCopyJob* pJob;
BG_FILE_INFO* paFiles = NULL;
int idx = 0;
int nCount = 0;  //Number of files to add to the job.
LPWSTR pszLocalName = NULL;
LPWSTR pszRemoteName = NULL;

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP
Server minimo supportato	Windows Server 2003
Piattaforma di destinazione	Windows
Intestazione	bits.h
Libreria	Bits.lib
DLL	QmgrPrxy.dll