3.1.4.47 RRasAdminConnectionGetInfoEx (Opnum 46)

  • Article

The RRasAdminConnectionGetInfoEx method<321> retrieves the connection information for a specific connection given in hDimConnection for a specified RRAS server using handle hDimServer. The caller SHOULD free the memory pointed to by pRasConnection.

 DWORD RRasAdminConnectionGetInfoEx(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD hDimConnection,
   [in] PMPRAPI_OBJECT_HEADER_IDL objectHeader,
   [out] PRAS_CONNECTION_EX_IDL pRasConnection
 );

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

hDimConnection: This is of type DWORD and MUST be set to a particular connection identifier for which the connection information is required. Obtain this handle by calling RRasAdminConnectionEnumEx (section 3.1.4.46). Because the RRASM server does not maintain the connection handles, the RRAS server SHOULD check and ensure that this handle represents a valid connection handle.

objectHeader: A pointer to MPRAPI_OBJECT_HEADER_IDL (section 2.2.1.2.129). In the structure, the revision field MUST be MPRAPI_RAS_CONNECTION_OBJECT_REVISION_1, the type field MUST be MPRAPI_OBJECT_TYPE_RAS_CONNECTION_OBJECT, and the size MUST be the size of RAS_CONNECTION_EX_IDL.

pRasConnection: Upon successful return, this is a pointer to a RAS_CONNECTION_EX_IDL (section 2.2.1.2.134) structure.

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

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 RouterType is ROUTER_TYPE_LAN, 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 RRAS server to perform the required management task.

  • If the RRAS server successfully processes the request, populate pRasConnection with information specific to the connection that was requested in hDimConnection. Return ERROR_SUCCESS to the caller. If the RRAS server doesn’t complete the request successfully, return the error status returned.

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