IBackgroundCopyJob

IBackgroundCopyJob インターフェイスを使用すると、ジョブへのファイルの追加、ジョブの優先度の設定、ジョブの状態の取得、およびジョブの開始と停止を行えます。

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

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

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

ジョブに複数のファイルを追加する場合、IBackgroundCopyJob::AddFile メソッドをループで呼び出すよりも AddFileSet メソッドを呼び出すほうが効率的です。ジョブに 1 つのファイルを追加するには、AddFile メソッドを呼び出します。詳細については、Adding Files to a Job を参照してください。

BITS がファイルの一部の範囲のみをダウンロードするようなファイルをジョブに追加するには、IBackgroundCopyJob3::AddFileWithRanges メソッドを呼び出します。

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

ダウンロードの場合、BITS は転送するファイルのバージョン(内容ではなく、ファイルサイズと日付に基づく)の一貫性を保証しますが、ファイルの集合としての一貫性は保証しません。たとえば、2 つのファイルのうち 2 番目のファイルをダウンロードしている最中にサーバー側でファイルが更新された場合、BITS は 2 番目のファイルのダウンロードを再開しますが、1 番目のファイルは再ダウンロードされません。

なお、サーバー上のダウンロード対象ファイルを自分で所有している場合は、ファイルの新しいバージョンごとに新しい URL を作成してください。新しいバージョンに同じ URL を使用すると、一部のプロキシサーバーは元のサーバーにファイルが古くなっていないかを確認しないため、キャッシュ内の古いデータを返す場合があります。

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

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

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

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

スケーラビリティに関する注意点については、Best Practices When Using BITS を参照してください。

例

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

HRESULT hr;
IBackgroundCopyJob* pJob;
BG_FILE_INFO* paFiles = NULL;
int idx = 0;
int nCount = 0;  //ジョブに追加するファイルの数。
LPWSTR pszLocalName = NULL;
LPWSTR pszRemoteName = NULL;

//転送するファイルの数を nCount に設定します。

//BG_FILE_INFO 構造体の配列を格納するメモリブロックを割り当てます。
//BG_FILE_INFO 構造体には、転送するファイルのローカル名と
//リモート名が含まれます。
paFiles = (BG_FILE_INFO*) malloc(sizeof(BG_FILE_INFO) * nCount);
if (NULL == paFiles)
{
  //エラー処理
}
else
{
  //ローカル名とリモート名のペアをメモリブロックに追加します。
  for (idx=0; idx<nCount; idx++)
  {
    //ローカル名を含む LPWSTR を pszLocalName に指定するか、
    //pszLocalName のメモリを割り当ててローカル名をコピーします。
    (paFiles+idx)->LocalName = pszLocalName;

    //リモート名を含む LPWSTR を pszRemoteName に指定するか、
    //pszRemoteName のメモリを割り当ててリモート名をコピーします。
    (paFiles+idx)->RemoteName = pszRemoteName;
  }

  //ファイルをジョブに追加します。
  hr = pJob->AddFileSet(nCount, paFiles);
  if (SUCCEEDED(hr))
  {
     //何らかの処理を行います。
  }

  //BG_FILE_INFO 構造体の配列用のメモリブロックを解放します。ローカル名と
  //リモート名のためにメモリを割り当てた場合は、paFiles を解放する前に配列を
  //ループしてファイル名のメモリを解放してください。
  free(paFiles);
}

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

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

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

1 つのジョブに一度に複数のファイルを追加するには、 IBackgroundCopyJob::AddFileSet メソッドを呼び出します。ジョブに複数のファイルを追加する場合、AddFile メソッドをループで呼び出すよりも AddFileSet メソッドを呼び出すほうが効率的です。詳細については、Adding Files to a Job を参照してください。

BITS がファイルの一部の範囲のみをダウンロードするようなファイルをジョブに追加するには、IBackgroundCopyJob3::AddFileWithRanges メソッドを呼び出します。

アップロードジョブに含められるファイルは 1 つだけです。2 つ目のファイルを追加した場合、このメソッドは BG_E_TOO_MANY_FILES を返します。

