3.3.4.5 RasRpcSubmitRequest (Opnum 12)

  • Article

The RasRpcSubmitRequest method retrieves or sets the configuration data on RRAS server.

 DWORD RasRpcSubmitRequest(
   [in] handle_t h,
   [in, out, unique, size_is(dwcbBufSize)] 
     PBYTE pReqBuffer,
   [in] DWORD dwcbBufSize
 );

hServer: An RPC binding handle as specified in [C706] section 2.

pReqBuffer: A pointer to a buffer of size dwcbBufSize. The buffer MUST be large enough to hold the RequestBuffer structure (section 2.2.1.2.217) and RequestBuffer.RB_Buffer data. RequestBuffer.RB_Reqtype specifies the request type which will be processed by the server and RequestBuffer.RB_Buffer specifies the structure specific to RB_Reqtype to be processed. The structure that MUST be used for each ReqTypes value is explained in section 2.2.1.2.217. The client MUST NOT send the ReqType other than those defined in ReqTypes (section 2.2.1.1.18). RequestBuffer.RB_PCBIndex MUST be set to the unique port identifier whose information is sought for ReqTypes REQTYPE_GETINFO and REQTYPE_GETDEVCONFIG. For other valid ReqTypes, RequestBuffer.RB_PCBIndex MUST be set to zero (0).

dwcbBufSize: Size in byte of pReqBuffer.

Return Values: Specifies the return status as explained in section 2.2.1.2.218 for retcode field.

Exceptions Thrown: This method throws an exception with the exception code RPC_S_ACCESS_DENIED (0x00000005) if the client is not an administrator on the RRASM server, with access permission to perform the operation.<340>

Validations which SHOULD be done by the RRASM for all ReqTypes are:

  • Return ERROR_SUCCESS (0x00000000) if one of the following conditions are met without any further processing of the call:

    • dwcbBufSize is less than the sum of size of RequestBuffer and 5000, i.e. if the condition (dwcbBufSize < size of RequestBuffer + 5000) is TRUE.

    • pReqBuffer is NULL

    • pReqBuffer.RB_ReqType is less than zero (0) or greater than maximum ReqTypes<341>

  • Validate as specified in section 3.3.4 whether this method was called by a client that is an administrator of the RRASM server.

Specific RRASM behavior for each ReqTypes value follows.

REQTYPE_GETDEVICECONFIGINFO:

When processing this request, the RRASM SHOULD do the following:

  • The dwcbBufSize that is passed in SHOULD be greater than or equal to the sum of the size of RequestBuffer (section 2.2.1.2.217) with the RB_Buffer field specifying the DeviceConfigInfo (section 2.2.1.2.218) structure, and the size of DeviceConfigInfo.cbBuffer. If this is not the case, RRASM MUST return the ERROR_SUCCESS (0x00000000) setting DeviceConfigInfo.retcode to E_INVALIDARG (0x80070057).

  • If DeviceConfigInfo.dwVersion is not set to the version of Rasrpc Server<342>, RRASM MUST return ERROR_SUCCESS (0x00000000) setting DeviceConfigInfo.retcode to ERROR_NOT_SUPPORTED (0x00000032).

  • Call the abstract interface Invoke RASRPC specifying the method and the parameters necessary to enable RRAS server to perform the required management task.

  • MUST set the cEntries to the number of devices returned by the RRAS.

  • MUST check the passed in cbBuffer size, and copy the device information details (RAS_DEVICE_INFO (section 2.2.1.2.219)) for the devices that fit in the cbBuffer size to abdata buffer.

  • cbBuffer MUST be set to the total size in bytes needed to hold all the device information. It MUST be set to the value of cEntries multiplied by the size of RAS_DEVICE_INFO.

  • dwVersion MUST be set to the version of the Rasrpc server.

  • If there is no error, ERROR_SUCCESS (0x00000000) MUST be returned setting DeviceConfigInfo.retcode to ERROR_SUCCESS (0x00000000).

REQTYPE_SETDEVICECONFIGINFO:

When processing this request, the RRASM MUST do the following:

  • The dwcbBufSize that is passed in SHOULD be greater than or equal to the sum of the size of RequestBuffer (section 2.2.1.2.217) with the RB_Buffer field specifying the DeviceConfigInfo (section 2.2.1.2.218) structure, and the size of DeviceConfigInfo.cbBuffer. The dwcbBufSize passed in SHOULD be equal to or greater than sum of the size of RequestBuffer, size of DeviceConfigInfo and DeviceConfigInfo.cbBuffer. If not, then ERROR_SUCCESS (0x00000000) MUST be returned setting DeviceConfigInfo.retcode to E_INVALIDARG (0x80070057).

  • The DeviceConfigInfo.cbBuffer SHOULD be greater than or equal to size of all the device information (RAS_DEVICE_INFO) as specified in DeviceConfigInfo.cEntries. If not, RRASM MUST return ERROR_SUCCESS (0x00000000) and also set DeviceConfigInfo.retcode to ERROR_INVALID_PARAMETER (0x00000057).

  • Call the abstract interface Invoke RASRPC method specifying the operation and the parameters to enable RRAS server to perform the required management task.

  • If the RRAS implementation does not have any of the devices, RAS_DEVICE_INFO.dwError for that device MUST be set to ERROR_DEVICE_DOES_NOT_EXIST (0x00000260).

  • If RAS_DEVICE_INFO.fWrite is set and the RRAS implementation could not succeed in storing the device information, then DeviceConfigInfo.retcode MUST be set to ERROR_CAN_NOT_COMPLETE (0x000003EB).

  • If RAS_DEVICE_INFO.dwNumEndPoints or RAS_DEVICE_INFO.dwMaxWanEndPoints is more than the maximum supported value for the WAN endpoint on the RRAS server, it MUST be set to the maximum supported value.

  • If the RRAS server returns no error status, ERROR_SUCCESS (0x00000000) MUST be returned setting DeviceConfigInfo.retcode to ERROR_SUCCESS. Otherwise return the error status returned by the RRAS server in DeviceConfigInfo.retcode.

REQTYPE_GETINFO:

When processing this request, the RRASM SHOULD do the following:

  • The dwcbBufSize that is passed in SHOULD be greater than or equal to the size of RequestBuffer (section 2.2.1.2.217) with the RB_Buffer field specifying the size of the Info structure. If not, RRASM MUST return ERROR_SUCCESS (0x00000000) setting Info.retcode to E_INVALIDARG (0x80070057).

  • Since the RRASM server does not manage the list of valid port identifiers, the RRAS implementation SHOULD check if the RequestBuffer.RB_PCBIndex refers to a valid port identifier. If the port identifier is not valid, RRASM MUST return ERROR_SUCCESS (0x00000000) and also set Info.retcode to ERROR_PORT_NOT_FOUND (0x00000267).

  • Call the abstract interface Invoke RASRPC method specifying the operation and the parameters to enable RRAS server to perform the required management task.

  • SHOULD<343> validate if the passed in RequestBuffer.RB_Dummy is equal to the size of ULONG_PTR on the server. If it is not equal and passed in RequestBuffer.RB_Dummy is equal to the size of DWORD, the RRASM server MUST marshal the RASMAN_INFO.RI_ConnectionHandle from HANDLE to ULONG.

  • If the RRAS server successfully processes the request, the RRASM server MUST populate the RequestBuffer.RB_Buffer (Info) structure with the port information provided by RRAS server and return ERROR_SUCCESS (0x00000000).

REQTYPE_GETCALLEDID:

When processing this request, the RRASM MUST do the following:

  • The dwcbBufSize that is passed in SHOULD be greater than or equal to the sum of the size of RequestBuffer (section 2.2.1.2.217) with the RB_Buffer field specifying the GetSetCalledId (section 2.2.1.2.220) structure, and the size of GetSetCalledId.rciInfo.dwSize. If not, RRASM MUST return ERROR_SUCCESS (0x00000000) and also set GetSetCalledId.retcode to E_INVALIDARG (0x80070057).

  • Call the abstract interface Invoke RASRPC method specifying the operation and the parameters to enable RRAS server to perform the required management task.

  •  GetSetCalledId.dwSize SHOULD be equal to or greater than the sum of the size of RAS_CALLEDID_INFO (section 2.2.1.2.221) and the size of CalledId buffer to be returned. If so, fill the GetSetCalledId.rciInfo buffer with the CalledId details returned by the RRAS server. Otherwise GetSetCalledId.rciInfo buffer is not filled with the CalledId details.

  • MUST set the GetSetCalledId.dwSize to the sum of the size of RAS_CALLEDID_INFO and the size of CalledId buffer to be returned and return ERROR_SUCCESS (0x00000000).

REQTYPE_SETCALLEDID:

When processing this request, the RRASM MUST do the following:

  • The dwcbBufSize that is passed in SHOULD be greater than or equal to the sum of the size of RequestBuffer (section 2.2.1.2.217) with the RB_Buffer field specifying the GetSetCalledId structure, and the size of GetSetCalledId.rciInfo.dwSize. If not, RRASM MUST return ERROR_SUCCESS (0x00000000) setting GetSetCalledId.retcode to E_INVALIDARG (0x80070057).

  • Call the abstract interface Invoke RASRPC method specifying the operation and the parameters to enable RRAS server to perform the required management task.

  • If all validation is successful, the RRAS server MUST store the GetSetCalledId.rciInfo buffer that contains CalledId details.

  • Return any error the RRAS server returns while processing the request. Otherwise return ERROR_SUCCESS (0x00000000).

