3.1.4.29 RMIBEntrySet (Opnum 28)

  • Article

The RMIBEntrySet method<290> modifies an MIB entry in the IPv4 forwarding table.

 DWORD
 RMIBEntrySet(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwPid,
   [in] DWORD dwRoutingPid,
   [in] 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 PID_IP. The method MUST return an error other than those specified in the return value table for any other value.

Value

Meaning

PID_IP

0x00000021

An IPv4 MIB entry is to be deleted.

dwRoutingPid: Specifies the routing protocol. This MUST be 0x00002710 (10000) and indicate that pInfoStruct MUST point to MIB_OPAQUE_QUERY (section 2.2.1.2.53). Otherwise, an error other than those specified in the return table value is returned.

pInfoStuct: This MUST be a pointer to the structure DIM_MIB_ENTRY_CONTAINER (section 2.2.1.2.19) with valid dwMibInEntrySize and pMibInEntry fields. The dwMibOutEntrySize and pMibOutEntry of the structure are ignored by the server for this method. dwMibInEntrySize MUST be set to the size of data being passed in pMibInEntry. If pInfoStuct is NULL, an error other than those specified in the return value table is returned. Otherwise, the pointer is treated as a pointer to the structure DIM_MIB_ENTRY_CONTAINER.   

Since the dwRoutingPid parameter of this method MUST take a value IPRTRMGR_PID (0x00002710), the pMibInEntry field of pInfoStuct MUST be a pointer to MIB_OPAQUE_INFO (section 2.2.1.2.52). The dwId and rgbyData fields of MIB_OPAQUE_INFO MUST be set to one of the values in the following table.

dwId Value

Structure that MUST be pointed to by rgbyData

Remarks

ROUTE_MATCHING

0x0000001F

MIB_IPDESTROW (section 2.2.1.2.20)

A route corresponding to data in rgbyData is added in the IPv4 route table.

The route is created with the following fields:

ForwardRow: Contains the MIB_IPFORWARDROW (section 2.2.1.2.35) structure that contains the route information with the following fields set:

  • dwForwardDest

  • dwForwardMask

  • dwForwardPolicy

  • dwForwardNextHop

  • ForwardType

  • ForwardProto

  • dwForwardAge

  • dwForwardNextHopAS

  • dwForwardMetric1

  • dwForwardMetric2

  • dwForwardMetric3

  • dwForwardMetric4

  • dwForwardMetric5

  • dwForwardPreference

  • dwForwardViewSet

  • dwRtInfoDest

  • dwRtInfoMask

  • dwRtInfoNextHop

  • dwRtInfoIfIndex

  • dwRtInfoProto

  • dwRtInfoMetric1

  • dwRtInfoMetric2

  • dwRtInfoMetric3

pMibInEntry: The following fields are set to these values irrespective of the values specified (INTERFACE_ROUTE_INFO (section 2.2.1.2.11)):

  • dwForwardPolicy is set to 0.

  • dwForwardMetric4 and dwForwardMetric5 are set to MIB_IPROUTE_METRIC_UNUSED (-1).

  • dwForwardPreference is set to IP_PRIORITY_DEFAULT_METRIC (0x0000007F).

IF_ROW

0x00000002

MIB_IFROW (section 2.2.1.2.29)

Only dwAdminStatus can be set to IF_ADMIN_STATUS_DOWN or IF_ADMIN_STATUS_UP (see dwAdminStatus of INTERFACE_STATUS_INFO (section 2.2.1.2.18).

MCAST_IF_ENTRY

0x00000017

MIB_IPMCAST_IF_ENTRY (section 2.2.1.2.40)

dwTtl MUST be set to less than or equal to 255.

dwRateLimit MUST NOT be set to 0.

dwIfIndex MUST be set to the index of the interface for which the entries are being updated.

The following entries can be set only if the operational status of the interface is IF_OPER_STATUS_OPERATIONAL (see dwOperStatus of MIB_IFROW:

ulInMcastOctets

ulOutMcastOctets

MCAST_BOUNDARY

0x0000001A

MIB_IPMCAST_BOUNDARY (section 2.2.1.2.37)

If dwStatus is set to ROWSTATUS_CREATEANDGO, the boundary information specified in MIB_IPMCAST_BOUNDARY is created.

If dwStatus field is set to ROWSTATUS_DESTROY, the boundary information specified in MIB_IPMCAST_BOUNDARY is deleted.

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.

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.

All error values MUST be treated the same and as long as ERROR_SUCCESS is not returned the call is deemed failed.

The opnum field value for this method is 28.

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 specified 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 that the RRAS server might return while processing the request. Otherwise return ERROR_SUCCESS (0x00000000).

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