Méthode IBackgroundCopyJob ::AddFileSet (bits.h)

Article
08/22/2023

Ajoute plusieurs fichiers à un travail.

Syntaxe

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

Paramètres

[in] cFileCount

Nombre d’éléments dans paFileSet.

[in] pFileSet

Tableau de structures BG_FILE_INFO qui identifient les noms de fichiers locaux et distants des fichiers à transférer.

Les travaux de chargement sont limités à un seul fichier. Si le tableau contient plusieurs éléments ou si le travail contient déjà un fichier, la méthode retourne BG_E_TOO_MANY_FILES.

Valeur retournée

Cette méthode retourne les valeurs HRESULT suivantes, ainsi que d’autres.

Code de retour	Description
S_OK	Les fichiers ont été correctement ajoutés au travail.
BG_E_TOO_MANY_FILES	Les travaux de chargement ne peuvent contenir qu’un seul fichier ; vous ne pouvez pas ajouter plusieurs fichiers au travail. Aucun des fichiers du tableau n’a été ajouté au travail.
BG_E_TOO_MANY_FILES_IN_JOB	Le paramètre de stratégie de groupe MaxFilesPerJob détermine le nombre de fichiers qu’un travail peut contenir. L’ajout du fichier au travail dépasse la limite MaxFilesPerJob.
E_INVALIDARG	Vous pouvez recevoir cette erreur pour l’une des raisons suivantes : Le nom de fichier local ou distant n’est pas valide. Le nom de fichier distant utilise un protocole non pris en charge. Le nom de fichier local a été spécifié à l’aide d’un chemin relatif.
E_ACCESSDENIED	L’utilisateur n’est pas autorisé à écrire dans le répertoire spécifié sur le client.

Remarques

Il est plus efficace d’appeler la méthode AddFileSet lors de l’ajout de plusieurs fichiers à un travail que d’appeler la méthode IBackgroundCopyJob ::AddFile dans une boucle. Pour ajouter un fichier unique à un travail, appelez la méthode AddFile . Pour plus d’informations, consultez Ajout de fichiers à un travail.

Pour ajouter un fichier à un travail à partir duquel BITS télécharge des plages de données à partir du fichier, appelez la méthode IBackgroundCopyJob3 ::AddFileWithRanges .

Les travaux de chargement ne peuvent contenir qu’un seul fichier. Si vous ajoutez plusieurs fichiers, la méthode retourne BG_E_TOO_MANY_FILES.

Pour les téléchargements, BITS garantit que la version d’un fichier (en fonction de la taille et de la date, et non du contenu) qu’il transfère sera cohérente ; Toutefois, cela ne garantit pas qu’un ensemble de fichiers sera cohérent. Par exemple, si BITS est en cours de téléchargement du deuxième des deux fichiers au moment où les fichiers sont mis à jour sur le serveur, BITS redémarre le téléchargement du deuxième fichier ; Toutefois, le premier fichier n’est pas téléchargé à nouveau.

Notez que si vous êtes propriétaire du fichier en cours de téléchargement à partir du serveur, vous devez créer une URL pour chaque nouvelle version du fichier. Si vous utilisez la même URL pour les nouvelles versions du fichier, certains serveurs proxy peuvent servir des données obsolètes à partir de leur cache, car ils ne vérifient pas avec le serveur d’origine si le fichier est obsolète.

Pour les chargements, BITS génère une erreur si le fichier local change pendant le transfert du fichier. Le code d’erreur est BG_E_FILE_CHANGED et le contexte est BG_ERROR_CONTEXT_LOCAL_FILE.

BITS transfère les fichiers au sein d’un travail de manière séquentielle. Si une erreur se produit lors du transfert d’un fichier, le travail passe à un état d’erreur et aucun autre fichier au sein du travail n’est traité tant que l’erreur n’est pas résolue.

Par défaut, un utilisateur peut ajouter jusqu’à 200 fichiers à un travail. Cette limite ne s’applique pas aux administrateurs ou aux comptes de service. Pour modifier la valeur par défaut, définissez les stratégies de groupe MaxFilesPerJob .

Avant Windows Vista : Il n’existe aucune limite quant au nombre de fichiers qu’un utilisateur peut ajouter à un travail.

Pour les problèmes d’extensibilité, consultez Meilleures pratiques lors de l’utilisation de BITS.

Exemples

L’exemple suivant montre comment ajouter plusieurs fichiers à un travail de téléchargement. L’exemple suppose que le pointeur d’interface IBackgroundCopyJob est valide.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP
Serveur minimal pris en charge	Windows Server 2003
Plateforme cible	Windows
En-tête	bits.h
Bibliothèque	Bits.lib
DLL	QmgrPrxy.dll