pfnOpenPortEx callback function
A language monitor's OpenPortEx function opens a printer port.
Syntax
pfnOpenPortEx OpenPortEx;
BOOL WINAPI OpenPortEx(
_In_ HANDLE hMonitor,
_In_ HANDLE hMonitorPort,
_In_ LPWSTR pPortName,
_In_ LPWSTR pPrinterName,
_Out_ PHANDLE pHandle,
_In_ struct _MONITOR2 *pMonitor
)
{ ... }
Parameters
hMonitor [in]
Caller supplied language 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.) In a cluster environment, there can be multiple instances of language monitors.hMonitorPort [in]
Caller supplied port 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.) A language monitor must use this handle when it calls functions in the port monitor's MONITOR2 structure.pPortName [in]
Caller-supplied pointer to a string containing the name of the port to be opened.pPrinterName [in]
Caller-supplied pointer to a string containing the name of the printer that is connected to the port.pHandle [out]
Caller-supplied pointer to a location to receive a port handle.pMonitor [in]
Caller-supplied pointer to the MONITOR2 structure returned by a port monitor's InitializePrintMonitor2 function.
Return value
If the operation succeeds, the function should return TRUE. Otherwise it should return FALSE.
Remarks
Language monitors are required to define an OpenPortEx function and include its address in a MONITOR2 structure. The OpenPortEx function is called by the print spooler when a print queue is being connected to a port.
The OpenPortEx function's primary purpose is to return a port handle that the caller can use as an input argument for subsequent calls to the language monitor's StartDocPort, WritePort, ReadPort, EndDocPort, and GetPrinterDataFromPort functions. Because a language monitor typically implements these functions by calling the equivalent functions in its associated port monitor, a language monitor typically obtains a port handle by calling the port monitor's OpenPort function. For more information see Language and Port Monitor Interaction.
The OpenPortEx function's pMonitor parameter is a pointer to the port monitor's MONITOR2 structure. This structure contains pointers to the port monitor's callable functions. The OpenPortEx function should check the structure to verify that all required function pointers are non-NULL. If the structure is valid, the function should copy it into local storage. Otherwise OpenPortEx should call SetLastError, specifying ERROR_INVALID_PRINT_MONITOR, and return FALSE.
Print monitor functions that accept a port handle as input do not also accept a monitor handle. Therefore, the OpenPortEx function must store the received monitor handle in a location that can be referenced by the port handle. This allows the functions that accept a port handle to reference the monitor handle.
Requirements
Target platform |
Desktop |
Header |
Winsplp.h (include Winsplp.h) |
See also