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

[アーティクル]
03/14/2023

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

構文

HRESULT AddFile(
  [in] LPCWSTR RemoteUrl,
  [in] LPCWSTR LocalName
);

パラメーター

[in] RemoteUrl

サーバー上のファイルの名前を含む Null で終わる文字列。リモート名の指定については、BG_FILE_INFO構造体の RemoteName メンバーと解説に関するセクションを参照してください。

[in] LocalName

クライアント上のファイルの名前を含む Null で終わる文字列。ローカル名の指定については、BG_FILE_INFO構造体の LocalName メンバーと解説に関するセクションを参照してください。

戻り値

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

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

注釈

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

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

アップロードジョブに含めることができるファイルは 1 つだけです。 2 つ目のファイルを追加すると、メソッドは 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 を使用するときのベストプラクティス」を参照してください。

例

ジョブに 1 つのファイルを追加する例については、「ジョブへのファイルの追加」を参照してください。

要件

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