3.1.4.6.5 RpcXcvData (Opnum 88)

  • Article

RpcXcvData provides an extensible mechanism by which a client can control ports on the server and exchange port specific commands and data with the server.<363>

 DWORD RpcXcvData(
   [in] PRINTER_HANDLE hXcv,
   [in, string] const wchar_t* pszDataName,
   [in, size_is(cbInputData)] BYTE* pInputData,
   [in] DWORD cbInputData,
   [out, size_is(cbOutputData)] BYTE* pOutputData,
   [in] DWORD cbOutputData,
   [out] DWORD* pcbOutputNeeded,
   [in, out] DWORD* pdwStatus
 );

hXcv: A handle to a port or port monitor object that was opened by RpcOpenPrinter (section 3.1.4.2.2) or RpcOpenPrinterEx (section 3.1.4.2.14).

pszDataName: A pointer to a string representing the name of the requested data or action. The following table shows the actions that SHOULD be supported. Other port monitor–specific action strings MAY be supported.<364>

Value

Description

"AddPort"

Add an instance of a specific port type controlled by the port monitor.

"DeletePort"

Delete an instance of a specific port type controlled by the port monitor.

"MonitorUI"

The action returns the name of the associated port monitor client-side executable configuration module in the buffer that is referenced by the pOutputData parameter.

pInputData: A pointer to a buffer that contains input data. This parameter can be NULL if cbInputData equals zero.

cbInputData: The size, in bytes, of the buffer pointed to by the pInputData parameter.

pOutputData: A pointer to a buffer to receive output data. This parameter can be NULL if cbOutputData equals zero.

cbOutputData: The size, in bytes, of the buffer pointed to by the pOutputData parameter.

pcbOutputNeeded: A pointer to a location that receives the size, in bytes, required for the buffer pointed to by the pOutputData parameter.

pdwStatus: A pointer to a variable that receives the status value that is returned by the port monitor's XcvData method. The value MUST be zero to indicate successful completion or a nonzero Windows error code to indicate failure [MS-ERREF].

Return Values: This method MUST return zero (ERROR_SUCCESS) to indicate that the print server successfully called the port monitor's XcvData method, or a nonzero Windows error code to indicate failure [MS-ERREF].

Upon receiving this message, the server MUST validate parameters as follows:

  • Perform the validation steps specified in PRINTER_HANDLE Parameters, section 3.1.4.1.11, substituting hXcv for hPrinter. This method assumes that the handle to the port object can be used without further access checks.

The print server SHOULD<365> further validate parameters as follows:

  • Verify that the string referenced by the pszDataName parameter is a valid command name, and if that verification fails, return ERROR_INVALID_PARAMETER.

  • Verify that pdwStatus is not NULL, and if that verification fails, return ERROR_INVALID_PARAMETER.

  • If the pszDataName parameter is set to "AddPort", verify that the pInputData parameter is not set to NULL, verify that the value of the cbInputData parameter is not zero and that the pInputData parameter contains a null terminated character string, and if those verifications fail, return ERROR_INVALID_DATA.

  • If the action returns information in pOutputData and cbOutputData is not zero, verify that the value of the pOutputData parameter is not NULL, and if that verification fails, return ERROR_INVALID_PARAMETER.

  • For actions that return data in the buffer that is pointed to by the pOutputData parameter, verify that the size of the buffer, as specified by the value of the cbOutputData parameter, is sufficient. If that verification fails, store the required buffer size in the variable that is pointed to by the pcbOutputNeeded parameter and return ERROR_INSUFFICIENT_BUFFER [MS-ERREF].

If parameter validation fails, the server MUST fail the operation immediately and return a nonzero error response to the client. Otherwise, the server MUST process the message and compose a response to the client as follows:

  • Load the executable object of the monitor that supports the port that is associated with the port object that is referenced by the hXcv parameter.

  • Invoke the XcvData method in that library, passing in the pszDataName, pInputData, cbInputData, pOutputData, cbOutputData, pcbOutputNeeded, and pdwStatus parameters.

  • Return the status from the XcvData method.

The port monitor's XcvData method processes the message by performing the operation indicated by the string pointed to by the pszDataName parameter, and then composes a response as follows:

  • If the pOutputData parameter is not NULL, copy the output data from the method into pOutputData, up to the limit that is specified by the value of the cbOutputData parameter.

  • Write the size of the data that was copied into pcbOutputNeeded.

  • If the pdwStatus parameter is not NULL, store the status of the port in the variable that is referenced by the pdwStatus parameter.

  • Return the status of the operation.