3.1.4.13 RRouterInterfaceCreate (Opnum 12)

  • Article

The RRouterInterfaceCreate method creates an interface on a specified RRAS server, hDimServer.<261>

 DWORD RRouterInterfaceCreate(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwLevel,
   [in] PDIM_INFORMATION_CONTAINER pInfoStruct,
   [in, out] LPDWORD phInterface
 );

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

The pInfoStruct->pBuffer MUST be set to point to a MPRI_INTERFACE_0 (section 2.2.1.2.81). 

1

The pInfoStruct->pBuffer MUST be set to point to a MPRI_INTERFACE_1 (section 2.2.1.2.82). 

2

The pInfoStruct->pBuffer MUST be set to point to a MPRI_INTERFACE_2 (section 2.2.1.2.83). 

3

The pInfoStruct->pBuffer MUST be set to point to a 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 MUST be set to following, based on dwLevel. 

dwLevel

pInfoStruct->size

pInfoStruct->pBuffer

0

This MUST be set to the size of MPRI_INTERFACE_0 (section 2.2.1.2.81). Otherwise, an error is returned. 

This MUST be set to point to MPRI_INTERFACE_0.

Only the wszInterfaceName, fEnabled, and dwIfType fields of MPRI_INTERFACE_0 can be set. Setting other values has no effect.

1

This MUST be set to the size of MPRI_INTERFACE_1 (section 2.2.1.2.82). Otherwise, an error is returned. 

This MUST be set to point to MPRI_INTERFACE_1.

Only the wszInterfaceName, fEnabled, dwIfType fields of MPRI_INTERFACE_1 can be set. Setting other values has no effect.

2

This MUST be set to the size of MPRI_INTERFACE_2 (section 2.2.1.2.83). Otherwise, an error is returned. 

This MUST be set to point to MPRI_INTERFACE_2.

The dwIfType of MPRI_INTERFACE_2 SHOULD be set to ROUTER_IF_TYPE_FULL_ROUTER. The szAlternates of MPRI_INTERFACE_2 MUST be set to 0.

3

This MUST be set to the size of MPRI_INTERFACE_3 (section 2.2.1.2.84). Otherwise, an error is returned. 

This MUST be set to point to MPRI_INTERFACE_3.

The dwIfType of MPRI_INTERFACE_3 SHOULD be set to ROUTER_IF_TYPE_FULL_ROUTER. The szAlternates of MPRI_INTERFACE_3 MUST be set to 0. The values of the ipv6addrDns and ipv6addrDnsAlt members of the MPRI_INTERFACE_3 structure SHOULD be ignored by the server.

If dwIfType is set to ROUTER_IF_TYPE_TUNNEL1 or ROUTER_IF_TYPE_DIALOUT in MPRI_INTERFACE_0, MPRI_INTERFACE_1, MPRI_INTERFACE_2, or MPRI_INTERFACE_3, an error is returned.<262>

If dwIfType is set to ROUTER_IF_TYPE_DEDICATED, ROUTER_IF_TYPE_INTERNAL, or ROUTER_IF_TYPE_LOOPBACK, and if fEnabled is set to FALSE, an error other than one of the errors specified in the table that follows MUST be returned.

If the dwIfType in MPRI_INTERFACE_0, MPRI_INTERFACE_1, MPRI_INTERFACE_2, or MPRI_INTERFACE_3, is set to ROUTER_IF_TYPE_CLIENT, ROUTER_IF_TYPE_HOME_ROUTER, or ROUTER_IF_TYPE_FULL_ROUTER, and if the RouterType is ROUTER_TYPE_LAN, an error SHOULD be returned.

If dwIfType in MPRI_INTERFACE_0 is set to ROUTER_IF_TYPE_FULL_ROUTER, phonebook information for the interface MUST have already been configured in the phonebook file.

If dwLevel is either 2 or 3 and none of the authentication protocol-related flags MPRIO_RequireMsCHAP2, MPRIO_RequireCHAP, and MPRIO_RequireEAP are specified in the dwfOptions member, then the dwEncryptionType member of the MPRI_INTERFACE_2 or MPRI_INTERFACE_3 structures SHOULD be initialized to MPR_ET_Require and the value of the dwfOptions member SHOULD be modified to enable the following flags by default:

  • MPRIO_RequireEncryptedPw

  • MPRIO_RequireDataEncryption

  • MPRIO_RequireCHAP

  • MPRIO_RequireMsCHAP2

phInterface: This is a pointer to a DWORD that specifies the unique identifier of the interface that is created. This is the same as the dwInterface in MPRI_INTERFACE_0, MPRI_INTERFACE_1, MPRI_INTERFACE_2, or MPRI_INTERFACE_3.

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.

The opnum field value for this method is 12.

 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 interface name of any entry in InterfaceList is the same as wszInterfaceName specified as a part of MPRI_INTERFACE_0, MPRI_INTERFACE_1, MPRI_INTERFACE_2, and MPRI_INTERFACE_3, 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 the RRAS server to perform the required management task.

  • If the RRAS server processes the request successfully, populate the phInterface with the interface handle returned by the RRAS server, add an interface entry to the InterfaceList comprising the interface name to be the wszInterfaceName (present as a part of the MPRI_INTERFACE_0, MPRI_INTERFACE_1, MPRI_INTERFACE_2, or MPRI_INTERFACE_3 structure) and the interface handle to be the value filled in for phInterface. If dwLevel value is specified as 2 or 3, add the wszInterfaceName specified as a part of MPRI_INTERFACE_2 or MPRI_INTERFACE_3 into PhonebookEntryNameList and return ERROR_SUCCESS.

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

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