RasSetCredentialsA 函式 (ras.h)

發行項
08/25/2023

RasSetCredentials函式會設定與指定 RAS 電話簿專案相關聯的使用者認證。

語法

DWORD RasSetCredentialsA(
  [in] LPCSTR            unnamedParam1,
  [in] LPCSTR            unnamedParam2,
  [in] LPRASCREDENTIALSA unnamedParam3,
  [in] BOOL              unnamedParam4
);

參數

[in] unnamedParam1

Null 終止字串的指標，指定電話簿 (PBK) 檔案的完整路徑和檔案名。如果此參數為 Null，函式會使用目前的預設電話簿檔案。預設電話簿檔案是由使用者選取的[撥號網路] 對話方塊之 [使用者喜好設定] 屬性工作表中的使用者所選取的檔案。

[in] unnamedParam2

指定電話簿專案名稱之 Null 終止字串的指標。

[in] unnamedParam3

RASCREDENTIALS結構的指標，指定要為指定的電話簿專案設定的使用者認證。在呼叫 RasSetCredentials之前，請將結構的 dwSize 成員設定為 sizeof(RASCREDENTIALS) ，並將 dwMask 成員設定為，以指出要設定的認證資訊。

[in] unnamedParam4

值，指定 RasSetCredentials 是否藉由將其設定為空字串「」來清除現有的認證。如果此旗標為TRUE，RASCREDENTIALS結構的dwMask成員會指出函式設定為空字串的認證。如果此旗標為 FALSE，函式會根據其對應 RASCREDENTIALS 成員的內容來設定指定的認證。

傳回值

如果函式成功，傳回值會 ERROR_SUCCESS。

如果函式失敗，傳回值就是下列其中一個錯誤碼，或是來自路由和遠端存取錯誤碼或 WinError.h 的值。

值	意義
ERROR_CANNOT_OPEN_PHONEBOOK	找不到指定的電話簿。
ERROR_INVALID_PARAMETER	lpCredentials參數為Null，或指定的專案不存在於電話簿中。
ERROR_ACCESS_DENIED	發生下列其中一個情況：呼叫端應用程式嘗試為每個使用者連線設定預設認證。預設認證只能針對所有使用者連線進行設定。若是所有使用者 connectoid，使用者沒有正確許可權可設定所有使用者的預先共用金鑰或認證。只有系統管理員可以完成這些工作。

備註

RasSetCredentials函式會設定與指定 RAS 電話簿專案相關聯的使用者認證。使用電話簿專案儲存的認證是最後一位使用者使用指定的電話簿專案成功連線的認證，或是後續在呼叫 RasSetCredentials 或 RasSetEntryDialParams 函式中為電話簿專案指定的認證。

RasSetCredentials 函式是使用電話簿專案安全地儲存認證的慣用方式。 RasSetCredentials 取代 RasSetEntryDialParams 函式，未來 Windows 作業系統版本可能不支援此功能。

密碼控制碼為「*\\\*\\」 (16 個星號) 。如果您呼叫 RasGetCredentials 並在密碼欄位中收到 16 *s，您有預存的密碼，而且基於安全性考慮，系統不會以純文字形式將它傳回給您。如果RASCREDENTIALS結構的szPassword成員包含RasGetCredentials或RasGetEntryDialParams所傳回的密碼控制碼 (16 *s) ，則下一次呼叫RasSetCredentials將不會變更儲存的密碼。

若要設定所有使用者連線的預設認證，請在lpCredentials參數所指向之 RASCREDENTIALS結構的dwMask成員中設定RASCM_DefaultCreds旗標。如果您嘗試為每個使用者連線設定預設認證， RasSetCredentials 會 傳回ERROR_ACCESS_DENIED。

設定所有使用者連線的認證時，如果通話應用程式為 phone-book 參數 lpszPhonebook指定非 Null 值，則電話簿檔案必須位於所有使用者應用程式資料路徑下方的電話簿目錄中。若要取得電話簿檔案的正確位置，請先呼叫CSIDL值為CSIDL_COMMON_APPDATA的 SHGetFolderPath。 SHGetFolderPath 會傳回所有使用者應用程式資料路徑。將下列字串附加至此路徑：

Microsoft\Network\Connections\Pbk

合併路徑是電話簿檔案的正確位置。

注意在更新版本的 Windows 作業系統中，可能不支援為 lpszPhonebook 參數指定非 Null 值。

若要設定預先共用金鑰，請使用RASCREDENTIALS中的RASCM_PreSharedKey旗標。dwMask欄位。

注意

ras.h 標頭會將 RasSetCredentials 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

需求


最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	ras.h
程式庫	Rasapi32.lib
Dll	Rasapi32.dll