OpenPort

BOOL (WINAPI *pfnOpenPort)(

LPWSTR pName,
PHANDLE pHandle
);

OpenPort opens a port for a printer.

Parameters

pName

Points to a string that specifies the name of the port to be opened.

pHandle

Points to the location in which the port handle will be returned.

Return Value

The return value is TRUE if the function is successful, FALSE if it fails.

Comments

All port monitors must implement OpenPort, whereas language monitors implement OpenPortEx. Monitors that combine both port and language monitor capabilities in one DLL need to implement both OpenPort and OpenPortEx.

OpenPort is called by the spooler whenever a port is assigned to a printer. It returns a handle to the port identified by pName. The spooler uses the returned port handle in subsequent calls to the port monitor's StartDocPort, WritePort, ReadPort, and EndDocPort routines. The spooler waits for OpenPort to return, so a monitor should return success or fail within a reasonable amount of time.

If necessary, the port monitor should lock other processes from using the specified port after it has been connected to a printer.

OpenPort can also perform any one-time port initializations needed to set up the port for printing. To avoid hung or unreasonably delayed port responses, port monitors should always establish reasonable time-outs before actually calling a port. Port timeouts can be established as a part of OpenPort's one-time port initializations, or by SetPortTimeouts.

Note that the parameter lists for OpenPort and the language monitor's OpenPortEx function differ in that OpenPortEx also receives the printer name and a port monitor's function table.

See Also

ClosePort, OpenPortEx, SetPortTimeouts