3.1.4.21 RRouterInterfaceEnum (Opnum 20)

  • Article

The RRouterInterfaceEnum method<280> Retrieves the list of all the interfaces from the specified server. The hDimServer handle specifies the RRASM server on which the call is to be executed. 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 RRouterInterfaceEnum(
   [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 to be executed, see section 3.1.3.

dwLevel: This is of type DWORD and SHOULD be set to zero (0).

pInfoStruct: This is a pointer of type DIM_INFORMATION_CONTAINER.  pInfoStruct.dwBufferSize SHOULD be initialized to zero (0). Upon successful return, the pInfoStruct->pBuffer is cast to an array of MPRI_INTERFACE_0 (section 2.2.1.2.81), 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 this parameter is -1, the buffer returned is large enough to hold all available information.

lpdwEntriesRead: This is a pointer to type DWORD. Upon successful return, this determines 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 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). If the return code is ERROR_MORE_DATA (0x000000EA), 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, it 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. This error code value can correspond to a RRAS Management Protocol–specific failure, which takes a value between 600 and 975, or any generic failure.

The return value is one of the following error codes. All other error values MUST be treated the same.

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

More information is available; the enumeration can be continued.

The opnum field value for this method is 20.

 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 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 interface information in pInfoStruct and fill the values for lpdwResumeHandle, lpdwEntriesRead, and lpdwTotalEntries as returned by the RRAS server. If the RRAS server has updated the resume handle and there are more entries to be enumerated, return ERROR_MORE_DATA. Otherwise, return ERROR_SUCCESS (0x00000000).

  • Otherwise return the error status provided by RRAS server.

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