IBackgroundCopyJob2

アップロード応答ジョブから応答データを取得し、クライアントへの応答データ転送の進行状況を確認し、コマンドラインの実行を要求し、プロキシおよびリモートサーバーの認証要求に対する資格情報を提供します。

ジョブが BG_JOB_STATE_ERROR または BG_JOB_STATE_TRANSFERRED 状態になったときに実行するプログラムを指定します。BITS は、このメソッドを呼び出したユーザーのコンテキストでプログラムを実行します。

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

BITS は、プログラムを起動するために CreateProcessAsUser 関数を呼び出します。

プログラムは終了コード 0 を返すようにしてください。プログラムが終了コード 0 を返さない場合、BITS はジョブの状態を確認します。プログラムがジョブをキャンセルも完了もしなかった場合、BITS はそのジョブに指定された 最小再試行遅延 が経過した後にプログラムを再度呼び出します。

BITS 1.5 以前: BITS はプログラムを 1 回だけ呼び出します。

スクリプトを実行するには、pProgram に WScript.exe を指定します (WScript.exe のフルパスを含めます)。pParameters パラメーターには、WScript.exe、スクリプト名、および任意の引数を含める必要があります。

プログラムがジョブ関連の情報を必要とする場合は、その情報を引数として渡す必要があります。%system32% などの環境変数は展開されないため、pProgram や pParameters に含めないでください。

プログラムへのフルパスを含める必要があります。pParameters の引数のいずれか (モジュール名など) に長いファイル名を使用するパスが含まれる場合は、そのパスを引用符で囲んでください。

実行するプログラムが応答ファイルまたはダウンロードファイルを使用する場合、そのプログラムは IBackgroundCopyJob::Complete メソッドを呼び出して、ファイルをクライアントから利用できるようにする必要があります。

プログラムを実行するタイミングを指定するには、 IBackgroundCopyJob::SetNotifyFlags メソッドを呼び出します。コマンドラインの実行を要求できるのはジョブのエラーイベントまたは転送完了イベントに対してのみで、ジョブ変更イベントに対しては要求できません。イベントの発生後に SetNotifyCmdLine メソッドを呼び出した場合でも、BITS はコマンドラインを実行することに注意してください。

BITS ジョブがサービスアカウントのコンテキスト (networkservice/localsystem/localservice) にある場合、いかなる形式のコマンドラインコールバックも実行されません。

SetNotifyCmdLine メソッドと IBackgroundCopyJob::SetNotifyInterface メソッドの両方を呼び出した場合、BITS は通知インターフェイスが無効になったとき、または BITS が呼び出した通知メソッドが失敗コードを返した場合にのみコマンドラインを実行します。たとえば、BITS が呼び出した通知メソッドが E_FAIL を返した場合、BITS はコマンドラインを実行します。ただし、通知メソッドが S_OK を返した場合、BITS はコマンドラインを実行しません。通知メソッドとコマンドラインの実行要求の両方が失敗した場合、BITS は最小再試行期間の経過後に再度通知を送信します。

IBackgroundCopyJob::TakeOwnership メソッドを呼び出すと、ジョブからコマンドライン通知が削除されることに注意してください。

例

SetNotifyCmdLine メソッドを呼び出す例については、 Registering to Execute a Program を参照してください。

ジョブがエラー状態または転送完了状態になったときに実行するプログラムを取得します。

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

IBackgroundCopyJob2::SetNotifyCmdLine メソッドが呼び出されていない場合、 GetNotifyCmdLine メソッドは pProgram と pParameters を空の文字列 (L"") に設定します。

アップロード応答ジョブからの応答データの転送に関する進行状況情報を取得します。

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

サーバーアプリケーションからの応答データのメモリ内コピーを取得します。このメソッドは、ジョブの種類が BG_JOB_TYPE_UPLOAD_REPLY で、状態が BG_JOB_STATE_TRANSFERRED である場合にのみ呼び出してください。

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

GetReplyData メソッドを使用すると、 IBackgroundCopyJob::Complete メソッドの呼び出しの前後どちらでも応答データを読み取ることができます。ただし、応答ファイルから応答データを読み取るには、先に Complete メソッドを呼び出す必要があります。Complete メソッドを呼び出すまで、ファイルはクライアントから利用できません。