ダウンロードの場合、BITS は転送するファイルのバージョン(内容ではなく、ファイルサイズと日付に基づく)の一貫性を保証しますが、ファイルの集合としての一貫性は保証しません。たとえば、ジョブ内の 2 つのファイルのうち 2 番目のファイルをダウンロードしている最中にサーバー側でファイルが更新された場合、BITS は 2 番目のファイルのダウンロードを再開しますが、1 番目のファイルは再ダウンロードされません。

なお、サーバー上のダウンロード対象ファイルを自分で所有している場合は、ファイルの新しいバージョンごとに新しい URL を作成してください。新しいバージョンに同じ URL を使用すると、一部のプロキシサーバーは元のサーバーにファイルが古くなっていないかを確認しないため、キャッシュ内の古いデータを返す場合があります。

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

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

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

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

スケーラビリティに関する注意点については、Best Practices When Using BITS を参照してください。

例

1 つのファイルをジョブに追加する例については、 Adding Files to a Job を参照してください。

ジョブ内のファイルを列挙するために使用する IEnumBackgroundCopyFiles インターフェイスポインターを取得します。

このメソッドは、成功した場合は S_OK を、エラーの場合は標準的な COM の HRESULT 値のいずれかを返します。

ジョブを中断します。新しいジョブ、エラー状態のジョブ、およびファイルの転送が完了したジョブは自動的に中断されます。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ジョブを正常に中断しました。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。

新しいジョブを開始するか、中断されているジョブを再開します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ジョブが正常に再開されました。
BG_E_EMPTY	転送するファイルがありません。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。

ジョブを作成すると、そのジョブは最初は中断状態になります。Resume を呼び出すと、ジョブは中断状態からキュー状態に移行します。スケジューラーがそのジョブの転送順になったと判断するまで、ジョブはキュー状態のままです。なお、このメソッドを呼び出す前に、ジョブには 1 つ以上のファイルが含まれている必要があります。ジョブの種類が BG_JOB_TYPE_UPLOAD_REPLY で、応答ファイルの名前を指定したい場合は、 Resume を呼び出す前に IBackgroundCopyJob2::SetReplyFileName メソッドを呼び出してください。

ジョブが BG_JOB_STATE_TRANSIENT_ERROR または BG_JOB_STATE_ERROR 状態にある場合は、エラーを修正した後に Resume メソッドを呼び出してジョブを再開します。

転送キューからジョブを削除し、クライアント(ダウンロード)およびサーバー(アップロード)上の関連する一時ファイルを削除します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ジョブが正常にキャンセルされました。
BG_S_UNABLE_TO_DELETE_FILES	ジョブは正常にキャンセルされましたが、サービスはジョブに関連付けられた一時ファイルを削除できませんでした。
BG_E_INVALID_STATE	状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であるジョブはキャンセルできません。

ジョブは いつでもキャンセルできますが、キャンセル後にジョブを復元することはできません。

アップロードジョブの場合、サーバーが利用できないときは、BITS がキューからジョブを削除するまでに遅延が生じることがあります。BITS は最大 24 時間にわたって BITS サーバーにキャンセル要求を定期的に送信します。24 時間以内にサーバーが応答しない場合、BITS はキューからジョブを削除します。無進行タイムアウト期間が 24 時間未満の場合、BITS はその無進行タイムアウト期間で再試行を制限します。

Cancel メソッドは、アップロードが完了していない場合にそのアップロードをキャンセルします。アップロードが完了しており、ジョブの種類が BG_JOB_TYPE_UPLOAD_REPLY の場合、このメソッドは応答をキャンセルします。

ジョブを終了し、転送されたファイルをクライアントに保存します。

このメソッドは以下の HRESULT 値を返します。また、転送されたファイルの一時コピーを指定された名前に変更する処理に関連するエラーが返されることもあります。

戻り値	説明
S_OK	すべてのファイルが正常に転送されました。
BG_S_PARTIAL_COMPLETE	一部のファイルが正常に転送されました。
BG_S_UNABLE_TO_DELETE_FILES	ジョブは正常に完了しましたが、サービスはジョブに関連付けられた一時ファイルを削除できませんでした。
BG_E_INVALID_STATE	ダウンロードの場合、ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。 アップロードの場合、ジョブの状態は BG_JOB_STATE_TRANSFERRED でなければなりません。

