AcquireCredentialsHandleA 函式 (sspi.h)
AcquireCredentialsHandle (CredSSP) 函式會取得安全性主體預先存在的認證控制碼。 InitializeSecurityCoNtext (CredSSP) 和AcceptSecurityCoNtext (CredSSP) 函式都需要此控制碼。 這些可以是預先存在的 認證，這些認證是透過此處未描述的系統登入所建立，或者呼叫端可以提供替代認證。
語法
SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleA(
[in, optional] LPSTR pszPrincipal,
[in] LPSTR pszPackage,
[in] unsigned long fCredentialUse,
[in, optional] void *pvLogonId,
[in, optional] void *pAuthData,
[in, optional] SEC_GET_KEY_FN pGetKeyFn,
[in, optional] void *pvGetKeyArgument,
[out] PCredHandle phCredential,
[out, optional] PTimeStamp ptsExpiry
);
參數
[in, optional] pszPrincipal
Null 終止字串的指標，指定控制碼將參考其認證之主體的名稱。
[in] pszPackage
Null 終止字串的指標，指定將使用這些認證 的安全性套件 名稱。 這是EnumerateSecurityPackages函式所傳回之 SecPkgInfo結構之Name成員中傳回的安全性套件名稱。 建立內容之後，可以使用ulAttribute設定為SECPKG_ATTR_PACKAGE_INFO呼叫QueryCoNtextAttributes (CredSSP) ，以傳回使用中安全性套件的相關資訊。
[in] fCredentialUse
旗標，指出如何使用這些認證。 此參數可以是下列其中一個值。
| 值 | 意義 |
|---|---|
|
驗證傳入的伺服器認證。 當呼叫 InitializeSecurityCoNtext (CredSSP) 或 AcceptSecurityCoNtext (CredSSP) 時，可能會使用驗證授權單位來驗證輸入認證。 如果無法使用這類授權單位，函式將會失敗並傳回 SEC_E_NO_AUTHENTICATING_AUTHORITY。 驗證是套件特定的。 |
|
允許本機用戶端認證準備傳出權杖。 |
[in, optional] pvLogonId
識別使用者的本機 唯一識別碼 指標 (LUID) 。 這個參數會提供給檔案系統進程，例如網路重新導向器。 此參數可以是 Null。
[in, optional] pAuthData
CREDSSP_CRED結構的指標，指定 Schannel 和 Negotiate 套件的驗證資料。
[in, optional] pGetKeyFn
保留的。 不使用此參數，而且應該設定為 Null。
[in, optional] pvGetKeyArgument
保留的。 此參數必須設定為 Null。
[out] phCredential
將接收認證控制碼之 CredHandle 結構的指標。
[out, optional] ptsExpiry
TimeStamp結構的指標，可接收傳回認證到期的時間。 收到的結構值取決於安全性套件，必須指定當地時間中的值。
傳回值
如果函式成功，則會傳回 SEC_E_OK。
如果函式失敗，它會傳回下列其中一個錯誤碼。
| 傳回碼 | Description |
|---|---|
|
記憶體不足，無法完成要求的動作。 |
|
未對應至 SSPI 錯誤碼的錯誤。 |
|
安全性套件中沒有可用的認證。 |
|
函式的呼叫端沒有必要的認證。 |
|
要求的安全性套件不存在。 |
|
無法辨識提供給封裝的認證。 |
備註
AcquireCredentialsHandle (CredSSP) 函式會傳回主體的認證控制碼，例如使用者或用戶端，如特定安全性套件所使用的。 函式可以將控制碼傳回至預先存在的認證或新建立的認證，並傳回它。 此控制碼可用於對 AcceptSecurityCoNtext (CredSSP) 和 InitializeSecurityCoNtext (CredSSP) 函式的後續呼叫。
一般而言， AcquireCredentialsHandle (CredSSP) 不提供其他使用者登入相同電腦的認證。 不過，具有SE_TCB_NAME許可權的呼叫端可以藉由指定該會話的登入識別碼 (LUID) ，來取得現有登入會話的認證。 一般而言，這是由必須代表登入使用者的核心模式模組使用。
套件可能會在 RPC 執行時間傳輸所提供的 pGetKeyFn 中呼叫 函式。 如果傳輸不支援擷取認證的回呼概念，此參數必須是 Null。
對於核心模式呼叫端，必須注意下列差異：
- 這兩個字串參數必須是 Unicode 字串。
- 緩衝區值必須配置在進程虛擬記憶體中，而不是從集區配置。
注意
sspi.h 標頭會根據 UNICODE 預處理器常數的定義，將 AcquireCredentialsHandle 定義為別名，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 最低支援的用戶端 | Windows Vista [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2008 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | sspi.h (包含 Security.h) |
| 程式庫 | Secur32.lib |
| Dll | Secur32.dll |
另請參閱
AcceptSecurityCoNtext (CredSSP)