IBackgroundCopyJob2::SetCredentials メソッド (bits1_5.h)

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

構文

HRESULT SetCredentials(
  [in] BG_AUTH_CREDENTIALS *credentials
);

パラメーター

[in] credentials

ターゲット (プロキシまたはサーバー)、認証スキーム、およびユーザー認証に使用するユーザーの資格情報を識別します。 詳細については、 BG_AUTH_CREDENTIALS 構造を参照してください。

戻り値

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

注釈

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

指定するターゲットとスキームのペアごとに、このメソッドを呼び出す必要があります。 たとえば、基本認証とダイジェスト認証の両方にプロキシ資格情報を指定する場合は、このメソッドを 1 回呼び出して基本資格情報を指定し、もう 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 はサーバー認証にも暗黙的な資格情報を使用します。

例示

次の例は、 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));
}

Requirements

こちらも参照ください

認証

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2::RemoveCredentials