ダウンロードしたファイルは、 Complete メソッドを呼び出すまで利用できません。BITS がファイルを正常に転送した後に Complete メソッドを呼び出してください。このメソッドは、一時的なダウンロードファイルを最終的な保存先の名前に変更し、キューからジョブを削除します。なお、アップロードの一時ファイルはサーバーが最後のフラグメントを受信した時点で BITS が名前を変更します。そのため、ダウンロードジョブではネットワーク接続が必要ですが、アップロードジョブでは不要です。

ジョブの状態が BG_JOB_STATE_TRANSFERRED であれば、すべてのファイルが正常に転送されています。ジョブの状態を確認するには、 IBackgroundCopyJob::GetState メソッドを呼び出します。また、 IBackgroundCopyCallback インターフェイスを実装して、すべてのファイルがクライアントに転送された時点で通知を受け取ることもできます。

90 日以内(既定の JobInactivityTimeout グループポリシー)に Complete メソッドまたは IBackgroundCopyJob::Cancel メソッドを呼び出さない場合、サービスはジョブをキャンセルします。サービスがジョブをキャンセルすると、ダウンロードされたファイルと応答ファイルはクライアントから利用できなくなります。ジョブのキャンセルは、既に正常にアップロードされたファイルには影響しません。

HRESULT が S_OK または BG_S_PARTIAL_COMPLETE の場合、BITS は転送キューからジョブを削除します。BITS がすべての一時ファイルの名前を変更できなかった場合、ジョブは転送キューに残ります。正常に名前が変更されたファイルはユーザーが利用できます。アプリケーションが問題を修正して Complete メソッドを再度呼び出すか、 IBackgroundCopyJob::Cancel メソッドを呼び出してジョブをキャンセルするまで、ジョブはキューに残ります(状態は BG_JOB_STATE_TRANSFERRED)。ダウンロードジョブで名前が変更されなかったファイルを判別するには、 BG_FILE_PROGRESS 構造体の Completed メンバーを参照してください。

ダウンロードジョブでは、転送処理中のいつでも Complete メソッドを呼び出せますが、保存されるのはこのメソッドを呼び出す前にクライアントへ正常に転送されたファイルのみです。たとえば、BITS が 5 つのファイルのうち 3 番目を処理している最中に Complete メソッドを呼び出した場合、保存されるのは最初の 2 つのファイルだけです。どのファイルが転送済みかを判別するには、 IBackgroundCopyFile::GetProgress メソッドを呼び出し、 BG_FILE_PROGRESS 構造体の BytesTransferred メンバーと BytesTotal メンバーを比較します。

アップロードジョブでは、ジョブの状態が BG_JOB_STATE_TRANSFERRED の場合にのみ Complete メソッドを呼び出せます。

BITS は、第三者による改ざんに対して転送されたファイルの整合性を保証しません。クライアントは、 Complete メソッドを呼び出した後に、転送されたファイルを検証する整合性チェックを実装できます。

ファイルの所有者は、この呼び出しを行ったユーザーになります。たとえば、管理者が他人のジョブを完了させた場合、ジョブの所有者ではなく管理者がファイルを所有します。

BITS 1.2 以前: Complete メソッドを呼び出したユーザーに関係なく、ファイルの所有者はジョブの所有者になります。

キュー内でジョブを識別するために使用する識別子を取得します。

このメソッドは、成功した場合は S_OK を、エラーの場合は標準的な COM の HRESULT 値のいずれかを返します。

識別子は、ジョブを 作成したときにサービスによって生成されます。この識別子を使用してジョブの IBackgroundCopyJob インターフェイスポインターを取得するには、 IBackgroundCopyManager::GetJob メソッドを呼び出します。

ファイルのダウンロードやアップロードなど、実行される転送の種類を取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	転送の種類が正常に取得されました。
E_INVALIDARG	pJobType パラメーターを NULL にすることはできません。

転送の種類は、 ジョブを作成するときに指定します。

転送されたバイト数やファイル数など、ジョブに関する進行状況の情報を取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	進行状況の情報が正常に取得されました。
E_INVALIDARG	pProgress パラメーターを NULL にすることはできません。

