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].