OpenPort function

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

Syntax

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

Parameters

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)
Library NtosKrnl.exe

See Also

GetPrinterDataFromPort

SetPortTimeOuts

ClosePort

StartDocPort

OpenPortEx

InitializePrintMonitor2

WritePort

EndDocPort

ReadPort