ジョブが作成された時刻や最後に変更された時刻など、ジョブに関するタイムスタンプを取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	タイムスタンプが正常に取得されました。
E_INVALIDARG	pTimes パラメーターを NULL にすることはできません。

ジョブの状態を取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ジョブの状態が正常に取得されました。
E_INVALIDARG	パラメーター pJobState を NULL にすることはできません。

ジョブがエラー状態になったとき、またはジョブ内のすべてのファイルの転送が完了したときを知りたい場合は、このメソッドでジョブの状態をポーリングするか、イベント発生時に通知を受け取るように登録します。イベント通知を受け取るための登録の詳細については、 IBackgroundCopyCallback インターフェイスを参照してください。

例

IBackgroundCopyManager::GetJob メソッドのサンプルコードを参照してください。

エラー発生後にエラーインターフェイスを取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	エラーオブジェクトが正常に生成されました。
BG_E_ERROR_INFORMATION_UNAVAILABLE	エラーインターフェイスは、エラーが発生した後(BG_JOB_STATE_ERROR または BG_JOB_STATE_TRANSIENT_ERROR)で、かつ BITS がデータの転送を開始する(BG_JOB_STATE_TRANSFERRING)前にのみ利用できます。

ジョブは、致命的なエラーが発生した場合、または一時的なエラーに対する無進行タイムアウト期間(GetNoProgressTimeout メソッドで取得)が経過した場合にエラー状態になります。ジョブがエラー状態かどうかを判別するには、次のいずれかの方法を使用します。

• ジョブの状態をポーリングするには、 IBackgroundCopyJob::GetState メソッドを呼び出します。状態が BG_JOB_STATE_ERROR であれば、ジョブはエラー状態です。
• エラー発生時に通知を受け取るには、 IBackgroundCopyCallback インターフェイス(特に JobError メソッド)を実装します。その後、 IBackgroundCopyJob::SetNotifyInterface メソッドを呼び出してコールバックを登録し、 IBackgroundCopyJob::SetNotifyFlags メソッドを呼び出して BG_NOTIFY_JOB_ERROR フラグを設定します。

IBackgroundCopyError インターフェイスには、エラーの原因を特定し、転送処理を続行できるかどうかを判断するための情報が含まれます。エラーの原因を特定した後は、次のいずれかを行います。

• ジョブをキャンセルするには、 IBackgroundCopyJob::Cancel メソッドを呼び出します。
• エラー発生前に正常に転送されたファイルを保存するには、 IBackgroundCopyJob::Complete メソッドを呼び出します。
• ジョブの処理を最後まで行うには、問題を修正してから IBackgroundCopyJob::Resume メソッドを呼び出します。

ジョブが 90 日間(既定の JobInactivityTimeout グループポリシー)エラー状態のままである場合、サービスはキューからジョブを削除し、クライアント上の一時ファイルを削除します。ジョブの削除は、既に正常にアップロードされたファイルには影響しません。

アップロード応答ジョブにおいて、アップロード、応答、サーバーアプリケーションのどの部分が失敗したかを判別するには、 IBackgroundCopyError::GetError メソッドを呼び出して、エラーが発生した コンテキストを取得します。コンテキストが BG_ERROR_CONTEXT_REMOTE_APPLICATION であれば、サーバーアプリケーションが失敗しています。エラーがアップロードまたは応答に関するものである場合、コンテキストは BG_ERROR_CONTEXT_REMOTE_FILE になります。 BG_JOB_REPLY_PROGRESS 構造体の BytesTotal メンバーが BG_SIZE_UNKNOWN であれば、アップロードが失敗しています。そうでない場合は、応答が失敗しています。

例

Handling Errors トピックのサンプルコードを参照してください。

ジョブの所有者の ID を取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ジョブの所有者の ID が正常に取得されました。
E_INVALIDARG	ppOwner パラメーターを NULL にすることはできません。

SID の文字列形式を、ユーザーインターフェイスでの表示に適した domain\user-name 形式に変換するには、次の関数を呼び出します。

• 文字列形式の SID を SID に変換するには、 ConvertStringSidToSid 関数を呼び出します。
• SID に関連付けられたドメインとユーザー名を取得するには、 LookupAccountSid 関数を呼び出します。

