3.1.4.40 RRouterInterfaceDeviceSetInfo (Opnum 39)

The RRouterInterfaceDeviceSetInfo method<308> sets the information for a specified device, dwIndex, for a specified interface, hInterface, on a specified server, hDimServer.

 DWORD RRouterInterfaceDeviceSetInfo(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwLevel,
   [in] PDIM_INFORMATION_CONTAINER pInfoStruct,
   [in] DWORD dwIndex,
   [in] DWORD hInterface
 );

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 one of the following values.

Value

Meaning

0

pInfoStruct->pBuffer MUST be set to point to MPR_DEVICE_0 (section 2.2.1.2.86).

1

 pInfoStruct->pBuffer MUST be set to point to MPR_DEVICE_1 (section 2.2.1.2.87).

pInfoStruct: This is a pointer of type DIM_INFORMATION_CONTAINER (section 2.2.1.2.1) and MUST be set to the following, based on dwLevel. The szDeviceName MUST be one of the devices as specified by RRouterDeviceEnum. The szDeviceType specified in the structure SHOULD be validated against the actual type of the device specified by szDeviceName. If the szDeviceType is incorrect, the actual device type SHOULD be used by the server instead.

dwLevel

pInfoStruct->size

pInfoStruct->pBuffer

0

Should be set to the size of MPR_DEVICE_0 (section 2.2.1.2.86).

This MUST be set to point to MPR_DEVICE_0.

1

Should be set to the size of MPR_DEVICE_1 (section 2.2.1.2.87).

This MUST be set to a point to MPR_DEVICE_1.

dwIndex: Specifies the 1-based index of the device. A multilinked demand-dial interface uses multiple devices. If the device information specified for dwIndex 1 is either a PPPoE interface or a VPN interface, any other device information, specified (with dwIndex > 1), SHOULD be ignored. If the device information specified for dwIndex 1 is a serial or ISDN device, the connection SHOULD be treated as a multilink-capable connection. Any other device information, specified (with dwIndex > 1), SHOULD be treated as device information for the individual links. Device information with type szDeviceType, which is neither modem nor ISDN, SHOULD<309> be ignored.

hInterface: The unique identifier of an interface. This can be obtained from RRouterInterfaceCreate (section 3.1.4.13) or RRouterInterfaceGetHandle (section 3.1.4.12). Since the RRASM server does not maintain the interface handles, the RRAS server implementation SHOULD check and ensure that this handle represents a valid interface handle.

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.

The opnum field value for this method is 39.

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.

  • 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 the RRAS server to perform the required management task.

  • Return the error status that is returned by the RRAS server while processing the request. Otherwise return ERROR_SUCCESS.

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