3.1.4.31 RMIBEntryGetFirst (Opnum 30)

The RMIBEntryGetFirst method SHOULD<294> retrieve the first value of an entry corresponding to the transport, protocol, and the MIB entry specified in pInfoStuct.

 DWORD
 RMIBEntryGetFirst(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwPid,
   [in] DWORD dwRoutingPid,
   [in, out] PDIM_MIB_ENTRY_CONTAINER pInfoStuct
 );

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

dwPid: Specifies the transport protocol. The value of this parameter MUST be one from the following table.<295>

Value	Meaning
PID_IPX 0x0000002B	An IPX MIB entry is to be retrieved.
PID_IP 0x00000021	An IPv4 MIB entry is to be retrieved.
PID_IPV6 0x00000057	An IPv6 MIB entry is to be retrieved.

dwRoutingPid: If dwPid is PID_IP and if dwRoutingPid is 10000, then pMibInEntry MUST point to MIB_OPAQUE_QUERY (section 2.2.1.2.53). The dwVarId field of MIB_OPAQUE_QUERY MUST be one of the following values. pMibOutEntry MUST be interpreted as a pointer to MIB_OPAQUE_QUERY. See section 2.2.1.2.53 for details on the structure retrieved by the rgdwVarIndex field of MIB_OPAQUE_QUERY for different dwVarId values.

dwVarId Value	Meaning
IF_NUMBER 0x00000000	Number of interfaces on the machine.
IF_TABLE 0x00000001	Information about interface table.
IF_ROW 0x00000002	Information about a particular interface.
IP_STATS 0x00000003	Information about the IP protocol.
IP_ADDRTABLE 0x00000004	Table of IPv4 address entries.
IP_ADDRROW 0x00000005	Information for a particular IPv4 address.
IP_FORWARDNUMBER 0x00000006	Information about number of routes in a particular IP routing table.
IP_FORWARDTABLE 0x00000007	Table of IPv4 route entries.
IP_NETTABLE 0x00000009	Table of ARP entries for IPv4 addresses.
IP_NETROW 0x0000000A	Information about an ARP table entry for an IPv4 address.
ICMP_STATS 0x0000000B	Statistics for ICMP messages on a particular computer.
TCP_STATS 0x0000000C	Statistics for the TCP protocol running on the local computer.
UDP_STATS 0x0000000F	Statistics for the UDP running on the local computer.
MCAST_MFE 0x00000012	Information for an IP multicast forwarding entry.
MCAST_MFE_STATS 0x00000013	Statistics associated with an MFE.
MCAST_IF_ENTRY 0x00000017	Information about an IP multicast interface.
ROUTE_MATCHING 0x0000001F	Information about a matching IP route.
BEST_IF 0x00000014	Index of the interface that has the best route to a particular destination IPv4 address.
MCAST_GLOBAL 0x00000018	Global information for IP multicast on a particular computer.
IF_STATUS 0x00000019	Status information for a particular interface.
MCAST_BOUNDARY 0x0000001A	Information about a router's scoped IPv4 multicast address boundaries.
MCAST_SCOPE 0x0000001B	Information about a multicast scope.

If dwPid is PID_IPV6 and dwRoutingPid is 10000, then pMibInEntry MUST point to MIB_OPAQUE_QUERY. The dwVarId field of pMibInEntry MUST be one of the following values. pMibOutEntry MUST be interpreted as a pointer to MIB_OPAQUE_QUERY. See section 2.2.1.2.53 for details on the structure retrieved by the rgdwVarIndex field of MIB_OPAQUE_QUERY for different dwVarId values.

dwVarId Value	Meaning
0x00000008 IP_FORWARDROW	Information about an IPv6 network route.

