OpenPort function pointer

A port monitor's OpenPort function opens a printer port.

Syntax


typedef BOOL ( WINAPI *pfnOpenPort)(
   HANDLE  hMonitor,
   LPWSTR  pName,
   PHANDLE pHandle
);

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.)

pName

Caller-supplied pointer to a string containing the name of the port to be opened.

pHandle

Caller-supplied pointer to a location to receive a 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 OpenPort function and include the function's address in a MONITOR2 structure.

The OpenPort function is called, either by a language monitor or by the print spooler, when a print queue is being connected to a port. The OpenPort function's primary purpose is to return a port handle that the caller can use as an input argument for subsequent calls to the port monitor's StartDocPort, WritePort, ReadPort, EndDocPort, and GetPrinterDataFromPort functions.

Besides returning a port handle, the OpenPort function can perform initialization operations that need to be taken care of before read or write operations are performed. For example, if the port supports modifiable time-out values, the OpenPort function should set these values.

Calls to OpenPort are not print job-specific. Between each call to a port monitor's OpenPort and ClosePort functions, there can be multiple calls to its StartDocPort and EndDocPort functions.

You can assume that after the print spooler has called OpenPort with a particular port name, it will not call OpenPort again with the same port name before calling ClosePort.

Print monitor functions that accept a port handle as input do not also accept a monitor handle. Therefore, the OpenPort 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

InitializePrintMonitor2
OpenPortEx
SetPortTimeOuts
StartDocPort
WritePort
ReadPort
EndDocPort
GetPrinterDataFromPort
ClosePort

 

 

Send comments about this topic to Microsoft

Show: