IBackgroundCopyJob3 ::AddFileWithRanges, méthode (bits2_0.h)

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 Membre RemoteName et Notes 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 Notes de la structure BG_FILE_INFO .

[in] RangeCount

Nombre d’éléments dans les 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 en chevauchement.

Valeur retournée

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

Remarques

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

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

BITS garantit que la version d’un fichier (en fonction de la taille et de la date, et non du contenu) qu’elle transfère sera cohérente ; toutefois, il ne garantit pas qu’un ensemble de fichiers sera cohérent. Par exemple, si BITS est au milieu du téléchargement de la seconde de 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.

Examples

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

Spécifications

Voir aussi

BG_FILE_RANGE

IBackgroundCopyFile2 ::GetFileRanges

IBackgroundCopyJob3

IBackgroundCopyJob ::AddFile