Metodo IBackgroundCopyJob::AddFile (bits.h)

Articolo
03/14/2023

Aggiunge un singolo file al processo.

Sintassi

HRESULT AddFile(
  [in] LPCWSTR RemoteUrl,
  [in] LPCWSTR LocalName
);

Parametri

[in] RemoteUrl

Stringa con terminazione null contenente il nome del file nel server. Per informazioni sulla specifica del nome remoto, vedere la sezione RemoteName member and Notes della struttura BG_FILE_INFO .

[in] LocalName

Stringa con terminazione null contenente il nome del file nel client. Per informazioni sulla specifica del nome locale, vedere la sezione LocalName member and Notes della struttura BG_FILE_INFO .

Valore restituito

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

Codice restituito	Descrizione
S_OK	Il file è stato aggiunto correttamente al processo.
BG_E_TOO_MANY_FILES	I processi di caricamento possono contenere solo un file; non è possibile aggiungere un altro file 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

Per aggiungere più file alla volta a un processo, chiamare il metodo IBackgroundCopyJob::AddFileSet . È più efficiente chiamare il metodo AddFileSet quando si aggiungono più file a un processo che per chiamare il metodo AddFile in un ciclo. 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 aggiunge un secondo 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 nel processo al momento in cui i file vengono aggiornati 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

Per un esempio che aggiunge un singolo file a un processo, vedere Aggiunta di file a un processo.

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