3.1.4.14 RRouterInterfaceGetInfo (Opnum 13)

The RRouterInterfaceGetInfo method<263> retrieves information for a specified interface, hInterface, on a specified RRAS server, hDimServer. This method is used to find information about existing interfaces on the RRAS. The information is returned in pInfoStruct. The caller SHOULD free the memory pointed to by pInfoStruct.

 DWORD RRouterInterfaceGetInfo(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwLevel,
   [in, out] PDIM_INFORMATION_CONTAINER pInfoStruct,
   [in] DWORD hInterface
 );

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

dwLevel: This is of type DWORD and MUST be set to any of the following values.

Value

Meaning

0

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as MPRI_INTERFACE_0 (section 2.2.1.2.81)

1

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as MPRI_INTERFACE_1 (section 2.2.1.2.82)

2

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as MPRI_INTERFACE_2 (section 2.2.1.2.83)

3

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as MPRI_INTERFACE_3 (section 2.2.1.2.84)

pInfoStruct: This is a pointer of type DIM_INFORMATION_CONTAINER (section 2.2.1.2.1), and DIM_INFORMATION_CONTAINER.dwBufferSize SHOULD be initialized to zero (0). Upon successful return, the pInfoStruct->pBuffer is cast to an array of MPRI_INTERFACE_0, MPRI_INTERFACE_1, MPRI_INTERFACE_2, or MPRI_INTERFACE_3 structures based on the dwLevel values. 

The dwfOptions member of MPRI_INTERFACE_2 and MPRI_INTERFACE_3 SHOULD be updated as follows:

  • If the dwfOptions member has neither MPRIO_RequirePAP nor MPRIO_RequireEAP, then enable MPRIO_RequireEncryptedPw.

  • If the dwfOptions has none of the following flags set, then enable MPRIO_RequireMsEncryptedPw:

    • MPRIO_RequireCHAP

    • MPRIO_RequirePAP

    • MPRIO_RequireEAP

  • If the dwEncryptionType member is not set to MPR_ET_None or MPR_ET_Optional, enable the MPRIO_RequireDataEncryption flag.

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). The interface MUST be of type ROUTER_IF_TYPE_FULL_ROUTER if dwLevel is set to 2 or 3. Because the RRASM server does not maintain the interface handles, the RRAS server SHOULD check and ensure that this handle value 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, the return value contains an error code, as specified in [MS-ERREF] or in section 2.2.4. All values that are not listed 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 13.

 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 those in the preceding table.

  • If dwLevel is not supported, return an error other than those in the preceding table.

  • If the hInterface value specified is not associated with an interface entry in InterfaceList that has a matching interface handle (value being the same), return an error other than one of the errors specified in the preceding table.

  • If dwLevel value is specified as 2 or 3 and lpszEntry is not present in PhonebookEntryNameList, return an error other than one of the errors 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.

  • If the RRAS server has processed the request successfully, populate the pInfoStruct with the information returned by the RRAS server and return ERROR_SUCCESS.

  • Otherwise return the error status returned by the RRAS server.

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