Share via

3.1.4.3 RRasAdminConnectionGetInfo (Opnum 2)

  • Article

The RRasAdminConnectionGetInfo method retrieves the connection information for a particular connection identified by the passed handle of the connection given in hDimConnection. The RRAS server is identified by the server handle passed in hDimServer. The dwLevel defines the type of information requested. The caller MUST pass a pointer to a valid DIM_INFORMATION_CONTAINER (section 2.2.1.2.1), where DIM_INFORMATION_CONTAINER.dwBufferSize is initialized to zero (0). The caller SHOULD free the memory pointed to by pInfoStruct.  

 DWORD RRasAdminConnectionGetInfo(
   [in] DIM_HANDLE hDimServer,
   [in] DWORD dwLevel,
   [in] DWORD hDimConnection,
   [out] PDIM_INFORMATION_CONTAINER pInfoStruct
 );

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 one of the following values.

Value

Meaning

0

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as RASI_CONNECTION_0 (section 2.2.1.2.77). 

1

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as RASI_CONNECTION_1 (section 2.2.1.2.78). 

2

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as an array of RASI_CONNECTION_2 (section 2.2.1.2.79) structures. 

3

After the function returns, the memory pointed to by pInfoStruct->pBuffer is interpreted as RASI_CONNECTION_3 (section 2.2.1.2.80). 

hDimConnection: This is of type DWORD and SHOULD be set to a particular connection identifier for which the connection information is required. Obtain this handle by calling RRasAdminConnectionEnum (section 3.1.4.2). Since RRASM server does not maintain connection handle information, the validation of this handle SHOULD be done by the RRAS server implementation. 

pInfoStruct: This is a pointer of type DIM_INFORMATION_CONTAINER, and DIM_INFORMATION_CONTAINER.dwBufferSize is initialized to zero (0). Upon successful return, the pInfoStruct->pBuffer is a cast to an array of RASI_CONNECTION_0, RASI_CONNECTION_1, RASI_CONNECTION_2, or RASI_CONNECTION_3 structures, based on the dwLevel value.

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, the value contains an error code, as specified in [MS-ERREF] or 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 2.

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 not, then return error ERROR_ACCESS_DENIED (0x00000005).

  • If the RouterType is ROUTER_TYPE_LAN, return an error other than those in the preceding table.

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

  • If the RRAS server successfully processes the request, populate the pInfoStruct with the information returned by the RRAS server and 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].