RasEnumConnectionsA 函式（ras.h）

發行項
11/20/2024

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。

傳回碼	描述
ERROR_BUFFER_TOO_SMALL	lprasconn 緩衝區不夠大。 l 參數小於呼叫函式之前，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 成功連線之前，無法將連線列舉為 Active。

Windows Me/98/95：RasEnumConnections 會在開始撥號時，將連線列舉為 Active。

列舉和檢查使用中聯機的最可靠方法是呼叫 RasEnumConnections 或 RasDial 以取得連線句柄，然後呼叫 RasGetConnectStatus 以判斷實際連線狀態。

注意

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

要求

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