IBackgroundCopyJob2：：SetCredentials 方法 (bits1_5.h)

  • 發行項

指定要用於 Proxy 或遠端伺服器使用者驗證要求的認證。

語法

HRESULT SetCredentials(
  [in] BG_AUTH_CREDENTIALS *credentials
);

參數

[in] credentials

識別目標 (Proxy 或伺服器) 、驗證配置，以及要用於使用者驗證的使用者認證。 如需詳細資訊，請參閱 BG_AUTH_CREDENTIALS 結構。

傳回值

這個方法會傳回下列傳回值，以及其他傳回值。

傳回碼 Description
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
 如果您指定基本或摘要配置， BG_BASIC_CREDENTIALS 結構的 UserName 和 Password 成員不能是 Null 。

備註

BITS 會提供 Proxy 或伺服器的認證，以回應使用者驗證的要求。 在初始呼叫 [ 繼續] 之前設定認證。

您必須針對您想要提供的每個目標和配置組呼叫這個方法。 例如，如果您想要同時指定基本和摘要式驗證的 Proxy 認證，您會呼叫此方法一次來指定基本認證，第二次指定摘要認證。

如果作業目前包含具有相同目標和配置組的認證，現有的認證會取代為新的認證。 認證會在作業的存留期間保存。 若要從作業中移除認證，請呼叫 IBackgroundCopyJob2：：RemoveCredentials 方法。

如果您知道 Proxy 或伺服器將要求的配置，您只能提供這些認證。 否則，請提供所有配置的認證。

如果您未提供 Proxy 或伺服器所要求的認證，則作業會進入 BG_JOB_STATE_ERROR 狀態，或者 Proxy 或伺服器無法驗證認證。 檢查錯誤碼，以判斷驗證在伺服器 (BG_E_HTTP_ERROR_401) 或 Proxy (BG_E_HTTP_ERROR_407) 是否失敗。 若要擷取錯誤碼，請呼叫 IBackgroundCopyJob：：GetError 方法來擷取 IBackgroundCopyError 介面指標。 然後，呼叫 IBackgroundCopyError：：GetError 方法來擷取錯誤碼。 在您判斷驗證失敗的位置 (Proxy 或伺服器) 之後，請指定要用於 Proxy 或伺服器的新認證，並呼叫 IBackgroundCopyJob：：Resume 方法來繼續作業。 因為您無法判斷哪個配置失敗，請在呼叫 Resume 方法之前，先指定所有配置的認證。

沒有方法可以擷取您已設定的認證。

您必須在作業擁有者的內容中呼叫這個方法。

呼叫 IBackgroundCopyJob：：TakeOwnership 方法會從作業中移除認證。

若要指定隱含認證 (登入使用者的認證) ，請將配置設定為 NTLM，並將使用者名稱和密碼設定為 Null。 如果您指定 Proxy 的隱含認證，除非指定明確的伺服器認證，否則 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)
程式庫 Bits.lib
Dll BitsPrx2.dll
可轉散發套件 Windows XP 上的 BITS 1.5

另請參閱

驗證

BG_AUTH_CREDENTIALS

IBackgroundCopyJob2：：RemoveCredentials