The RasEnumConnections function lists all active RAS connections. It returns each connection's handle and phone-book entry name.
Syntax
DWORD RasEnumConnections( __inout LPRASCONN lprasconn, __inout LPDWORD lpcb, __out LPDWORD lpcConnections );
Parameters
- lprasconn [in, out]
Pointer to a buffer that receives, on output, an array of RASCONN structures, one for each RAS connection.
On input, an application must set the dwSize member of the first RASCONN structure in the buffer to sizeof(RASCONN) in order to identify the version of the structure being passed.
- lpcb [in, out]
Pointer to a variable that, on input, contains the size, in bytes, of the buffer specified by lprasconn.
On output, the function sets this variable to the number of bytes required to enumerate the RAS connections.
Note
To determine the required buffer size, call RasEnumConnections with lprasconn set to NULL. The variable pointed to by lpcb should be set to zero. The function will return the required buffer size in lpcb and an error code of ERROR_BUFFER_TOO_SMALL.
- lpcConnections [out]
Pointer to a variable that receives the number of RASCONN structures written to the buffer specified by lprasconn.
Return Value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is from Routing and Remote Access Error Codes or Winerror.h.
| Return code | Description |
|---|---|
| The lprasconn buffer is not large enough. The lpcb parameter is less than the dwSize member in the lprasconn parameter which is should be set prior to calling the function. The function returns the required buffer size in the variable pointed to by lpcb. |
Remarks
If a connection was made without specifying a phone-book entry name, the information returned for that connection gives the connection phone number preceded by ".".
The following code sample code uses RasEnumConnections to enumerates the active RAS connections.
#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "raserror.h"
#pragma comment(lib, "rasapi32.lib")
DWORD __cdecl wmain(DWORD argc, WCHAR * pArgv[]){
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 cannot enumerate a connection as Active until RAS has successfully connected.
Windows Me/98/95: RasEnumConnections enumerates a connection as Active as soon as it starts dialing.
The most reliable way to enumerate and check for an active connection is to call RasEnumConnections or RasDial to get a connection handle, then call RasGetConnectStatus to determine the actual connection state.
Requirements
Minimum supported client | Windows 2000 Professional |
|---|---|
Minimum supported server | Windows 2000 Server |
Header | Ras.h |
Library | Rasapi32.lib |
DLL | Rasapi32.dll |
Unicode and ANSI names | RasEnumConnectionsW (Unicode) and RasEnumConnectionsA (ANSI) |
See Also
- Remote Access Service (RAS) Overview
- Remote Access Service Functions
- RASCONN
- RasEnumEntries
- RasGetConnectStatus
Send comments about this topic to Microsoft
Build date: 7/2/2010
If another connection is established between you asking for the size and you asking for the buffer to be filled, your buffer size will not be sufficient even if you have included the sizeof(RASCONN) workaround below.
If you use this API in any critical code, you should probably call it in a (bounded) loop so that if the second call fails due to buffer sizes you can try again from the start a few times.
- 6/14/2010
- Leo Davidson
You need to work around a design flaw in this API (and the documentation) if you want your code to work with versions of Windows older than the SDK version you are compiling against.
When you call RasEnumConnections(NULL, &dwCb, &dwConnections) the OS sets dwCb based on the largest RASCONN structure size that it knows about. The size given is "sizeof(RASCONN) * dwConnections" but where "sizeof(RASCONN)" is based on the headers at the time the OS was compiled, not the headers you are actually using when compiling your code.
(Since you have to specify NULL for the first argument, you cannot tell the OS the sizeof(RASCONN) value from your headers; the OS must be using its own largest known size as an upper bound. That is what Windows 7 appears to do, at least.)
If your sizeof(RASCONN) is larger than the operating system's -- which will happen if you compile with the Vista SDK and then run the code on XP, for example -- then the second call to RasEnumConnections will fail if you use the bytesize the OS tells you to. That is because in the second call, where the buffer argument is not NULL, you can & must tell the OS your sizeof(RASCONN) and it will then realise that the buffer size is too small to fit the required number of structures (dwConnections).
Luckily, at least with Windows 7, in the first call with the NULL buffer, the dwConnections value is set by the API as well as the dwCb value. That means you can do this:
if (ERROR_BUFFER_TOO_SMALL != ::RasEnumConnections(NULL, &dwCb, &dwConnections))
{
return false; // No connections or an error. Not connected, either way.
}
// The OS returns the buffer sized based on the largest RASCONN structure it knows about.
// If we are compiled with an SDK from a later OS version that has a larger RASCONN structure
// then the OS's suggested buffer size will not be large enough. So allocate the maximum of
// what the OS tells us and what is actually needed.
if (dwCb < (dwConnections * sizeof(RASCONN)))
{
dwCb = (dwConnections * sizeof(RASCONN));
}
// ...now allocate a buffer dwCb bytes in size and use that in the second call...
- 6/14/2010
- Leo Davidson
