Share via

3.1.4.2 RRasAdminConnectionEnum (Opnum 1)

  • Article

The RRasAdminConnectionEnum method retrieves the list of active connections for a specified RRASM server identified by the handle hDimServer. The dwLevel specifies the type of information requested. The caller MUST pass a pointer to a valid DIM_INFORMATION_CONTAINER (section 2.2.1.2.1), where DIM_INFORMATION_CONTAINER.dwBufferSize is initialized to zero (0). After the function returns, the caller SHOULD free the memory pointed to by pInfoStruct.  

 DWORD RRasAdminConnectionEnum(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwLevel,
   [in, out] PDIM_INFORMATION_CONTAINER pInfoStruct,
   [in] DWORD dwPreferedMaximumLength,
   [out] LPDWORD lpdwEntriesRead,
   [out] LPDWORD lpdwTotalEntries,
   [in, out, unique] LPDWORD lpdwResumeHandle
 );

hDimServer: A handle to the RRASM server where the call is executed, see section 3.1.3.

dwLevel: This is of type DWORD and SHOULD be set to one of the following values.

Value

Meaning

0

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as an array of RASI_CONNECTION_0 (section 2.2.1.2.77). The size of the array is determined by lpdwEntriesRead. 

1

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as an array of RASI_CONNECTION_1 (section 2.2.1.2.78). The size of the array is determined by lpdwEntriesRead. 

2

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as an array of RASI_CONNECTION_2 (section 2.2.1.2.79). The size of the array is determined by lpdwEntriesRead. 

3

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as an array of RASI_CONNECTION_3 (section 2.2.1.2.80)).The size of the array is determined by lpdwEntriesRead. 

4

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as an array of RAS_CONNECTION_4_IDL (section 2.2.1.2.236). The size of the array is determined by lpdwEntriesRead.

pInfoStruct: This is a pointer of type DIM_INFORMATION_CONTAINER, and DIM_INFORMATION_CONTAINER.dwBufferSize is initialized to zero (0). Upon successful return, the pInfoStruct->pBuffer is a typecast array of RASI_CONNECTION_0, RASI_CONNECTION_1, RASI_CONNECTION_2, RASI_CONNECTION_3,<253> or RAS_CONNECTION_4_IDL based on the dwLevel value. The array size is determined by the value in memory pointed to by lpdwEntriesRead.

dwPreferedMaximumLength: This is of type DWORD and SHOULD specify the preferred maximum length of the returned data (pInfoStruct->pBuffer) in bytes.

lpdwEntriesRead: This is a pointer to type DWORD and upon a successful function-call return specifies the total number of connections enumerated from the current resume position given by lpdwResumeHandle.

lpdwTotalEntries: This is a pointer to type DWORD and receives the total number of connections that could have been enumerated from the current resume position given by lpdwResumeHandle.

lpdwResumeHandle: This is a pointer to type DWORD and specifies a resume handle that is used to continue the enumeration. The lpdwResumeHandle parameter is zero (0) on the first call and left unchanged on subsequent calls. The caller MUST pass the same returned value in the next call to this function; otherwise, an error is returned. If the return code is ERROR_MORE_DATA, another call can be made using this handle to retrieve more data. If the return code is not ERROR_MORE_DATA, the handle returned SHOULD be ignored. A return value of ERROR_SUCCESS indicates a successful completion of the enumeration. Any return value other than ERROR_SUCCESS or ERROR_MORE_DATA indicates the failure of the enumeration.

Return Values: A 32-bit, unsigned integer value that indicates return status. A return value of ERROR_SUCCESS (0x00000000) indicates that the operation was completed successfully; otherwise, the return value contains an error code, as specified in [MS-ERREF] or in section 2.2.4. All values that are not in the table that follows MUST be treated the same by the RRASM client.

Return value/code

Description

ERROR_SUCCESS

0x00000000

The call was successful.

ERROR_ACCESS_DENIED

0x00000005

The calling application does not have sufficient privileges as specified in section 2.1.1.1.

ERROR_MORE_DATA

0x000000EA

Not all the data was returned with this call. To obtain additional data, call the function again using the handle that was returned in the lpdwResumeHandle parameter.

The opnum field value for this method is 1.

When processing this call, the RRASM server MUST do the following:

  • Validate, as specified in section 2.1.1.1, whether this method was called by a client that has access to the method. If the client does not have access, then return error ERROR_ACCESS_DENIED (0x00000005).

  • If the RouterType (section 2.2.3.4.1) is ROUTER_TYPE_LAN, return an error other than those in the preceding table. 

  • If pInfoStruct is NULL, return an error other than those in the preceding table.

  • If dwLevel is not supported, return an error other than those in the preceding table.

  • Call the abstract interface Invoke DIMSVC method specifying the operation and the parameters to enable RRAS server to perform the required management task.

  • If the RRAS server processes the request successfully, populate the information returned by RRAS server in pInfoStruct, along with lpdwEntriesRead, lpdwTotalEntries, and lpdwResumeHandle, and return ERROR_SUCCESS (0x00000000).

  • Otherwise return the failure error that the RRAS server returns.

 No exceptions are thrown beyond those thrown by the underlying RPC protocol [MS-RPCE].