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
ERROR_BUFFER_TOO_SMALL
 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

另請參閱

RASCONN

RasEnumEntries

RasGetConnectStatus

遠端訪問服務 (RAS) 概觀

遠端存取服務函式