ジョブの表示名を指定します。通常、表示名はユーザーインターフェイスでジョブを識別するために使用します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	表示名が正常に設定されました。
E_INVALIDARG	pDisplayName パラメーターを NULL にすることはできません。または、名前が 256 文字を超えています。
BG_E_STRING_TOO_LONG	表示名が 256 文字を超えています。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。

表示名は、ジョブを作成するときに最初に設定されます。ジョブ作成時の表示名の指定方法の詳細については、 IBackgroundCopyManager::CreateJob メソッドを参照してください。

ジョブの表示名を取得します。通常、表示名はユーザーインターフェイスでジョブを識別するために使用します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	表示名が正常に取得されました。
E_INVALIDARG	ppDisplayName パラメーターを NULL にすることはできません。

ジョブの説明を設定します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ジョブの説明が正常に設定されました。
E_INVALIDARG	pDescription パラメーターを NULL にすることはできません。
BG_E_STRING_TOO_LONG	説明が 1,024 文字を超えています。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。

ジョブの説明を取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ジョブの説明が正常に取得されました。
E_INVALIDARG	パラメーター ppDescription を NULL にすることはできません。

ジョブの優先度レベルを指定します。優先度レベルによって、転送キュー内の他のジョブと比べてジョブがいつ処理されるかが決まります。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ジョブの優先度が正常に設定されました。
E_NOTIMPL	Priority の値が BG_JOB_PRIORITY 列挙型で定義されていません。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。

ジョブの優先度レベルを取得します。優先度レベルによって、転送キュー内の他のジョブと比べてジョブがいつ処理されるかが決まります。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	優先度レベルが正常に取得されました。
E_INVALIDARG	pPriority パラメーターを NULL にすることはできません。

ジョブ転送完了イベントなど、受け取りたいイベント通知の種類を指定します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	イベント通知の種類が正常に設定されました。
E_NOTIMPL	NotifyFlags の値が無効です。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。

イベント通知を受け取るには、 SetNotifyFlags メソッドを IBackgroundCopyJob::SetNotifyInterface メソッドおよび IBackgroundCopyJob2::SetNotifyCmdLine メソッドと組み合わせて使用します。

例

IBackgroundCopyJob::SetNotifyInterface メソッドのサンプルコードを参照してください。

ジョブのイベント通知フラグを取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	イベント通知フラグが正常に取得されました。
E_INVALIDARG	pNotifyFlags のアドレスを渡す必要があります。

IBackgroundCopyCallback インターフェイスの実装を BITS に登録します。ジョブ関連のイベント通知を受け取るには、IBackgroundCopyCallback インターフェイスを使用します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	通知インターフェイスポインターが正常に設定されました。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。

このメソッドは、 IBackgroundCopyCallback インターフェイスを実装している場合にのみ呼び出してください。受け取りたい通知の種類を指定するには、 SetNotifyInterface メソッドを SetNotifyFlags メソッドと組み合わせて使用します。

通知インターフェイスはアプリケーションの終了時に無効になります。BITS は通知インターフェイスを永続化しません。そのため、通知を受け取りたい既存のジョブに対しては、アプリケーションの初期化処理で SetNotifyInterface メソッドを呼び出す必要があります。アプリケーションが前回実行されてから発生した状態や進行状況の情報を取得する必要がある場合は、アプリケーションの初期化時に状態と進行状況をポーリングしてください。

なお、登録したイベントが既に発生していた場合でも、BITS はコールバックを呼び出します。

コールバック通知を受け取る代わりに、エラーイベントおよび転送完了イベントに対して BITS にコマンドラインを実行させるよう登録することもできます。詳細については、 IBackgroundCopyJob2::SetNotifyCmdLine メソッドを参照してください。

なお、複数のアプリケーションが同じジョブに対して SetNotifyInterface メソッドを呼び出して通知インターフェイスを設定した場合、通知を受け取るのは最後に SetNotifyInterface メソッドを呼び出したアプリケーションのみで、他のアプリケーションは通知を受け取りません。

例

