IBackgroundCopyJob::AddFileSet メソッド (bits.h)

[アーティクル]
08/22/2023

ジョブに複数のファイルを追加します。

構文

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

パラメーター

[in] cFileCount

paFileSet 内の要素の数。

[in] pFileSet

転送するファイルのローカルファイル名とリモートファイル名を識別するBG_FILE_INFO構造体の配列。

アップロードジョブは 1 つのファイルに制限されます。配列に複数の要素が含まれている場合、またはジョブに既にファイルが含まれている場合、メソッドは BG_E_TOO_MANY_FILESを返します。

戻り値

このメソッドは、次の HRESULT 値と他の値を返します。

リターンコード	説明
S_OK	ファイルがジョブに正常に追加されました。
BG_E_TOO_MANY_FILES	アップロードジョブに含めることができるファイルは 1 つだけです。ジョブに複数のファイルを追加することはできません。配列内のファイルはジョブに追加されませんでした。
BG_E_TOO_MANY_FILES_IN_JOB	MaxFilesPerJob グループポリシー設定によって、ジョブに含めることができるファイルの数が決まります。ファイルをジョブに追加すると、MaxFilesPerJob の制限を超えています。
E_INVALIDARG	このエラーは、次のいずれかの理由で発生する可能性があります。ローカルまたはリモートのファイル名が無効です。リモートファイル名は、サポートされていないプロトコルを使用します。ローカルファイル名は、相対パスを使用して指定されました。
E_ACCESSDENIED	ユーザーには、クライアント上の指定されたディレクトリに書き込むアクセス許可がありません。

注釈

複数のファイルをジョブに追加するときに AddFileSet メソッドを呼び出す方が、ループ内で IBackgroundCopyJob::AddFile メソッドを呼び出すよりも効率的です。ジョブに 1 つのファイルを追加するには、 AddFile メソッドを呼び出します。詳細については、「ジョブへのファイルの追加」を参照してください。

BITS がファイルからデータ範囲をダウンロードするジョブにファイルを追加するには、 IBackgroundCopyJob3::AddFileWithRanges メソッドを呼び出します。

アップロードジョブに含めることができるファイルは 1 つだけです。複数のファイルを追加すると、メソッドは BG_E_TOO_MANY_FILESを返します。

ダウンロードの場合、BITS は転送するファイルのバージョン (コンテンツではなく、ファイルのサイズと日付に基づく) が一貫していることを保証します。ただし、一連のファイルが一貫性があることを保証するものではありません。たとえば、BITS がサーバーでファイルが更新されるときに 2 つ目のファイルの 2 つ目をダウンロードする途中にある場合、BITS は 2 番目のファイルのダウンロードを再開します。ただし、最初のファイルは再度ダウンロードされません。

サーバーからダウンロードするファイルを所有している場合は、ファイルの新しいバージョンごとに新しい URL を作成する必要があることに注意してください。新しいバージョンのファイルに同じ URL を使用する場合、一部のプロキシサーバーは、ファイルが古い場合は元のサーバーで検証されないため、キャッシュから古いデータを提供する可能性があります。

アップロードの場合、ファイルの転送中にローカルファイルが変更されると、BITS によってエラーが生成されます。エラーコードがBG_E_FILE_CHANGEDされ、コンテキストがBG_ERROR_CONTEXT_LOCAL_FILE。

BITS は、ジョブ内のファイルを順次転送します。ファイルの転送中にエラーが発生した場合、ジョブはエラー状態に移行し、エラーが解決されるまでジョブ内のそれ以上のファイルは処理されません。

既定では、ユーザーは最大 200 個のファイルをジョブに追加できます。この制限は、管理者またはサービスアカウントには適用されません。既定値を変更するには、 MaxFilesPerJob グループポリシーを設定します。

Windows Vista より前: ユーザーがジョブに追加できるファイルの数に制限はありません。

スケーラビリティの問題については、「BITS を使用するときのベストプラクティス」を参照してください。

例

次の例は、ダウンロードジョブに複数のファイルを追加する方法を示しています。この例では、 IBackgroundCopyJob インターフェイスポインターが有効であることを前提としています。

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

要件

要件	値
サポートされている最小のクライアント	Windows XP
サポートされている最小のサーバー	Windows Server 2003
対象プラットフォーム	Windows
ヘッダー	bits.h
Library	Bits.lib
[DLL]	QmgrPrxy.dll