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

  • [アーティクル]

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

構文

HRESULT SetCredentials(
  [in] BG_AUTH_CREDENTIALS *credentials
);

パラメーター

[in] credentials

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

戻り値

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

リターン コード 説明
S_OK
 Success
BG_E_INVALID_AUTH_TARGET
 認識できないターゲット列挙値。
BG_E_INVALID_AUTH_SCHEME
 認識できないスキーム列挙値。
BG_E_USERNAME_TOO_LARGE
 ユーザー名が長すぎます。 制限については、 BG_BASIC_CREDENTIALS 構造を参照してください。
BG_E_PASSWORD_TOO_LARGE
 パスワードが長すぎます。 制限については、 BG_BASIC_CREDENTIALS 構造を参照してください。
E_INVALIDARG
 Basic または Digest スキームを指定した場合、 BG_BASIC_CREDENTIALS 構造体の UserName メンバーと Password メンバーを NULL にすることはできません。

解説

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 はサーバー認証に暗黙的な資格情報も使用します。

メモ BITS は、SMB パスを指定する リモート名 の資格情報を無視します。
 
メモ BITS では、サーバーの認証やチャネルの暗号化は行われません。 これがアプリケーションの問題である場合は、HTTPS を使用します。
 

例

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

要件

   
サポートされている最小のクライアント Windows Vista
サポートされている最小のサーバー Windows Server 2003
対象プラットフォーム Windows
ヘッダー bits1_5.h (Bits.h を含む)
Library Bits.lib
[DLL] BitsPrx2.dll
再頒布可能パッケージ Windows XP の BITS 1.5

関連項目

認証

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2::RemoveCredentials