Share via

3.1.4.12 RRouterInterfaceGetHandle (Opnum 11)

  • Article

The RRouterInterfaceGetHandle method<260> retrieves the handle of the specified interface lpwsInterfaceName among all the ROUTER_INTERFACE_TYPEs. The hDimServer handle determines the RRAS server on which the call is made.

 DWORD RRouterInterfaceGetHandle(
   [in] DIM_HANDLE hDimServer,
   [in, string] LPWSTR lpwsInterfaceName,
   [in, out] LPDWORD phInterface,
   [in] DWORD fIncludeClientInterfaces
 );

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

lpwsInterfaceName: Pointer to a null-terminated Unicode string that specifies the name of the interface to be retrieved.

phInterface: This is a pointer to a DWORD that receives the unique identifier of the interface specified by lpwsInterfaceName.

fIncludeClientInterfaces: Specifies whether the method includes client interfaces while searching. If this parameter is 0, interfaces of type ROUTER_IF_TYPE_CLIENT are ignored in the search for the interface with the name specified by lpwsInterfaceName. If this parameter is a nonzero value and an interface with the specified name exists, RRouterInterfaceGetHandle returns a handle to an interface of type ROUTER_IF_TYPE_CLIENT. Since it is possible that there are several interfaces of type ROUTER_IF_TYPE_CLIENT, the handle returned references the first interface that is found with the name ROUTER_IF_TYPE_CLIENT specified by lpwsInterfaceName.

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

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 lpwsInterfaceName is NULL, return an error other than those specified in the preceding table.

  • If the interface name of any entry in InterfaceList is not the same as lpwsInterfaceName, 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 successfully processed the request, populate the interface handle in phInterface. This interface handle is the same as the one present as a part of the interface-specific entry in InterfaceList. Return ERROR_SUCCESS.

  • Otherwise return the error provided by the RRAS server.

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