Méthode IBackgroundCopyJob3 ::AddFileWithRanges (bits2_0.h)

Article
02/26/2024

Ajoute un fichier à un travail de téléchargement et spécifie les plages du fichier que vous souhaitez télécharger.

Syntaxe

HRESULT AddFileWithRanges(
  [in] LPCWSTR          RemoteUrl,
  [in] LPCWSTR          LocalName,
  [in] DWORD            RangeCount,
  [in] BG_FILE_RANGE [] Ranges
);

Paramètres

[in] RemoteUrl

Chaîne terminée par null qui contient le nom du fichier sur le serveur. Pour plus d’informations sur la spécification du nom distant, consultez la section RemoteName member et Remarks de la structure BG_FILE_INFO .

À compter de BITS 3.0, le protocole SMB n’est pas pris en charge pour les plages.

BITS 2.5 et 2.0 : BITS prend en charge le protocole SMB pour les plages.

[in] LocalName

Chaîne terminée par null qui contient le nom du fichier sur le client. Pour plus d’informations sur la spécification du nom local, consultez la section Membre LocalName et Remarques de la structure BG_FILE_INFO .

[in] RangeCount

Nombre d’éléments dans plages.

[in] Ranges

Tableau d’une ou plusieurs structures BG_FILE_RANGE qui spécifient les plages à télécharger. Ne spécifiez pas de plages en double ou qui se chevauchent.

Valeur retournée

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

Code de retour	Description
S_OK	Succès
E_INVALIDARG	Vous pouvez recevoir cette erreur pour l’une des raisons suivantes : Le paramètre RangeCount est égal à zéro ; vous devez spécifier une ou plusieurs plages. 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_NOTIMPL	Vous ne pouvez pas appeler cette méthode pour les travaux de chargement ou de chargement-réponse ; Appelez cette méthode uniquement pour les travaux de téléchargement.
E_ACCESSDENIED	L’utilisateur n’est pas autorisé à écrire dans le répertoire spécifié sur le client.
BG_E_INVALID_RANGE	L’une des plages n’est pas valide. Par exemple, InitialOffset est défini sur BG_LENGTH_TO_EOF.
BG_E_OVERLAPPING_RANGES	Vous ne pouvez pas spécifier de plages en double ou qui se chevauchent. Note Les plages sont triées en fonction du décalage de la valeur, et non de la longueur. Si des plages sont entrées qui ont le même décalage, mais sont dans l’ordre inverse, cette erreur est retournée. Par exemple, si 100.5 et 100.0 sont entrés dans cet ordre, vous ne pourrez pas ajouter le fichier au travail.
BG_E_TOO_MANY_RANGES_IN_FILE	Le paramètre de stratégie de groupe MaxRangesPerFile détermine le nombre de plages que vous pouvez spécifier pour un fichier. L’ajout de ces plages dépasse la limite MaxRangesPerFile.
BG_E_INVALID_STATE	L’état du travail ne peut pas être BG_JOB_STATE_CANCELLED ou BG_JOB_STATE_ACKNOWLEDGED.

Remarques

Les plages sont écrites dans le fichier LocalName dans l’ordre indiqué. Par exemple, si Ranges identifie les octets 100-199, 900-999 et 400-499 du fichier distant, le fichier local sera de 300 octets. Les octets 0 à 99 du fichier local contiennent les octets 100 à 199 du fichier distant, les octets 100 à 199 du fichier local contiennent les octets 900 à 999 du fichier distant et les octets 200 à 299 du fichier local contiennent les octets 400 à 499 du fichier distant.

Le tableau suivant identifie les codes d’erreur possibles qui peuvent se produire après la reprise du travail. Ces erreurs placent le travail dans l’état BG_JOB_STATE_ERROR.

Code d'erreur	Description
BG_E_INVALID_SERVER_RESPONSE	BITS ne prend pas en charge les serveurs qui consolident des plages en double ou qui se chevauchent.
BG_E_INVALID_RANGE	L’une des plages se trouve en dehors des limites du fichier distant.
BG_E_INSUFFICIENT_RANGE_SUPPORT	Le serveur ne prend pas en charge les plages.

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 train de télécharger le deuxième des deux fichiers dans le travail 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.

Par défaut, un utilisateur peut ajouter jusqu’à 500 plages pour un fichier. Cette limite ne s’applique pas aux administrateurs ou aux comptes de service. Pour modifier la valeur par défaut, définissez la stratégie de groupe MaxRangesPerFile .

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

Pour de meilleures performances sur les transferts de fichiers avec Windows BranchCache, il est recommandé de définir la longueur de plage sur au moins 400 octets.

Exemples

L’exemple suivant montre comment appeler la méthode AddFileWithRanges pour spécifier les plages d’un fichier à télécharger. L’exemple suppose que la variable IBackgroundCopyJob , pJob, est valide.

    IBackgroundCopyJob *pJob;
    IBackgroundCopyJob3 *pJob3 = NULL;
    DWORD dwRangeCount = 3;                  //Number of elements in Ranges.
    BG_FILE_RANGE Ranges[] = {24, 17,        //Array of ranges to download (offset and length).
                              111, BG_LENGTH_TO_EOF,
                              83, 7
                             };

    //Need to query the IBackgroundCopyJob interface for an IBackgroundCopyJob3
    //interface pointer. The IBackgroundCopyJob3 interface contains the AddFileWithRanges method.
    hr = pJob->QueryInterface(__uuidof( IBackgroundCopyJob3 ), (void**)&pJob3;);
    if (S_OK == hr)
    {
         pJob->Release(); //No longer need the IBackgoundCopyJob interface pointer.

         //Add a file to the job and specify the ranges from the file to download.
         hr = pJob3->AddFileWithRanges(L"<REMOTENAMEGOESHERE>", L"<LOCALNAMEGOESHERE>",
                                       dwRangeCount, Ranges);
         if (FAILED(hr))
         {
              //Handle error.
              //Returns E_NOTIMPL if not a download job.
              //Returns E_INVALIDARG if dwRangeCount is zero or the remote or local name is invalid.
              //Returns BG_E_INVALID_RANGE if one of the ranges is invalid.
              //Returns BG_E_OVERLAPPING_RANGES if you specify overlapping or duplicate ranges.
         }

          pJob3->Release(); //Release the interface if you are done with it.
     }
    else
    {
         //Handle error. QueryInterface will return E_NOINTERFACE if the version of BITS
         //running on the computer is less than BITS 2.0.
    }

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista, Windows XP avec SP2 KB842773 sur Windows Server 2003 et Windows XP
Serveur minimal pris en charge	Windows Server 2008, Windows Server 2003 avec SP1
Plateforme cible	Windows
En-tête	bits2_0.h (include Bits.h)
Bibliothèque	Bits.lib
DLL	BitsPrx3.dll