Ajout de fichiers à un travail

Un travail contient un ou plusieurs fichiers que vous souhaitez transférer. Utilisez l’une des méthodes suivantes pour ajouter des fichiers à un travail :

IBackgroundCopyJob::AddFile

Ajoute un seul fichier à un travail.

IBackgroundCopyJob::AddFileSet

Ajoute un ou plusieurs fichiers à un travail. Si vous ajoutez plusieurs fichiers, il est plus efficace d’appeler cette méthode que d’appeler la méthode AddFile dans une boucle.

IBackgroundCopyJob3::AddFileWithRanges

Ajoute un seul fichier à un travail. Utilisez cette méthode si vous souhaitez télécharger des plages de données à partir d’un fichier. Vous pouvez utiliser cette méthode uniquement pour télécharger des travaux.

Lorsque vous ajoutez un fichier à un travail, vous spécifiez le nom distant et le nom local du fichier. Pour plus d’informations sur le format des noms de fichiers locaux et distants, consultez la structure BG_FILE_INFO .

Un travail de chargement ne peut contenir qu’un seul fichier. Les méthodes IBackgroundCopyJob::AddFile et IBackgroundCopyJob::AddFileSet retournent BG_E_TOO_MANY_FILES si vous essayez d’ajouter plusieurs fichiers à un travail de chargement. Si vous devez charger plusieurs fichiers, envisagez d’utiliser un fichier CAB ou ZIP.

Pour les travaux de téléchargement, BITS limite le nombre de fichiers qu’un utilisateur peut ajouter à un travail à 200 fichiers et le nombre de plages pour un fichier à 500 plages. Ces limites ne s’appliquent pas aux administrateurs ou aux services. Pour modifier ces limites par défaut, consultez Stratégies de groupe.

Le propriétaire du travail ou un utilisateur disposant de privilèges d’administrateur peut ajouter des fichiers au travail à tout moment avant d’appeler la méthode IBackgroundCopyJob::Complete ou la méthode IBackgroundCopyJob::Cancel .

Si vous devez modifier le nom distant du fichier après avoir ajouté le fichier au travail, vous pouvez appeler la méthode IBackgroundCopyJob3::ReplaceRemotePrefix ou la méthode IBackgroundCopyFile2::SetRemoteName . Utilisez la méthode ReplaceRemotePrefix pour modifier la partie serveur du nom distant lorsque le serveur n’est pas disponible ou pour permettre aux utilisateurs itinérants de se connecter au serveur le plus proche. Utilisez la méthode SetRemoteName pour modifier le protocole utilisé pour transférer le fichier ou modifier le nom ou le chemin d’accès du fichier.

BITS crée un fichier temporaire dans le répertoire de destination et utilise le fichier temporaire pour le transfert de fichiers. Pour obtenir le nom de fichier temporaire, appelez la méthode IBackgroundCopyFile3::GetTemporaryName . BITS remplace le nom du fichier temporaire par le nom du fichier de destination lorsque vous appelez la méthode Complete . BITS ne spécifie pas de descripteur de sécurité lorsqu’il crée le fichier temporaire (le fichier hérite des informations ACL du répertoire de destination). Si les données transférées sont sensibles, l’application doit spécifier une liste de contrôle d’accès appropriée sur le répertoire de destination pour empêcher tout accès non autorisé.

Pour conserver les informations propriétaire et ACL avec le fichier transféré, appelez la méthode IBackgroundCopyJob3::SetFileACLFlags .

Le propriétaire du travail (l’utilisateur qui a créé le travail ou l’administrateur qui a pris la propriété du travail) doit disposer des autorisations sur le fichier sur le serveur ainsi que sur le client. Par exemple, pour télécharger un fichier, l’utilisateur doit disposer d’autorisations de lecture sur le serveur et d’autorisations d’écriture dans le répertoire local sur le client.

L’exemple suivant montre comment ajouter un seul fichier au travail. L’exemple suppose que le pointeur d’interface IBackgroundCopyJob , pJob, est valide.

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

L’exemple suivant montre comment ajouter plusieurs fichiers au travail. L’exemple suppose que le pointeur d’interface IBackgroundCopyJob , pJob, est valide et que les noms locaux et distants proviennent d’une liste dans l’interface utilisateur.

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