ジョブへのファイルの追加

ジョブには、転送する 1 つ以上のファイルが含まれています。 ジョブにファイルを追加するには、次のいずれかの方法を使用します。

IBackgroundCopyJob::AddFile

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

IBackgroundCopyJob::AddFileSet

ジョブに 1 つ以上のファイルを追加します。 複数のファイルを追加する場合は、ループ内の AddFile メソッドを呼び出すよりも、このメソッドを呼び出す方が効率的です。

IBackgroundCopyJob3::AddFileWithRanges

ジョブに 1 つのファイルを追加します。 ファイルからデータの範囲をダウンロードする場合は、このメソッドを使用します。 この方法は、ダウンロード ジョブにのみ使用できます。

ジョブにファイルを追加するときは、リモート名とファイルのローカル名を指定します。 ローカル ファイル名とリモート ファイル名の形式の詳細については、 BG_FILE_INFO 構造を参照してください。

アップロード ジョブに含めることができるファイルは 1 つだけです。 IBackgroundCopyJob::AddFile および IBackgroundCopyJob::AddFileSet メソッドは、アップロード ジョブに複数のファイルを追加しようとするとBG_E_TOO_MANY_FILESを返します。 複数のファイルをアップロードする必要がある場合は、CAB または ZIP ファイルの使用を検討してください。

ダウンロード ジョブの場合、BITS は、ユーザーがジョブに追加できるファイルの数を 200 個のファイルに制限し、ファイルの範囲の数を 500 個の範囲に制限します。 これらの制限は、管理者またはサービスには適用されません。 これらの既定の制限を変更するには、「 グループ ポリシー」を参照してください。

ジョブの所有者または管理者特権を持つユーザーは、 IBackgroundCopyJob::Complete メソッドまたは IBackgroundCopyJob:: Cancel メソッドを呼び出す前に、いつでもジョブにファイル 追加できます。

ジョブにファイルを追加した後でファイルのリモート名を変更する必要がある場合は、 IBackgroundCopyJob3::ReplaceRemotePrefix メソッドまたは IBackgroundCopyFile2::SetRemoteName メソッドを呼び出すことができます。 ReplaceRemotePrefix メソッドを使用して、サーバーが使用できないときにリモート名のサーバー部分を変更するか、ローミング ユーザーが最も近いサーバーに接続できるようにします。 SetRemoteName メソッドを使用して、ファイルの転送に使用するプロトコルを変更したり、ファイル名またはパスを変更したりします。

BITS は、転送先ディレクトリに一時ファイルを作成し、ファイル転送に一時ファイルを使用します。 一時ファイル名を取得するには、 IBackgroundCopyFile3::GetTemporaryName メソッドを 呼び出します。 BITS は、 Complete メソッドを呼び出すときに、一時ファイル名を宛先ファイル名に変更します。 BITS は、一時ファイルを 作成 するときにセキュリティ記述子を指定しません (ファイルは宛先ディレクトリから ACL 情報を継承します)。 転送されたデータが機密性の高い場合、アプリケーションは、許可されていないアクセスを防ぐために、宛先ディレクトリに適切な ACL を指定する必要があります。

転送されたファイルで所有者と ACL の情報を保持するには、 IBackgroundCopyJob3::SetFileACLFlags メソッドを 呼び出します。

ジョブの所有者 (ジョブを作成したユーザーまたはジョブの 所有権を取得した 管理者) は、サーバー上のファイルとクライアントに対するアクセス許可を持っている必要があります。 たとえば、ファイルをダウンロードするには、ユーザーがサーバーに対する読み取りアクセス許可を持ち、クライアント上のローカル ディレクトリに対する書き込みアクセス許可を持っている必要があります。

次の例は、ジョブに 1 つのファイルを追加する方法を示しています。 この例では、 IBackgroundCopyJob インターフェイス ポインター pJob が有効であると想定しています。

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

次の例は、ジョブに複数のファイルを追加する方法を示しています。 この例では、 IBackgroundCopyJob インターフェイス ポインター pJob が有効であり、ローカル名とリモート名がユーザー インターフェイスのリストから取得されていることを前提としています。

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