IBackgroundCopyJob2：：SetCredentials 方法（bits1_5.h）

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

Syntax

HRESULT SetCredentials(
  [in] BG_AUTH_CREDENTIALS *credentials
);

参数

[in] credentials

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

返回值

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

注解

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 还将使用隐式凭据进行身份验证，除非指定显式服务器凭据。

例子

以下示例演示如何调用 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));
}

要求

另请参阅

身份验证

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2：：RemoveCredentials