RasEnumConnectionsA 函式 (ras.h)
RasEnumConnections 函式會列出所有作用中的 RAS 連線。 它會傳回每個連線的句柄和電話簿項目名稱。
語法
DWORD RasEnumConnectionsA(
[in, out] LPRASCONNA unnamedParam1,
[in, out] LPDWORD unnamedParam2,
[out] LPDWORD unnamedParam3
);
參數
[in, out] unnamedParam1
在輸出上接收 RASCONN 結構的緩衝區指標,每個 RAS 連線各有一個。
在輸入時,應用程式必須將緩衝區中第一個RASCONN結構的 dwSize 成員設定為sizeof (RASCONN) ,才能識別所傳遞結構的版本。
[in, out] unnamedParam2
在輸入上,變數的指標包含 lprasconn 所指定的緩衝區大小,以位元組為單位。
在輸出時,函式會將此變數設定為列舉 RAS 連線所需的位元元組數目。
若要判斷所需的緩衝區大小,請呼叫 RasEnumConnections ,並將 lprasconn 設定為 NULL。 l其所指向的變數應該設定為零。 此函式會以 l ERROR_BUFFER_TOO_SMALL傳回所需的緩衝區大小。
[out] unnamedParam3
變數的指標,該變數會接收寫入 lprasconn 所指定之緩衝區的 RASCONN 結構數目。
傳回值
如果函式成功,傳回值 會ERROR_SUCCESS。
如果函式失敗,傳回值來自 路由和遠端訪問錯誤碼 或 Winerror.h。
傳回碼 | Description |
---|---|
|
lprasconn 緩衝區不夠大。 lcs 參數小於 lprasconn 參數中的 dwSize 成員,在呼叫函式之前應該先加以設定。 函式會傳回 l其所指向之變數中所需的緩衝區大小。 |
備註
如果在未指定電話簿專案名稱的情況下建立連線,則為該聯機傳回的資訊會提供前面加上 “.” 的連接電話號碼。
下列程式代碼範例程式代碼會使用 RasEnumConnections 列舉作用中的 RAS 連線。
#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "raserror.h"
#pragma comment(lib, "rasapi32.lib")
DWORD __cdecl wmain(){
DWORD dwCb = 0;
DWORD dwRet = ERROR_SUCCESS;
DWORD dwConnections = 0;
LPRASCONN lpRasConn = NULL;
// Call RasEnumConnections with lpRasConn = NULL. dwCb is returned with the required buffer size and
// a return code of ERROR_BUFFER_TOO_SMALL
dwRet = RasEnumConnections(lpRasConn, &dwCb, &dwConnections);
if (dwRet == ERROR_BUFFER_TOO_SMALL){
// Allocate the memory needed for the array of RAS structure(s).
lpRasConn = (LPRASCONN) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
if (lpRasConn == NULL){
wprintf(L"HeapAlloc failed!\n");
return 0;
}
// The first RASCONN structure in the array must contain the RASCONN structure size
lpRasConn[0].dwSize = sizeof(RASCONN);
// Call RasEnumConnections to enumerate active connections
dwRet = RasEnumConnections(lpRasConn, &dwCb, &dwConnections);
// If successful, print the names of the active connections.
if (ERROR_SUCCESS == dwRet){
wprintf(L"The following RAS connections are currently active:\n");
for (DWORD i = 0; i < dwConnections; i++){
wprintf(L"%s\n", lpRasConn[i].szEntryName);
}
}
//Deallocate memory for the connection buffer
HeapFree(GetProcessHeap(), 0, lpRasConn);
lpRasConn = NULL;
return 0;
}
// There was either a problem with RAS or there are no connections to enumerate
if(dwConnections >= 1){
wprintf(L"The operation failed to acquire the buffer size.\n");
}else{
wprintf(L"There are no active RAS connections.\n");
}
return 0;
}
RasEnumConnections 無法在 RAS 成功連線之前,將連線列舉為 作用 中。
Windows Me/98/95: RasEnumConnections 會在開始撥號 時立即列舉 連線。
列舉及檢查作用中連線的最可靠方式是呼叫 RasEnumConnections 或 RasDial 以取得連線句柄,然後呼叫 RasGetConnectStatus 以判斷實際的連線狀態。
注意
ras.h 標頭會將 RasEnumConnections 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows 2000 專業版 [僅限傳統型應用程式] |
最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
目標平台 | Windows |
標頭 | ras.h |
程式庫 | Rasapi32.lib |
Dll | Rasapi32.dll |