REQTYPE_PORTENUM:

When processing this request, the RRASM MUST do the following:

  • The dwcbBufSize that is passed in SHOULD be greater than or equal to the sum of the size of the RequestBuffer structure specifying the Enum (section 2.2.1.2.225) structure, and Enum.size. If not, RRASM MUST return ERROR_SUCCESS (0x00000000) setting Enum.retcode to E_INVALIDARG (0x80070057).

  • Call the abstract interface Invoke RASRPC method specifying the operation and the parameters to enable RRAS server to perform the required management task.

  • MUST set the Enum.entries to the number of available port devices returned by the RRAS server.

  • MUST check the passed in Enum.size and copy all of the port information details (RASMAN_PORT_32 (section 2.2.1.2.226)) for the ports that fit in the Enum.size to Enum.buffer.

  • Enum.size MUST be set to the total size in bytes needed to hold all the port information.

  • If there is no error, the server MUST return ERROR_SUCCESS (0x00000000).

REQTYPE_GETNDISWANDRIVERCAPS:

When processing this request, the RRASM MUST do the following:

  • The dwcbBufSize that is passed in SHOULD be greater than or equal to the size of the RequestBuffer structure with the RB_Buffer field specifying the GetNdiswanDriverCapsStruct (section 2.2.1.2.222) structure. If not, RRASM MUST return ERROR_SUCCESS (0x00000000) setting GetNdiswanDriverCapsStruct.retcode to E_INVALIDARG (0x80070057).

  • Call the abstract interface Invoke RASRPC method specifying the operation and the parameters to enable the RRAS server to perform the required management task.

  • If all validation is successful, populate the GetNdiswanDriverCapsStruct with the encryption capabilities returned by the RRAS server and set GetNdiswanDriverCapsStruct.retcode to ERROR_SUCCESS (0x00000000). If there is any error while retrieving the encryption capabilities of RRAS, set the GetNdiswanDriverCapsStruct.retcode with the error. RRASM MUST return ERROR_SUCCESS (0x00000000).

REQTYPE_GETDEVCONFIG:

When processing this request, the RRASM MUST do the following:

  • The dwcbBufSize that is passed in SHOULD be greater than or equal to the sum of the size of the RequestBuffer structure with the RB_Buffer field specifying the GetDevConfigStruct (section 2.2.1.2.224) structure, and GetDevConfigStruct.size. If not, RRASM MUST return ERROR_SUCCESS (0x00000000) setting GetDevConfigStruct.retcode to E_INVALIDARG (0x80070057).

  • Because RRASM does not maintain the list of valid port identifiers, the RRAS server SHOULD check that RequestBuffer.RB_PCBIndex is a valid port identifier. If this is not the case, RRAS MUST return ERROR_SUCCESS (0x00000000) setting GetDevConfigStruct.retcode to ERROR_PORT_NOT_FOUND (0x00000267).

  • If the device type specified by GetDevConfigStruct.devicetype does not exist on the RRAS server, the RRAS implementation MUST return ERROR_SUCCESS (0x00000000) setting GetDevConfigStruct.retcode to ERROR_DEVICE_DOES_NOT_EXIST (0x00000260).

  • If the device type associated with the port as identified by RequestBuffer.RB_PCBIndex is a value other than "MODEM", RRASM MUST return ERROR_SUCCESS (0x00000000) setting GetDevConfigStruct.retcode to ERROR_SUCCESS (0x00000000) and GetDevConfigStruct.size to zero (0).

  • Call the abstract interface Invoke RASRPC method specifying the operation and the parameters to enable RRAS server to perform the required management task.

  • Check if GetDevConfigStruct.size is large enough to hold the device information as returned by RRAS. If not, RRASM MUST return ERROR_SUCCESS (0x00000000) setting GetDevConfigStruct.retcode to ERROR_BUFFER_TOO_SMALL (0x0000025B). Set the GetDevConfigStruct.size to the size of the required buffer to hold device information.

  • If all validation is successful, the RRAS server MUST get the device configuration information associated with the port identified by RequestBuffer.RB_PCBIndex and fill the GetDevConfigStruct.config buffer with the details and set the GetDevConfigStruct.size to the size of the buffer copied to GetDevConfigStruct.config. Server MUST return ERROR_SUCCESS (0x00000000).