XcvData function

Warning  

Starting with Windows 10, the APIs which support third-party print providers are deprecated. Microsoft does not recommend any investment into third-party print providers. Additionally, on Windows 8 and newer products where the v4 print driver model is available, third-party print providers may not create or manage queues which use v4 print drivers.

 

The print spooler's XcvData function is the means by which a port monitor UI DLL communicates with its associated port monitor server DLL. Win32 applications can also call XcvData.

Syntax

BOOL XcvData(
  _In_      HANDLE hXcv,
  _In_      PCTSTR pszDataName,
  _In_opt_  PBYTE  pInputData,
            DWORD  cbInputData,
  _Out_opt_ PBYTE  pOutputData,
            DWORD  cbOutputData,
  _Out_     PDWORD pcbOutputNeeded,
  _Out_opt_ PDWORD pdwStatus
);

Parameters

  • hXcv [in]
    Caller-supplied printer handle, obtained by calling the OpenPrinter function (described in the Microsoft Windows SDK documentation).

  • pszDataName [in]
    Caller-supplied pointer to a string representing the name of the data being requested. For more information, see XcvDataPort.

  • pInputData [in, optional]
    Caller-supplied pointer to a buffer containing input data.

  • cbInputData
    Caller-supplied size, in bytes, of the buffer pointed to by pInputData.

  • pOutputData [out, optional]
    Caller-supplied pointer to a buffer to receive output data.

  • cbOutputData
    Caller-supplied size, in bytes, of the buffer pointed to by pOutputData.

  • pcbOutputNeeded [out]
    Caller-supplied pointer to a location to receive the minimum size, in bytes, required for the buffer pointed to by pOutputData.

  • pdwStatus [out, optional]
    Caller-supplied pointer to a location to receive the status value returned by XcvDataPort. The returned value should be an ERROR_-prefixed Win32 error code.

Return value

If the operation succeeds, the function returns TRUE. Otherwise the function returns FALSE. The caller can obtain an error code by calling GetLastError.

Remarks

The print spooler's XcvData function is called by port monitor UI DLLs so they can communicate with their associated port monitor server DLLs.

The XcvData function calls the port monitor server DLL's XcvDataPort function and returns its result in the location pointed to by the pdwStatus parameter.

The string pointed to by pszDataName must be one that the server DLL's XcvDataPort function recognizes. Contents, if any, of the input and output buffers are dependent on the data name string.

With the exception of pdwStatus, the function parameters for XcvData and XcvDataPort are identical. For more information about XcvData and XcvDataPort parameters, see XcvDataPort.

Win32 applications can also call XcvData, to add or delete printer ports without invoking the user interface that the Win32 AddPort function displays. Applications can specify the following standard values for pszDataName:

Data Name String Operation

L"AddPort"

Notifies the port monitor server DLL that all information about the port has been sent, so the server can add the port.

The pInputData parameter must point to a NULL-terminated port name string.

The pOutputData, cbOutputData, and pcbOutputNeeded parameters are not used.

L"DeletePort"

Notifies the port monitor server DLL that the port can be deleted.

The pInputData parameter must point to a NULL-terminated port name string.

The pOutputData, cbOutputData, and pcbOutputNeeded parameters are not used.

 

Note that additional, monitor-specific data name strings might be defined. To communicate with a vendor-supplied port monitor, it might be necessary to send additional, customized data name strings before sending "AddPort" or "DeletePort".

The XcvData function can used to communicate with the standard TCP/IP port monitor. See TCPMON Xcv Interface for details.

Requirements

Target platform

Desktop

Header

Winspool.h (include Winspool.h)

See also

XcvDataPort

 

 

Send comments about this topic to Microsoft