If dwPid is PID_IP and if dwRoutingPid is not IPRTRMGR_PID (0x00002710), then dwRoutingPid MUST be one of the entries in the Value column and pMibInEntry MUST be the corresponding entry in the Structure to be pointed to by pMibInEntry in the following table. The following specified routing protocols are valid only if the protocol is already initialized by RRAS for IPv4. RRAS initializes a protocol when an RTR_TOC_ENTRY with the InfoType corresponding to the protocol is present in the global configuration. The RRouterInterfaceTransportSetGlobalInfo method enables specifying the global configuration through the pGlobalInfo member of pInfoStuct.  

Value	Meaning	Structure to be pointed to by pMibInEntry.	Remarks
MS_IP_BOOTP 0x0000270F	An entry in IBOOTPMIB needs to be retrieved.	IPBOOTP_MIB_GET_INPUT_DATA	See section 2.2.1.2.152 for details on how to populate IPBOOTP_MIB_GET_INPUT_DATA to retrieve different types of MIB entries.  When this method returns pMibOutEntry, pInfoStruct MUST be cast to IPBOOTP_MIB_GET_OUTPUT_DATA. See section 2.2.1.2.157 on how to interpret the data returned.
MS_IP_NAT 0x81372715	An entry in the NAT MIB needs to be retrieved.	IP_NAT_MIB_QUERY	See IP_NAT_MIB_QUERY (section 2.2.1.2.182) for details on how to populate this structure to retrieve the entries required. The values are returned in IP_NAT_MIB_QUERY.
MS_IP_DNS_PROXY 0x81372713	An entry in DNS Proxy MIB needs to be retrieved.	IP_DNS_PROXY_MIB_QUERY	See section 2.2.1.2.186 for details on how to populate IP_DNS_PROXY_MIB_QUERY. The values are returned in IP_DNS_PROXY_MIB_QUERY.
MS_IP_DHCP_ALLOCATOR 0x81372714	An entry in auto DHCP MIB is retrieved.	IP_AUTO_DHCP_MIB_QUERY	See section 2.2.1.2.188 for details on how to populate IP_AUTO_DHCP_MIB_QUERY. The values are returned in the same structure.
MS_IP_OSPF<296> 0x0000000D	An entry in OSPF MIB needs to be retrieved.	MIB_DA_MSG MIB_DA_MSG OSPF_GLOBAL_PARAM OSPF_ROUTE_FILTER_INFO OSPF_PROTO_FILTER_INFO OSPF_AREA_PARAM OSPF_AREA_RANGE_PARAM OSPF_VIRT_INTERFACE_PARAM OSPF_NBMA_NEIGHBOR_PARAM

If dwPid is PID_IPV6 and if dwRoutingPid is not IPRTRMGR_PID (0x00002710), then dwRoutingPid MUST be one of the entries in the Value column and pMibInEntry MUST be the corresponding entry in the Structure to be pointed to by pMibInEntry in the following table. The following specified routing protocols are valid only if the protocol is already initialized by RRAS for IPv6. RRAS initializes a protocol when an RTR_TOC_ENTRY with the InfoType corresponding to the protocol is present in the global configuration. The RRouterInterfaceTransportSetGlobalInfo method enables specifying the global configuration through the pGlobalInfo member of pInfoStruct. 

Value	Meaning	Structure to be pointed to by pMibInEntry	Remarks
MS_IPV6_DHCP 0x000003E7	An entry in DHCPv6 Relay agent MIB needs to be retrieved.	DHCPV6R_MIB_GET_INPUT_DATA	See section 2.2.1.2.160 on how to populate DHCPV6R_MIB_GET_INPUT_DATA. The values are retuned in DHCPV6R_MIB_GET_OUTPUT_DATA.

pInfoStuct: The same as in RMIBEntryGet (section 3.1.4.30).   

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, as specified in section 2.1.1.1.

The opnum field value for this method is 30.

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 pInfoStuct is NULL, return an error other than those in the preceding table.

• If dwPid is not specified in the SupportedTransportsList, return an error other than those specified 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.

• Return any error status returned by the RRAS server while processing the request. Otherwise fill the MIB information returned by the RRAS server in the pInfoStruct and return ERROR_SUCCESS (0x00000000).

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