XcvDataPort

A port monitor server DLL's XcvDataPort function receives information from, and returns information to, the port monitor's UI DLL.

DWORD
  XcvDataPort(
    HANDLE  hXcv,
    LPCWSTR  pszDataName,
    PBYTE  pInputData,
    DWORD  cbInputData,
    PBYTE  pOutputData,
    DWORD  cbOutputData,
    PDWORD  pcbOutputNeeded
    );

Parameters

hXcv

Caller-supplied printer handle, obtained by calling OpenPrinter (described in the Platform SDK documentation). This handle is created and returned by the XcvOpenPort function.

pszDataName

Caller-supplied pointer to a string representing the name of the data being requested. For more information, see the following Comments section.

pInputData

Caller-supplied pointer to a buffer containing input data.

cbInputData

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

pOutputData

Caller-supplied pointer to a buffer to receive output data.

cbOutputData

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

pcbOutputNeeded

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

Return Value

If the operation succeeds, this function should return ERROR_SUCCESS. Otherwise, it should return an ERROR_-prefixed Win32 error code. The print monitor UI DLL receives this value in the pdwStatus location specified for XcvData.

Headers

Declared in winsplp.h. Include winsplp.h.

Comments

Port monitor server DLLs are required to define an XcvDataPort function so they can receive information from, and return information to, port monitor UI DLLs. The function's address must be included in a MONITOR2 structure.

The XcvDataPort function is called by the spooler's XcvData function. The function parameters for XcvDataPort and XcvData are almost identical. (XcvData has an additional parameter, pdwStatus, that is not present in XcvDataPort.)

The string pointed to by pszDataName specifies the operation to be performed. The function must recognize the following data name strings:

Typically, the function is written to recognize additional, customized strings that are sent by the UI DLL from within its AddPortUI, ConfigurePortUI, and DeletePortUI functions. These strings might represent commands that request current configuration values from the server DLL, or that deliver new values. For example, your XcvDataPort function might recognize the string "GetTransmissionRetryTimeout", which your UI DLL could send to your server DLL to request the currently stored transmission retry time-out value. Or, you might define a set of strings that must be sent before "AddPort" or "DeletePort" is sent, where the strings are used to supply information identifying the port to add or delete.

For a given pszDataName string and input buffer, XcvDataPort might first be called with a cbOutputData value of zero. The function should return a required buffer size in pcbOutputNeeded, along with a return value of ERROR_INSUFFICIENT_BUFFER. The caller can use the value received in pcbOutputNeeded to allocate an output buffer of adequate size, and can then call XcvDataPort again, this time specifying the allocated buffer size in cbOutputData.

The XcvDataPort function must validate all input arguments. Specifically, the function must:

• Validate the contents of the string pointed to by the pszDataName parameter. If this string represents an administrative operation (typically adding, deleting, or configuring a port), the XcvDataPort function should compare the granted access mask that was previously received by the XcvOpenPort function with SERVER_ACCESS_ADMINISTER. If the comparison fails, XcvDataPort must return ERROR_ACCESS_DENIED.
• Validate the contents of the buffer pointed to by the pInputData parameter. When the spooler calls the XcvOpenPort function, it performs no validation on the contents of this buffer. The monitor can make no assumptions about the validity of this data, which can come from a malicious application.

If you are writing a port monitor that will communicate with TCPMON, see TCPMON Xcv Interface.

See Also

XcvOpenPort, XcvData, AddPortUI, ConfigurePortUI, DeletePortUI