OpenPrinter

The OpenPrinter function retrieves a handle identifying the specified printer or print server.

BOOL OpenPrinter(
  LPTSTR pPrinterName, // pointer to printer or server name
  LPHANDLE phPrinter,  // pointer to printer or server handle
  LPPRINTER_DEFAULTS pDefault 
                       // pointer to printer defaults structure
);
 

Parameters

pPrinterName

Pointer to a null-terminated string that specifies the name of the printer or print server.

phPrinter

Pointer to a variable that receives the handle identifying the opened printer or print server object.

Windows NT 5.0 and later: The phPrinter parameter can return an Xcv handle for use with the XcvData function. For more information about XcvData, see the Microsoft Windows NT Device Driver Kit documentation.

pDefault

Pointer to a PRINTER_DEFAULTS structure. This value can be NULL.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The pDefault parameter enables you to specify the data type and device mode values that are used for printing documents submitted by the StartDocPrinter function. However, you can override these values by using the SetJob function after a document has been started.

You can call the OpenPrinter function to open a handle to a print server or to determine the access rights that a client has to a print server. To do so, specify the name of the print server in the pPrinterName parameter, set the pDatatype and pDevMode members of the PRINTER_DEFAULTS structure to NULL, and set the DesiredAccess member to specify a server access mask value such as SERVER_ALL_ACCESS. When you are finished with the handle, pass it to the ClosePrinter function to close it.

Windows 95 and later: OpenPrinter ignores the DesiredAccess member of PRINTER_DEFAULTS.

Windows NT: Use the DesiredAccess member of the PRINTER_DEFAULTS structure to specify the access rights that you need to the printer. If you want to use the phPrinter handle to perform administrative tasks such as those provided by the SetPrinter function, set DesiredAccess to PRINTER_ALL_ACCESS. If you just want to perform basic printing operations, PRINTER_ACCESS_USE is sufficient.

If a user does not have permission to open a specified printer or print server with the desired access, the OpenPrinter call will fail, and GetLastError will return the value ERROR_ACCESS_DENIED.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Unsupported.
  Header: Declared in winspool.h.
  Import Library: Use winspool.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Printing and Print Spooler Overview, Printing and Print Spooler Functions, ClosePrinter, PRINTER_DEFAULTS, SetJob, SetPrinter, StartDocPrinter