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

  • [アーティクル]

ジョブには、転送する 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 メソッドを呼び出します。

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

次の例は、単一のファイルをジョブに追加する方法を示しています。 この例では、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);
}