RasSetEntryPropertiesA 函式（ras.h）

發行項
11/20/2024

RasSetEntryProperties 函式會變更電話簿中專案的連接資訊，或建立新的電話簿專案。

語法

DWORD RasSetEntryPropertiesA(
  [in] LPCSTR      unnamedParam1,
  [in] LPCSTR      unnamedParam2,
  [in] LPRASENTRYA unnamedParam3,
  [in] DWORD       unnamedParam4,
  [in] LPBYTE      unnamedParam5,
  [in] DWORD       unnamedParam6
);

參數

[in] unnamedParam1

Null 終止字串的指標，指定電話簿檔案的完整路徑和檔名。如果此參數 NULL，則函式會使用目前的預設電話簿檔案。默認的電話簿檔案是使用者在 [撥號網络] 對話框中 [使用者 喜好設定] 屬性表中選取的默認電話簿檔案。

[in] unnamedParam2

指定項目名稱之 Null 終止字串的指標。

如果項目名稱符合現有的專案，RasSetEntryProperties 修改該專案的屬性。

如果專案名稱不符合現有的專案，RasSetEntryProperties 會建立新的電話簿專案。針對新的專案，呼叫 RasValidateEntryName 函式，以在呼叫 rasSetEntryProperties 之前驗證項目名稱。

[in] unnamedParam3

RASENTRY 結構的指標，指定要與 lpszEntry 參數所指示之電話簿專案相關聯的新聯機數據。

呼叫端必須提供下列成員的值，RASENTRY 結構中。

dwSize
szLocalPhoneNumber
szDeviceName
szDeviceType
dwFramingProtocol
dwfOptions
dwType

Windows XP 或更新版本：支援 dwType。

如果未為這些成員提供值，RasSetEntryProperties 失敗，ERROR_INVALID_PARAMETER。

結構後面可能會接著以 Null 終止的替代電話號碼字串數位。最後一個字串會以兩個連續的 Null 字元終止。 dwAlternateOffsetRASENTRY 結構的成員包含第一個字串的位移。

[in] unnamedParam4

指定 lpRasEntry 參數所識別之緩衝區的大小，以位元組為單位。

[in] unnamedParam5

指定裝置特定組態信息的緩衝區指標。這是不透明的 TAPI 裝置組態資訊。如需 TAPI 裝置設定的詳細資訊，請參閱 Platform SDK 中 Telephony Application Programming Interfaces （TAPI）中的 lineGetDevConfig 函式。

Windows XP：這個參數未使用。呼叫函式應將此參數設定為 NULL。

[in] unnamedParam6

指定 lpbDeviceInfo 緩衝區的大小，以位元組為單位。

Windows XP：這個參數未使用。呼叫函式應該將此參數設定為零。

傳回值

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

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

價值	意義
ERROR_ACCESS_DENIED	用戶沒有正確的許可權。只有系統管理員才能完成這項工作。
ERROR_BUFFER_INVALID	lpRasEntry 所指定的位址或緩衝區無效。
ERROR_CANNOT_OPEN_PHONEBOOK	電話簿已損毀或遺失元件。
ERROR_INVALID_PARAMETER	RASENTRY 結構所指向的 lpRasEntry 參數未包含足夠的資訊，或指定的專案不存在於電話簿中。請參閱 lpRasEntry 的描述，以查看需要哪些資訊。

言論

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

Microsoft\Network\Connections\Pbk

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

注意指定 lpszPhonebook 參數的非NULL 值，在 Windows XP 版本之後可能無法支援。

注意

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

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	ras.h
連結庫	Rasapi32.lib
DLL	Rasapi32.dll