3.1.4.46 RRasAdminConnectionEnumEx (Opnum 45)

  • Article

The RRasAdminConnectionEnumEx method<320> retrieves the list of all active connections for a specified RRAS server using handle hDimServer. The caller SHOULD free the memory pointed to by pRasConections.

 DWORD RRasAdminConnectionEnumEx(
   [in] DIM_HANDLE hDimServer,
   [in] PMPRAPI_OBJECT_HEADER_IDL objectHeader,
   [in] DWORD dwPreferedMaxLen,
   [out] LPDWORD lpdwEntriesRead,
   [out] LPDWORD lpdNumTotalElements,
   [out, size_is(,*lpdwEntriesRead)] 
     PRAS_CONNECTION_EX_IDL* pRasConections,
   [in, out, unique] LPDWORD lpdwResumeHandle
 );

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

objectHeader: The pointer to an MPRAPI_OBJECT_HEADER_IDL structure (section 2.2.1.2.129). In the structure, the revision field MUST be MPRAPI_RAS_CONNECTION_OBJECT_REVISION_1, type filed MUST be MPRAPI_OBJECT_TYPE_RAS_CONNECTION_OBJECT, and size MUST be size of RAS_CONNECTION_EX_IDL.

dwPreferedMaxLen: This parameter is of type DWORD and SHOULD specify the preferred maximum length of returned data (pRasConections) in bytes. If dwPreferedMaxLen is -1, the buffer returned is large enough to hold all available information. The number of entries returned is zero (0) in the case that dwPreferedMaxLen is less than the size of one item; otherwise, the number of entries returned is one more than what could be accommodated in dwPreferedMaxLen bytes.

lpdwEntriesRead: This is a pointer to type DWORD. Upon a successful function call return, this parameter determines the total number of connections enumerated from the current resume position given by lpdwResumeHandle.

lpdNumTotalElements: 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.

pRasConections: Upon successful return, this is a pointer array of  RAS_CONNECTION_EX_IDL (section 2.2.1.2.134) structures and the array size is determined by value pointed to by lpdwEntriesRead.

lpdwResumeHandle: This is a pointer to type DWORD and specifies a resume handle used to continue the enumeration. The lpdwResumeHandle parameter is NULL on the first call and left unchanged on subsequent calls (caller MUST pass the same returned value in the next call to this function). If the return code is ERROR_MORE_DATA, another call MAY be made using this handle to retrieve more data. If the handle is NULL upon return, the enumeration is complete. This handle is invalid for other types of error returns.

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 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 of the data was returned with this call. To obtain additional data, call the function again using the resume handle.

The opnum field value for this method is 45.

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 RouterType is ROUTER_TYPE_LAN, 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 successfully processes the request, populate pRasConections with information about the active connections returned by the RRAS server. For successful processing, the lpdwEntriesRead, lpdwNumTotalElements, and lpdwResumeHandle will be filled with the values returned by the RRAS server. If there are more entries to be enumerated, the RRAS implementation MUST return ERROR_MORE_DATA. If all the entries have been enumerated, the RRAS implementation MUST return ERROR_SUCCESS (0x00000000).

  • Otherwise, return the failure error status that is returned by the RRAS server.

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