3.1.4.38 RRouterInterfaceTransportCreate (Opnum 37)

The RRouterInterfaceTransportCreate method<304> is used to create a new transport on the RRAS server.

 DWORD RRouterInterfaceTransportCreate(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwTransportId,
   [in, string] LPWSTR lpwsTransportName,
   [in] PDIM_INTERFACE_CONTAINER pInfoStruct,
   [in, string] LPWSTR lpwsDLLPath
 );

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

dwTransportId: Specifies the transport for which the information is set (IPX, IPv4, or IPv6). It MUST be set to one of the following values.<305>

Value

Meaning

PID_IPX

0x0000002B

IPX protocol

PID_IP

0x00000021

IPv4 protocol

 PID_IPV6

0x00000057

IPv6 protocol

lpwsTransportName: Pointer to a null-terminated Unicode string that specifies the name of the transport being added. If this parameter is not specified, the dwTransportId parameter is converted into a string and used as the transport name.

pInfoStruct: Pointer to a DIM_INTERFACE_CONTAINER (section 2.2.1.2.2). This MUST NOT be NULL. The pGlobalInfo member of the DIM_INTERFACE_CONTAINER MUST NOT be NULL and MUST point to a valid RTR_INFO_BLOCK_HEADER (section 2.2.1.2.3) and RTR_TOC_ENTRY (section 2.2.1.2.4).

If dwTransportId is PID_IP or PID_IPV6, one or more of the following entries MUST be set in the InfoType field in the RTR_TOC_ENTRY (section 2.2.1.2.4) structure while passing to the method.

Value

Meaning and conditions

Structure pointed to at offset

IP_PROT_PRIORITY_INFO

0xFFFF0006

IPv4 and IPv6 route priority information is specified.

PRIORITY_INFO (section 2.2.1.2.12)

IP_PROT_PRIORITY_INFO_EX

0xFFFF0017

IPv4 and IPv6 route priority information is specified.

PRIORITY_INFO_EX (section 2.2.1.2.266)

IPV6_GLOBAL_INFO

0xFFFF000F

Global lPv6 logging and filtering information.

GLOBAL_INFO (section 2.2.1.2.9)

IP_GLOBAL_INFO

0xFFFF0003

Global lPv4 logging and filtering information.

GLOBAL_INFO (section 2.2.1.2.9)

lpwsDLLPath: Pointer to a null-terminated Unicode string that specifies the name of the router manager DLL for the specified transport. If this name is specified, the function sets the DLL path for this transport to this name.<306>

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 37.

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 one of the errors specified in the preceding table.

  • If dwTransportId is not specified in the SupportedTransportsList, 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.

  • Return any error status returned by the RRAS server. Otherwise return ERROR_SUCCESS.

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