次の例は、 SetNotifyInterface メソッドの呼び出し方法を示します。この例で使用している CNotifyInterface サンプルクラスの詳細については、 IBackgroundCopyCallback インターフェイスを参照してください。この例では、 IBackgroundCopyJob インターフェイスポインターが有効であることを前提としています。

IBackgroundCopyJob* pJob;
CNotifyInterface* pNotify = new CNotifyInterface();

hr = pJob->SetNotifyInterface(pNotify);
if (SUCCEEDED(hr))
{
  hr = pJob->SetNotifyFlags(BG_NOTIFY_JOB_TRANSFERRED |
                            BG_NOTIFY_JOB_ERROR);
}
pNotify->Release();
pNofity = NULL;

if (FAILED(hr))
{
  //エラー処理 - イベント通知の登録に失敗しました。
}

IBackgroundCopyCallback インターフェイスの実装へのインターフェイスポインターを取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	通知インターフェイスポインターが正常に取得されました。
E_INVALIDARG	ppNotifyInterface インターフェイスポインターのアドレスを渡す必要があります。

一時的なエラー状態が発生した後、BITS がファイルの転送を再試行するまでに待機する最小時間を設定します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	再試行遅延が正常に設定されました。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。

最小再試行期間が経過する前にジョブを開始するには、IBackgroundCopyJob::Resume メソッドを呼び出します。

ネットワークの切断やディスクロックエラー(chkdsk の実行中など)が発生した場合、または MaxInternetBandwidth グループポリシーがゼロの場合、BITS はジョブを再試行しません。

注 システムクロックを変更しても、最小再試行遅延には影響しません。たとえば、現在時刻が午後 2 時で、BITS が午後 2 時 10 分にジョブを再試行する予定である場合、システムクロックを 10 分以上進めても BITS が早くジョブを再試行するわけではなく、10 分後に再試行します。システムクロックの変更を BITS に反映させるには、コンピューターまたは BITS サービスを再起動する必要があります。

一時的なエラー状態が発生した後、サービスがファイルの転送を再試行するまでに待機する最小時間を取得します。

このメソッドは、成功した場合は S_OK を、エラーの場合は標準的な COM の HRESULT 値のいずれかを返します。

一時的なエラー状態が発生した後、BITS がファイルの転送を試み続ける時間の長さを設定します。進行があった場合、タイマーはリセットされます。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	再試行期間が正常に設定されました。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。

再試行期間中に BITS が進行しなかった場合、ジョブの状態は BG_JOB_STATE_TRANSIENT_ERROR から BG_JOB_STATE_ERROR に移行します。エラー通知を要求している場合、BITS は JobError コールバックを呼び出します。

注 システムクロックを変更しても、再試行期間には影響しません。たとえば、再試行期間が 14 日後に満了する場合、システムクロックを 14 日以上進めても再試行期間が早く満了するわけではなく、14 日後に満了します。システムクロックの変更を BITS に反映させるには、コンピューターまたは BITS サービスを再起動する必要があります。

一時的なエラー状態が発生した後、サービスがファイルの転送を試み続ける時間の長さを取得します。進行があった場合、タイマーはリセットされます。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	タイムアウトが正常に取得されました。
E_INVALIDARG	pRetryPeriod のアドレスを渡す必要があります。

BITS がジョブの転送を試みてエラーが発生した回数を取得します。

このメソッドは、成功した場合は S_OK を、エラーの場合は標準的な COM の HRESULT 値のいずれかを返します。

このカウントがリセットされることはありません。また、ジョブが一時的なエラー状態またはエラー状態に移行した回数を正確に反映しない場合があります。たとえば、ネットワークの切断が発生した場合、チェックディスクプログラムが実行された場合、または帯域幅ポリシーによってジョブの転送が妨げられた場合、BITS はカウントを増加させません。

BITS は、ジョブが一時的なエラー状態にあるときにジョブの転送を試みて失敗するたびにもカウントを増加させます。

BITS 1.5 以前: BITS は、ジョブが一時的なエラー状態にあるときにジョブの転送を試みるたびにはカウントを増加させません。

