IBackgroundCopyJob2：：SetCredentials 方法 (bits1_5.h)

  • 项目

指定要用于代理或远程服务器用户身份验证请求的凭据。

语法

HRESULT SetCredentials(
  [in] BG_AUTH_CREDENTIALS *credentials
);

参数

[in] credentials

标识目标 (代理或服务器) 、身份验证方案以及用于用户身份验证的用户凭据。 有关详细信息，请参阅 BG_AUTH_CREDENTIALS 结构。

返回值

此方法返回以下返回值以及其他返回值。

返回代码 说明
S_OK
 成功
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
 如果指定“基本”或“摘要”方案， 则 BG_BASIC_CREDENTIALS 结构的 UserName 和 Password 成员不能为 NULL 。

注解

BITS 向代理服务器或服务器提供凭据，以响应用户身份验证请求。 在初始调用 Resume 之前设置凭据。

必须为每个要提供的目标和方案对调用此方法。 例如，如果要为基本身份验证和摘要式身份验证指定代理凭据，可以调用此方法一次以指定基本凭据，并再次调用一次以指定摘要凭据。

如果作业当前包含具有相同目标和方案对的凭据，现有凭据将替换为新凭据。 凭据在作业的生命周期内会保留。 若要从作业中删除凭据，请调用 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