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