ファイルの転送に使用するプロキシを指定します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	プロキシが正常に指定されました。
E_NOTIMPL	ProxyUsage の値が BG_JOB_PROXY_USAGE 列挙型で定義されていません。
BG_E_PROXY_LIST_TOO_LARGE	pProxyList バッファーは 32 KB を超えることはできません。
BG_E_PROXY_BYPASS_LIST_TOO_LARGE	pProxyBypassList は 32 KB を超えることはできません。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。
E_INVALIDARG	ProxyUsage が BG_JOB_PROXY_USAGE_OVERRIDE の場合、pProxyList パラメーターを NULL にすることはできません。

指定したプロキシ情報は実行時に検証されます。プロキシ情報が無効な場合、ジョブは BG_E_INVALID_PROXY_INFO エラーコードを伴って BG_JOB_STATE_ERROR 状態になります。

サービスが LocalSystem として実行される場合は、SetProxySettings メソッドを使用してそのアカウント用のプロキシまたはプロキシバイパスリストを明示的に指定し、ProxyUsage に BG_JOB_PROXY_USAGE_OVERRIDE を設定してください。BITS でのシステムアカウントの使用に関する詳細については、Service Accounts and BITS を参照してください。

BITS は、Proxycfg.exe で設定されたプロキシ設定を認識しません。

プロキシは次の形式で指定します。

"[protocol=][protocol"://"]server[":"port]"

有効なプロトコルは HTTP と HTTPS です。プロキシリストには、プロキシへのアクセスに使用するポート番号を含めることができます。たとえば、HTTP プロキシを列挙する場合、"http=http://http_proxy_name:80" という文字列が有効です。ここで http_proxy_name はプロキシサーバーの名前、80 はプロキシへのアクセスに使用するポート番号です。プロキシがそのプロトコルの既定のポート番号を使用する場合は、ポート番号を省略できます。プロキシ名だけが列挙されている場合、そのプロキシは、プロキシが指定されていないすべてのプロトコルの既定のプロキシとして使用できます。たとえば、"http=http://http_proxyother_proxy" では、HTTP の操作には http_proxy が使用され、HTTPS プロトコルには other_proxy という名前のプロキシが使用されます。

プロキシバイパスリストには、ローカルで既知のホスト名やインターネットプロトコル (IP) アドレスを列挙できます。この名前には "" などのワイルドカードを含めることができ、指定したパターンに一致するアドレス(たとえば ".microsoft.com" や ".org")に対してアプリケーションはプロキシサーバーをバイパスします。ワイルドカード文字は名前の左端に置く必要があります。たとえば "aaa." はサポートされません。<local> マクロを指定すると、すべてのローカルイントラネットサイトがバイパスされます。ローカルイントラネットサイトとは、名前にピリオドを含まないすべてのサーバーを指します。

アプリケーションがプロキシの使用方法を指定しない場合、BITS はユーザーの Internet Explorer のプロキシ設定を使用します。この既定の動作は、対話的なユーザーのコンテキストでアプリケーションがジョブを送信する場合には通常機能しますが、LocalSystem として実行されているサービスがジョブを送信する場合には機能しないことがあります。LocalSystem 用に Internet Explorer のプロキシ設定を指定することもできますが、問題が発生したときにその設定を検出するのは困難です。

ジョブがファイルの転送に使用するプロキシ情報を取得します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	プロキシ情報が正常に取得されました。
E_INVALIDARG	1 つ以上のパラメーターが NULL です。

ジョブの所有権を現在のユーザーに変更します。

このメソッドは、以下の HRESULT 値のほか、その他の値も返します。

戻り値	説明
S_OK	ジョブの所有権が正常に変更されました。
BG_E_INVALID_STATE	ジョブの状態が BG_JOB_STATE_CANCELLED または BG_JOB_STATE_ACKNOWLEDGED であってはなりません。
BG_E_NEW_OWNER_NO_FILE_ACCESS	新しい所有者には、クライアントコンピューター上の一時ファイルへの十分なアクセス権がありません。BITS は所有者のセキュリティ権限を使用して一時ファイルを作成します。
BG_E_NEW_OWNER_DIFF_MAPPING	現在の所有者のローカルファイルに対するネットワークドライブのマッピングが、以前の所有者のものと異なります。
E_ACCESSDENIED	ユーザーに管理者権限がありません。

