RasSetEntryPropertiesA 函式 (ras.h)

發行項
03/05/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 終止字串的指標，指定電話簿 (PBK) 檔案的完整路徑和檔名。如果此參數為 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 字元終止。 RASENTRY 結構的 dwAlternateOffset 成員包含第一個字串的位移。

[in] unnamedParam4

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

[in] unnamedParam5

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

Windowsxp： 此參數未使用。呼叫函式應該將此參數設定為 NULL。

[in] unnamedParam6

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

Windowsxp： 此參數未使用。呼叫函式應該將此參數設定為零。

傳回值

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

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

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

備註

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

Microsoft\Network\Connections\Pbk

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

注意lpszPhonebook 參數的非 NULL 值，在 Windows XP 之後的 Windows 版本中可能不支援。

注意

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

規格需求

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