応答データが 1 MB を超える場合、 GetReplyData メソッドは BG_E_TOO_LARGE を返します (pSize には応答データのサイズが格納されます)。1 MB を超える応答を取得するには、 IBackgroundCopyJob2::GetReplyFileName メソッドを呼び出してファイル名を取得します。その後、そのファイルを開いて応答データを直接読み取ります。

例

GetReplyData メソッドを使用する例については、 Retrieving the Reply From an Upload-Reply Job を参照してください。

サーバーアプリケーションからの応答データを格納するファイルの名前を指定します。このメソッドは、ジョブの種類が BG_JOB_TYPE_UPLOAD_REPLY である場合にのみ呼び出してください。

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

最初に IBackgroundCopyJob::Resume メソッドを呼び出す前に SetReplyFileName メソッドを呼び出さなかった場合、BITS がファイル名を生成します。

BITS がファイル名を生成する場合、応答ファイルはローカルのアップロードファイルと同じディレクトリに書き込まれます。

SetReplyFileName メソッドは、BITS がサーバーアプリケーションから応答のダウンロードを開始するまでの間であればいつでも呼び出せます。ダウンロードが開始されている場合、このメソッドは失敗します。

応答ファイルは、 IBackgroundCopyJob::Complete メソッドを呼び出した後にクライアントから利用できるようになります。Complete メソッドを呼び出す前に応答データを取得するには、 IBackgroundCopyJob2::GetReplyData メソッドを呼び出します。

サーバーアプリケーションが応答を返さなかった場合、ファイルは空になります。

サーバーアプリケーションからの応答データを格納しているファイルの名前を取得します。このメソッドは、ジョブの種類が BG_JOB_TYPE_UPLOAD_REPLY である場合にのみ呼び出してください。

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

応答ファイル名を指定するには、 IBackgroundCopyJob2::SetReplyFileName メソッドを呼び出します。名前を指定しなかった場合、 GetReplyFileName メソッドは BITS が生成した名前を返します。名前を指定せず、かつジョブにファイルを追加する前にこのメソッドを呼び出した場合、pReplyFileName は NULL に設定されます。

応答ファイルを開いて読み取る前に、 IBackgroundCopyJob::Complete メソッドを呼び出す必要があります。Complete メソッドを呼び出すまで、応答ファイルはクライアントから利用できません。

サーバーアプリケーションが応答を返さなかった場合、ファイルは空になります。

例

GetReplyFileName メソッドを使用する例については、 Retrieving the Reply From an Upload-Reply Job を参照してください。

プロキシまたはリモートサーバーのユーザー認証要求に使用する資格情報を指定します。

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

BITS は、ユーザー認証の要求に応じてプロキシまたはサーバーに資格情報を提供します。資格情報は、最初に Resume を呼び出す前に設定してください。

提供したいターゲットとスキームの組み合わせごとに、このメソッドを呼び出す必要があります。たとえば、Basic 認証と Digest 認証の両方にプロキシの資格情報を指定したい場合、Basic の資格情報を指定するために 1 回、Digest の資格情報を指定するためにもう 1 回、このメソッドを呼び出します。

ジョブに同じターゲットとスキームの組み合わせの資格情報が既に含まれている場合、既存の資格情報は新しい資格情報で置き換えられます。資格情報はジョブの有効期間中保持されます。ジョブから資格情報を削除するには、 IBackgroundCopyJob2::RemoveCredentials メソッドを呼び出します。

プロキシまたはサーバーが要求するスキームが分かっている場合は、そのスキームの資格情報だけを提供できます。それ以外の場合は、すべてのスキームに対する資格情報を提供してください。