ジョブの所有権を取得するには、ユーザーがクライアント上で管理者権限を持っている必要があります。Windows Vista では、ユーザーは昇格した状態で実行する必要があります。所有権を取得した後、そのジョブに対する以降の更新も、ユーザーが昇格した状態で実行しながら行う必要があります。詳細については、Users and Network Connections を参照してください。

管理者は、他のユーザーのジョブのプロパティを変更したり、そのジョブにファイルを追加したりするために所有権を取得する必要はありません。通常、管理者が TakeOwnership メソッドを使用するのは、ユーザーにジョブを完了するための十分な権限がない場合や、ユーザーがログオンしておらず管理者がジョブを完了させる必要がある場合です。

ジョブの所有権が変更されると、そのジョブは新しい所有者がクライアントにログオンしているときにのみ処理されます。新しい所有者の SID を取得するには、 IBackgroundCopyJob::GetOwner メソッドを呼び出します。

管理者が所有権を取得した後にジョブを キャンセルした場合、管理者がファイルへの書き込み権限を持たないために、ファイルが孤立する可能性があります。これは、ローカルファイルの保存先が以前のユーザーの移動プロファイル内にある場合に発生することがあります。

TakeOwnership メソッドは、設定されている場合、ジョブから 資格情報、証明書、カスタムヘッダー、および コマンドライン通知を削除します。

ジョブにイベント通知が指定されている場合、コールバックは IBackgroundCopyJob::SetNotifyInterface メソッドを呼び出したユーザーのコンテキストで実行されます。

#define global IID_IBackgroundCopyJob "{37668D37-507E-4160-9316-26306D150B12}"
#usecom global IBackgroundCopyJob IID_IBackgroundCopyJob "{}"
#comfunc global IBackgroundCopyJob_AddFileSet            3 int,var
#comfunc global IBackgroundCopyJob_AddFile               4 wstr,wstr
#comfunc global IBackgroundCopyJob_EnumFiles             5 sptr
#comfunc global IBackgroundCopyJob_Suspend               6
#comfunc global IBackgroundCopyJob_Resume                7
#comfunc global IBackgroundCopyJob_Cancel                8
#comfunc global IBackgroundCopyJob_Complete              9
#comfunc global IBackgroundCopyJob_GetId                 10 var
#comfunc global IBackgroundCopyJob_GetType               11 var
#comfunc global IBackgroundCopyJob_GetProgress           12 var
#comfunc global IBackgroundCopyJob_GetTimes              13 var
#comfunc global IBackgroundCopyJob_GetState              14 var
#comfunc global IBackgroundCopyJob_GetError              15 sptr
#comfunc global IBackgroundCopyJob_GetOwner              16 var
#comfunc global IBackgroundCopyJob_SetDisplayName        17 wstr
#comfunc global IBackgroundCopyJob_GetDisplayName        18 var
#comfunc global IBackgroundCopyJob_SetDescription        19 wstr
#comfunc global IBackgroundCopyJob_GetDescription        20 var
#comfunc global IBackgroundCopyJob_SetPriority           21 int
#comfunc global IBackgroundCopyJob_GetPriority           22 var
#comfunc global IBackgroundCopyJob_SetNotifyFlags        23 int
#comfunc global IBackgroundCopyJob_GetNotifyFlags        24 var
#comfunc global IBackgroundCopyJob_SetNotifyInterface    25 sptr
#comfunc global IBackgroundCopyJob_GetNotifyInterface    26 sptr
#comfunc global IBackgroundCopyJob_SetMinimumRetryDelay  27 int
#comfunc global IBackgroundCopyJob_GetMinimumRetryDelay  28 var
#comfunc global IBackgroundCopyJob_SetNoProgressTimeout  29 int
#comfunc global IBackgroundCopyJob_GetNoProgressTimeout  30 var
#comfunc global IBackgroundCopyJob_GetErrorCount         31 var
#comfunc global IBackgroundCopyJob_SetProxySettings      32 int,wstr,wstr
#comfunc global IBackgroundCopyJob_GetProxySettings      33 var,var,var
#comfunc global IBackgroundCopyJob_TakeOwnership         34
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。