3.1.4.41 RRouterInterfaceSetCredentialsEx (Opnum 40)

  • Article

The RRouterInterfaceSetCredentialsEx method<312> is used to set extended credentials (other than username and password) information for an interface. This function is used to set credentials information used for the EAP methods or used as a key that is shared between two routers (a preshared key).

 DWORD RRouterInterfaceSetCredentialsEx(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwLevel,
   [in] 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: Specifies the format of the credentials information. This parameter MUST be one of the following values: 0x00000000, 0x0000001, 0x0000002, or 0x00000003. A value of zero (0) indicates that this is EAP information, and the MPR_CREDENTIALSEX_1 structure MUST contain EAPTLS_USER_PROPERTIES (section 2.2.1.2.128). A value of one, two, or three (these can be used interchangeably) indicate that the credentials information is a preshared key and is formatted as an MPR_CREDENTIALSEX_1 structure. The preshared key specifies the preshared key to be used with IPsec for L2TP over IPsec connections.

pInfoStruct: Pointer to the DIM_INFORMATION_CONTAINER (section 2.2.1.2.1), the pBuffer pointer of which points to the MPR_CREDENTIALSEX_1 structure that contains the credential information to be set for the interface.

hInterface: Handle to the interface. This can be obtained from RRouterInterfaceCreate (section 3.1.4.13) or RRouterInterfaceGetHandle (section 3.1.4.12). If dwLevel is 0x0000002 and hInterface is NULL, the preshared key is used for L2TP. Since the RRASM server does not maintain the interface handles, the RRAS server SHOULD check and ensure that this handle is 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, as specified in section 2.1.1.1.

The opnum field value for this method is 40.

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.

  • 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 any error the RRAS server returns while processing the request. Otherwise return ERROR_SUCCESS (0x00000000).

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