プロキシまたはサーバーが要求する資格情報を提供しなかった場合、あるいはプロキシまたはサーバーが資格情報を認証できなかった場合、ジョブは BG_JOB_STATE_ERROR 状態になります。認証がサーバーで失敗したのか (BG_E_HTTP_ERROR_401)、プロキシで失敗したのか (BG_E_HTTP_ERROR_407) は、エラーコードを確認して判断します。エラーコードを取得するには、 IBackgroundCopyJob::GetError メソッドを呼び出して IBackgroundCopyError インターフェイスポインターを取得します。その後、 IBackgroundCopyError::GetError メソッドを呼び出してエラーコードを取得します。認証がどこで失敗したか (プロキシかサーバーか) を特定したら、プロキシまたはサーバーに使用する新しい資格情報を指定し、 IBackgroundCopyJob::Resume メソッドを呼び出してジョブを再開します。どのスキームが失敗したかは判別できないため、 Resume メソッドを呼び出す前にすべてのスキームの資格情報を指定してください。

設定した資格情報を取得するメソッドはありません。

このメソッドは、ジョブの所有者のコンテキストで呼び出す必要があります。

IBackgroundCopyJob::TakeOwnership メソッドを呼び出すと、ジョブから資格情報が削除されます。

暗黙的な資格情報 (ログオン中のユーザーの資格情報) を指定するには、スキームを NTLM に設定し、ユーザー名とパスワードを NULL に設定します。プロキシに対して暗黙的な資格情報を指定した場合、明示的なサーバー資格情報を指定しない限り、BITS はサーバー認証にも暗黙的な資格情報を使用します。

例

次の例は、サーバーのユーザー認証要求に対して Basic の資格情報を指定するために SetCredentials メソッドを呼び出す方法を示しています。この例では、 CredUIPromptForCredentials 関数を使用してユーザー名とパスワードを取得しています。この例では、有効な IBackgroundCopyJob インターフェイスポインター pJob があることを前提としています。また、機密情報に関連付けられたメモリ領域をクリアするために SecureZeroMemory 関数を使用しています。SecureZeroMemory 関数は WinBase.h で定義されています。

#define MAX_STR_LENGTH 300+1    // BITS limit for user name and password

CREDUI_INFO cuiinfo;
WCHAR szUserName[MAX_STR_LENGTH];  
WCHAR szPassword[MAX_STR_LENGTH];
DWORD rc;
IBackgroundCopyJob* pJob;
IBackgroundCopyJob2* pJob2 = NULL;
BG_AUTH_CREDENTIALS ac;

cuiinfo.cbSize = sizeof(CREDUI_INFO);
cuiinfo.hbmBanner = NULL;
cuiinfo.hwndParent = NULL; //Desktop is parent
cuiinfo.pszCaptionText = L"Server Authentication";
cuiinfo.pszMessageText = L"Enter user credentials for Basic authentication.";

//Initialize the UserName and Password fields. This example sets  
//UserName to blank, but you could also set UserName to the owner 
//of the job or the current user. For an example that retrieves the owner's
//name, see the example code for the IBackgroundCopyJob::GetOwner method. 
szUserName[0] = L'\0';
szPassword[0] = L'\0';
rc = CredUIPromptForCredentials(&cuiinfo, NULL, NULL, 0,
    szUserName, MAX_STR_LENGTH,
    szPassword, MAX_STR_LENGTH, 
    NULL, CREDUI_FLAGS_DO_NOT_PERSIST | CREDUI_FLAGS_GENERIC_CREDENTIALS);

if (NO_ERROR == rc)
{
    pJob->QueryInterface(__uuidof(IBackgroundCopyJob2), (void**)&pJob2);
    ac.Target = BG_AUTH_TARGET_SERVER;
    ac.Scheme = BG_AUTH_SCHEME_BASIC;
    ac.Credentials.Basic.UserName = szUserName;
    ac.Credentials.Basic.Password = szPassword;
    hr = pJob2->SetCredentials(&ac);
    if (FAILED(hr))
    {
      //Handle error
    }
    SecureZeroMemory(szUserName, sizeof(szUserName));
    SecureZeroMemory(szPassword, sizeof(szPassword));
}

資格情報を使用対象から削除します。指定する資格情報は、IBackgroundCopyJob2::SetCredentials メソッドで設定した既存のターゲットとスキームの組み合わせに一致している必要があります。設定した資格情報を取得するメソッドはありません。

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