3.1.4.37 RRouterDeviceEnum (Opnum 36)

  • Article

The RRouterDeviceEnum method<305> retrieves the list of all the devices from the specified server. The hDimServer handle specifies the RRASM server on which the call is 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->pBuffer.  

 DWORD RRouterDeviceEnum(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwLevel,
   [in, out] PDIM_INFORMATION_CONTAINER pInfoStruct,
   [in, out] LPDWORD lpdwTotalEntries
 );

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 to by pInfoStruct->pBuffer it is interpreted as array of MPR_DEVICE_0 (section 2.2.1.2.85). The size of the array is determined by lpdwEntriesRead.  

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

lpdwTotalEntries: This is a pointer to type DWORD and receives the total number of devices that have been enumerated.

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.

The opnum field value for this method is 36.

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 one of the errors 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 completes the request successfully, place the returned information in pInfoStruct and set lpdwTotalEntries to the number of entries returned by RRAS server and 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].