rasDialA 函式 (ras.h)

發行項
08/25/2023

RasDial函式會在 RAS 用戶端與 RAS 伺服器之間建立 RAS 連線。連線資料包含回呼和使用者驗證資訊。

語法

DWORD RasDialA(
  [in]  LPRASDIALEXTENSIONS unnamedParam1,
  [in]  LPCSTR              unnamedParam2,
  [in]  LPRASDIALPARAMSA    unnamedParam3,
  [in]  DWORD               unnamedParam4,
  [in]  LPVOID              unnamedParam5,
  [out] LPHRASCONN          unnamedParam6
);

參數

[in] unnamedParam1

RASDIALEXTENSIONS結構的指標，指定要啟用的一組 RasDial擴充功能。如果不需要啟用這些功能，請將此參數設定為 Null 。

[in] unnamedParam2

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

[in] unnamedParam3

RASDIALPARAMS結構的指標，指定 RAS 連線的呼叫參數。使用 RasGetEntryDialParams 函式擷取特定電話簿專案的這個結構複本。

呼叫端必須將 RASDIALPARAMS 結構的 dwSize 成員設定為 sizeof (RASDIALPARAMS) ，以識別所傳遞的結構版本。

如果RASDIALPARAMS結構的szPhoneNumber成員是空字串，RasDial會使用儲存在電話簿專案中的電話號碼。

[in] unnamedParam4

指定 lpvNotifier 參數的本質。如果 lpvNotifier 為 Null， 則會忽略 dwNotifierType 。如果 lpvNotifier 不是 Null，請將 dwNotifierType 設定為下列其中一個值。

值	意義
0	lpvNotifier參數會指向RasDialFunc 回呼函式。
1	lpvNotifier參數會指向RasDialFunc1 回呼函式。
2	lpvNotifier參數會指向RasDialFunc2 回呼函式。

[in] unnamedParam5

指定視窗控制碼或 RasDialFunc、 RasDialFunc1或 RasDialFunc2 回呼函式，以接收 RasDial 事件通知。 dwNotifierType參數會指定lpvNotifier的本質。如需進一步的詳細資料，請參閱其先前的描述。

如果此參數不是 Null， RasDial 會針對每個 RasDial 事件傳送訊息或呼叫回呼函式。此外， RasDial 呼叫會以非同步方式運作： RasDial 會在建立連接之前立即傳回，並透過視窗或回呼函式傳達其進度。

如果 lpvNotifier 為 Null， RasDial 呼叫會同步運作：在連線嘗試順利或失敗之前， RasDial 不會傳回。

如果 lpvNotifier 不是 Null，則對視窗或回呼函式的通知可以隨時在 初始呼叫 RasDial之後發生。發生下列其中一個事件時，通知會結束：

已建立連線。換句話說，RAS 線上狀態RASCS_Connected。
連線失敗。換句話說， dwError 為非零。
RasHangUp 會在連線上呼叫。

回呼通知是在初始呼叫 RasDial期間所擷取的執行緒內容中進行。

[out] unnamedParam6

HRASCONN類型的變數指標。在呼叫RasDial之前，將HRASCONN變數設定為Null。如果 RasDial 成功，它會將 RAS 連線的控制碼儲存至 *lphRasConn。

傳回值

如果函式成功，傳回值 會ERROR_SUCCESS ，而 RAS 連線的控制碼則會在 lphRasConn所指向的變數中傳回。

如果函式失敗，則傳回值來自路由和遠端存取錯誤碼或 Winerror.h。

備註

RasGetConnectStatus可以偵測到立即傳回之後發生的錯誤。資料可供使用，直到應用程式呼叫 RasHangUp 以停止連線為止。

每當非Null連線控制碼儲存到 *lphRasConn時，應用程式最終必須呼叫RasHangUp。即使 RasDial 傳回非零 (錯誤) 值，也是如此。

應用程式可以從RasDial通知函式安全地呼叫RasHangUp。不過，如果這樣做，直到常式傳回之後，才會發生停止回應。

如果 lpRasDialExtensions 所指向的結構啟用 RDEOPT_PausedStates， 則每當 RasDial 函式進入 RASCS_PAUSED 位設定為 1 的狀態時，就會暫停。若要從這類暫停狀態重新開機RasDial，請再次呼叫RasDial，並傳遞從*lphRasConn中原始RasDial呼叫傳回的連接控制碼。從暫停狀態重新開機時，必須使用原始 RasDial 呼叫中使用的相同通知。

lpvNotifier參數是視窗的控制碼，可接收進度通知訊息。在進行中通知訊息中，wParam相當於RasDialFunc和RasDialFunc1的rasconnstate參數，而lParam相當於RasDialFunc和RasDialFunc1的dwError參數。

進度通知訊息會使用系統註冊的訊息碼。您可以取得此訊息程式碼的值，如下所示：

UINT unMsg = RegisterWindowMessageA( RASDIALEVENT );
if (unMsg == 0)
    unMsg = WM_RASDIALEVENT;

RAS 支援參考的連線。如果撥號的專案已經連接， RasDial 會傳回 SUCCESS ，並參考連接。若要中斷連線連線，連線上的每個 RasDial 都應該與 RasHangUp相符。

由於某些電話簿專案需要可延伸驗證通訊協定 (EAP) 進行驗證，因此呼叫端應該在呼叫RasDial之前呼叫RasGetEapUserIdentity。如果 RasGetEapUserIdentity 傳回 ERROR_INVALID_FUNCTION_FOR_ENTRY，則電話簿專案不需要 EAP。不過，如果RasGetEapUserIdentity傳回NO_ERROR，則呼叫端應該將 EAP 身分識別資訊從RasGetEapUserIdentity複製到RASDIALEXTENSIONS的RasEapInfo成員，以及RASDIALPARAMS的szUserName成員。如需詳細資訊，請參閱 RasGetEapUserIdentity 。如果電話簿專案需要 EAP，則專案的RASENTRY結構的dwfOptions成員包含RASEO_RequireEAP旗標。

若要指定RasDial應該進入RASCS_CallbackSetByCaller狀態，請在初始呼叫RasDial時將lpRasDialParams-szCallbackNumber> 設定為「*」。使用此狀態呼叫通知處理常式時，請將回呼號碼設定為使用者所提供的數位。

注意

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

需求


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