Export (0) Print
Expand All

AddPrinterDriverEx function

The AddPrinterDriverEx function installs a local or remote printer driver and links the configuration, data, and driver files. Besides having the capabilities of AddPrinterDriver, it also has options that permit strict upgrade, strict downgrade, copying of newer files only, and copying of all files (regardless of file time stamps).

Syntax


BOOL AddPrinterDriverEx(
  _In_     LPTSTR pName,
  _In_     DWORD Level,
  _Inout_  LPBYTE pDriverInfo,
  _In_     DWORD dwFileCopyFlags
);

Parameters

pName [in]

A pointer to a null-terminated string that specifies the name of the server on which the driver should be installed. If this parameter is NULL, the function installs the driver on the local computer.

Level [in]

The version of the structure to which pDriverInfo points. This value can be 2, 3, 4, 6, or 8.

pDriverInfo [in, out]

A pointer to a structure containing printer driver information. It can be one of the following.

Value of LevelDRIVER_INFO_* Structure
2

DRIVER_INFO_2

3

DRIVER_INFO_3

4

DRIVER_INFO_4

6

DRIVER_INFO_6

8

DRIVER_INFO_8

 

If the pEnvironment member of the structure pointed to by pDriverInfo is NULL, the function uses the current environment of the caller/client, not the environment of the destination/server.

dwFileCopyFlags [in]

The options for copying the driver files. This parameter can be one of the following values.

ValueMeaning
APD_COPY_ALL_FILES

Add the printer driver and copy all the files in the printer-driver directory. The file time stamps are ignored with this option.

APD_COPY_FROM_DIRECTORY

Add the printer driver using the fully qualified file names specified in the DRIVER_INFO_6 structure. This flag is ORed in conjunction with one of the other copy flags. If this flag is set, AddPrinterDriverEx will fail if the files do not exist where they are specified to exist by the DRIVER_INFO_6 structure. The files do not need to be copied to the system's printer-driver directory. See the Remarks.

Windows 2000:  This flag is not supported.

APD_COPY_NEW_FILES

Add the printer driver and copy the files in the printer-driver directory that are newer than any corresponding files that are currently in use. This flag emulates the behavior of AddPrinterDriver.

APD_STRICT_DOWNGRADE

Add the printer driver only if all the files in the printer-driver directory are older than any corresponding files currently in use.

APD_STRICT_UPGRADE

Add the printer driver only if all the files in the printer-driver directory are newer than any corresponding files currently in use.

 

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

If the printer driver is known to have problems working with the operating system, AddPrinterDriverEx will fail with one of the following error codes:

Error CodeMeaning
ERROR_PRINTER_DRIVER_BLOCKEDThe driver does not work on the operating system.
ERROR_PRINTER_DRIVER_WARNEDThe driver is unreliable on the operating system. However, if APD_INSTALL_WARNED_DRIVER is specified, the driver is installed and no warning is given.

 

For more information, see the Remarks.

Remarks

Note  This is a blocking or synchronous function and might not return immediately. How quickly this function returns depends on run-time factors such as network status, print server configuration, and printer driver implementation—factors that are difficult to predict when writing an application. Calling this function from a thread that manages interaction with the user interface could make the application appear to be unresponsive.

The caller must have the SeLoadDriverPrivilege.

Before calling the AddPrinterDriverEx function, all files required by the driver must be copied to the system's printer-driver directory. To retrieve the name of this directory, call the GetPrinterDriverDirectory function.

To determine which printer drivers are currently installed, call the EnumPrinterDrivers function.

If the printer driver has been successfully added, the function calls the DrvDriverEvent (DRIVER_EVENT_INITIALIZE, Level, DRIVER_INFO_*, lparam ) function to allow the driver to perform any initializations required during the installation of a printer driver. For more information about DrvDriverEvent, see the Microsoft Windows Driver Development Kit (DDK)

The driver should not use a UI call during the call to DrvDriverEvent. To do UI-related jobs, the installer should either use the VendorSetup entry in the printer's .inf file or, for Plug and Play devices, the installer can use a device-specific co-installer. For more information about VendorSetup, see the DDK.

The files that are referenced in the DRIVER_INFO_6 structure must be local to the machine from which the call is made. A file name can be a UNC name as long as the UNC name is the local machine.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winspool.h (include Windows.h)

Library

Winspool.lib

DLL

Winspool.drv

Unicode and ANSI names

AddPrinterDriverExW (Unicode) and AddPrinterDriverExA (ANSI)

See also

Printing
Print Spooler API Functions
AddPrinterDriver
DRIVER_INFO_2
DRIVER_INFO_3
DRIVER_INFO_4
DRIVER_INFO_6
DeletePrinterDriverEx
EnumPrinterDrivers
GetPrinterDriverDirectory

 

 

Community Additions

ADD
Show:
© 2014 Microsoft