DrvPrinterEvent

BOOL DrvPrinterEvent

LPWSTR pPrinterName,
INT DriverEvent,
DWORD Flags,
LPARAM lParam
);

DrvPrinterEvent is called by the print subsystem when an event occurs that might require action by the printer driver.

Parameters

pPrinterName

Pointer to a null-terminated string that identifies the printer. The string name can identify a local or remote printer; that is, it can be in the form of “PrinterName” or “\\Machine\PrinterName”.

DriverEvent

Specifies the event that occurred. Possible values for DriverEvent are as follows:

• PRINTER_EVENT_ADD_CONNECTION

• PRINTER_EVENT_DELETE_CONNECTION

• PRINTER_EVENT_INITIALIZE

• PRINTER_EVENT_DELETE

• PRINTER_EVENT_CACHE_REFRESH

• PRINTER_EVENT_CACHE_DELETE

Flags

Bitmask in which the following field can be set:

Value	Meaning
PRINTER_EVENT_FLAG_NO_UI	The driver should not display any kind of user interface.

lParam

Specifies the parameters associated with the event that occurred. This field is currently always null.

Return Value

DrvPrinterEvent returns TRUE upon success; otherwise it returns FALSE.

Comments

The print subsystem calls DrvPrinterEvent when certain events occur that might require action by the printer driver. Printer interface drivers must support the PRINTER_EVENT_INITIALIZE event; all other events can be supported optionally. Details associated with each DriverEvent are described in the sections that follow.

PRINTER_EVENT_ADD_CONNECTION

The print subsystem calls DrvPrinterEvent with this event after a successful call to the Win32 AddPrinterConnection function. The driver should store connection settings in the HKEY_CURRENT_USER key of the registry, because printer connections are stored on a per-user basis. Thus, when a user with a floating profile logs into other machines, the connection floats too. Because printer connections can float, DrvPrinterEvent is not called from any machines that a user subsequently logs into after establishing a printer connection on their current machine.

The string to which pPrinterName points always identifies a remote printer for this DriverEvent. The user typically does not have administrative privileges on the remote server.

DrvPrinterEvent is called in the context of the calling application for this event; the calling application is usually the Printer Folder. As a result, the driver can display a user interface. The print subsystem ignores the value returned by the driver.

PRINTER_EVENT_DELETE_CONNECTION

The print subsystem calls DrvPrinterEvent with this event before calling the Win32 DeletePrinterConnection function. The driver should delete connection settings stored earlier in the HKEY_CURRENT_USER key of the registry during a previous call to this function with a DriverEvent of PRINTER_EVENT_ADD_CONNECTION, and perform any other clean-up.

The string to which pPrinterName points always identifies a remote printer for this DriverEvent. The user typically does not have administrative privileges on the remote server.

DrvPrinterEvent is called in the context of the calling application for this event; the calling application is usually the Printer Folder. As a result, the driver can display a user interface. The print subsystem ignores the value returned by the driver.

PRINTER_EVENT_INITIALIZE

The print subsystem calls DrvPrinterEvent with this event when a printer is created so that the driver can initialize its registry settings. It is also called when the Win32 SetPrinter function is called and the driver changes.

DrvPrinterEvent is called in the context of the spooler process for this event; consequently, the driver must not display a user interface. The spooler verifies that the user has administrative privileges before making the call, and calls the driver while impersonating the user.

A driver must implement this event.

PRINTER_EVENT_DELETE

The print subsystem calls DrvPrinterEvent with this event when a printer is being deleted so that the driver can delete its registry settings.

DrvPrinterEvent is called in the context of the spooler process for this event; consequently, the driver must not display a user interface. The spooler verifies that the user has administrative privileges before making the call, and calls the driver while impersonating the user.

PRINTER_EVENT_CACHE_REFRESH

The print subsystem calls DrvPrinterEvent with this event when the spooler is establishing a workstation cache or detects that a change to the cache has occurred. The driver can update any private cache data, such as font files, at this time.

DrvPrinterEvent is called in the context of the spooler process for this event; consequently, the driver must not display a user interface. The print subsystem ignores the value returned by the driver.

PRINTER_EVENT_CACHE_DELETE

The print subsystem calls DrvPrinterEvent with this event while the spooler is deleting a cached printer. The driver should delete any privately cached data, such as font files, at this time.

DrvPrinterEvent is called in the context of the spooler process for this event; consequently, the driver must not display a user interface. The print subsystem ignores the value returned by the driver.