XcvOpenPort function

A port monitor server DLL's XcvOpenPort function opens a port for configuration operations.

Syntax


BOOL XcvOpenPort(
   HANDLE      hMonitor,
   LPCWSTR     pszObject,
   ACCESS_MASK GrantedAccess,
   PHANDLE     phXcv
);

Parameters

hMonitor

Caller supplied monitor instance handle. This is the handle returned by the monitor's InitializePrintMonitor2 function. (This parameter does not exist if the print monitor supports InitializePrintMonitor instead of InitializePrintMonitor2.)

pszObject

Caller-supplied pointer to a string representing the name of the port. Can be NULL, and most monitors do not need this parameter.

GrantedAccess

Caller-supplied ACCESS_MASK structure containing the access granted to the user during a print monitor UI DLL's call to the spooler's OpenPrinter function. See the following Remarks section.

phXcv

Caller-supplied pointer to a location to receive a function-supplied port handle.

Return value

If the operation succeeds, the function should return TRUE. Otherwise it should return FALSE.

Remarks

Port monitor server DLLs are required to define an XcvOpenPort function and include its address in a MONITOR2 structure.

The spooler's OpenPrinter function (described in the Microsoft Windows SDK documentation) calls XcvOpenPort if the specified printer name includes either of the strings "XcvPort" or "XcvMonitor". For more information, see AddPortUI.

The XcvOpenPort function should open the port for configuration purposes. This operation might only consist of storing the input arguments for subsequent use within XcvDataPort. The function should return a handle to the stored information in the location pointed to by phXcv. This handle is returned to the caller of OpenPrinter, and subsequently received as an input argument to XcvDataPort.

The function should save the granted access mask. Later, when the server DLL's XcvDataPort function is called, the granted access should be compared with SERVER_ACCESS_ADMINISTER and if the comparison fails, XcvDataPort should return ERROR_ACCESS_DENIED.

Requirements

Target platform

Desktop

Header

Winsplp.h (include Winsplp.h)

See also

InitializePrintMonitor2
XcvClosePort
XcvDataPort
AddPortUI

 

 

Send comments about this topic to Microsoft

Show: