Share via

3.1.4.5 RRasAdminPortEnum (Opnum 4)

  • Article

The RRasAdminPortEnum method retrieves the list of all ports on a RRAS server, or the ports for a specified connection determined by hRasConnection. The hDimServer handle specifies the RRAS server on which the call is executed. The dwLevel defines 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). The caller SHOULD free the memory pointed to by pInfoStruct.  

 DWORD RRasAdminPortEnum(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwLevel,
   [in] DWORD hRasConnection,
   [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 to be executed, see section 3.1.3.

dwLevel: This is of type DWORD and MUST be set to the following value.

Value

Meaning

0

After the function returns, the memory pointed by pInfoStruct->pBuffer is interpreted as an array of RASI_PORT_0 (section 2.2.1.2.75). The size of the array is determined by lpdwEntriesRead. This includes information related to the Port object during runtime. The port objects SHOULD be initialized based on the port configurations defined by WanEndpoints (section 2.2.3.3.1.8). The Device Name is also returned as a part of each port information. 

hRasConnection: This is of type DWORD and SHOULD be set to a particular connection identifier for which the connection information is required. Obtain this handle by calling RRasAdminConnectionEnum (section 3.1.4.2). If this parameter is passed as INVALID_HANDLE_VALUE (0xFFFFFFFF), the function enumerates all the active ports configured on the RRAS server. Since RRASM server does not maintain connection handle information, the validation of this handle SHOULD be done by the RRAS server implementation. 

pInfoStruct: This is a pointer of type DIM_INFORMATION_CONTAINER (section 2.2.1.2.1), and DIM_INFORMATION_CONTAINER.dwBufferSize is initialized to zero (0). Upon successful return, the pInfoStruct->pBuffer is typecast to an array of RASI_PORT_0, and the array size is determined by the value to pointer lpdwEntriesRead. 

dwPreferedMaximumLength: This is of type DWORD and SHOULD specify the preferred maximum length of returned data (pInfoStruct->pBuffer) in bytes. If dwPreferedMaximumLength is -1 then all existing port entries for the specified connection are returned in the buffer.

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

lpdwTotalEntries: This is a pointer to type DWORD and receives the total number of ports 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 (0x000000EA), another call can be made using this handle to retrieve more data. If the handle is NULL upon return, the enumeration is complete. This handle is invalid (-1) 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, it contains an error code, as specified in [MS-ERREF] or section 2.2.4. All values that are not listed 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.

ERROR_MORE_DATA

0x000000EA

Not all of 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 4.

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 the RRAS server to perform the required management task.

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

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

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