3.1.4.4.8 RpcAddPrinterDriverEx (Opnum 89)

  • Article

RpcAddPrinterDriverEx installs a printer driver on the print server.<329> This method performs a function similar to RpcAddPrinterDriver (section 3.1.4.4.1) and is also used to specify options that permit printer driver upgrade, printer driver downgrade, copying of newer files only, and copying of all files regardless of their time stamps.

 DWORD RpcAddPrinterDriverEx(
   [in, string, unique] STRING_HANDLE pName,
   [in] DRIVER_CONTAINER* pDriverContainer,
   [in] DWORD dwFileCopyFlags
 );

pName: A string that conforms to the parameter specification in Print Server Name Parameters (section 3.1.4.1.4).

pDriverContainer: A pointer to a DRIVER_CONTAINER structure (section 2.2.1.2.3) that MUST conform to the specification in DRIVER_CONTAINER parameters (section 3.1.4.1.8.3).

The Level member of the DRIVER_CONTAINER refers to the level of driver information structure, as follows:

Value

Description

0x00000002

DRIVER_INFO_2 (section 2.2.1.5.2).

0x00000003

RPC_DRIVER_INFO_3 (section 2.2.1.5.3).

0x00000004

RPC_DRIVER_INFO_4 (section 2.2.1.5.4).

0x00000006

RPC_DRIVER_INFO_6 (section 2.2.1.5.5).

0x00000008

RPC_DRIVER_INFO_8 (section 2.2.1.5.6).

dwFileCopyFlags: A bit field that specifies options for copying replacement printer driver files. The value of this parameter is a combination of flags from the following tables.

Exactly one of the following flags MUST be specified:

Name/value

Description

APD_STRICT_UPGRADE

0x00000001

Add the replacement printer driver only if none of the files of the replacement driver are older than any corresponding files of the currently installed driver.

APD_STRICT_DOWNGRADE

0x00000002

Add the replacement printer driver only if none of the files of the currently installed driver are older than any corresponding files of the replacement driver.

APD_COPY_ALL_FILES

0x00000004

Add the printer driver and copy all the files in the driver directory. File time stamps MUST be ignored.

APD_COPY_NEW_FILES

0x00000008

Add the printer driver and copy the files in the driver directory that are newer than any of the corresponding files that are currently in use.

Zero or more of the following flags can be specified.

Name/value

Description

APD_COPY_FROM_DIRECTORY

0x00000010

Add the printer driver by using the fully qualified file names that are specified in the _DRIVER_INFO_6 structure. If this flag is specified, one of the other copy flags in this bit field MUST be specified.

APD_DONT_COPY_FILES_TO_CLUSTER

0x00001000

When adding a printer driver to a print server cluster, do not copy the driver files to the shared cluster disk.

APD_COPY_TO_ALL_SPOOLERS

0x00002000

Add the printer driver to cluster spooler servers.

APD_INSTALL_WARNED_DRIVER

0x00008000

Add the printer driver, even if it is in the server's List of Warned Printer Drivers (section 3.1.1).<330>

APD_RETURN_BLOCKING_STATUS_CODE

0x00010000

Specifies the implementation-specific error code to return if the printer driver is blocked from installation by server policy.<331>

Return Values: This method MUST return zero (ERROR_SUCCESS) to indicate successful completion or a nonzero Windows error code to indicate failure [MS-ERREF].

Upon receiving this message, the server MUST validate parameters as follows:

  • Perform the validation steps that are specified in Print Server Name Parameters (section 3.1.4.1.4).

  • Perform the validation steps that are specified in DRIVER_CONTAINER Parameters.

  • Verify that dwFileCopyFlags contains a valid flag value or set of values as specified in the dwFileCopyFlags parameter definition above. If this verification fails, return ERROR_INVALID_PARAMETER.

  • Additional validation MAY<332> be performed.

In addition, print servers SHOULD<333> validate parameters as follows:

  • Validate that the cVersion member of the DRIVER_INFO structure contained in the DRIVER_CONTAINER pointed to by the pDriverContainer is strictly less than 0x00000004. If this validation fails, return ERROR_PRINTER_DRIVER_BLOCKED.

  • Validate that the pEnvironment member of the DRIVER_INFO structure contained in the DRIVER_CONTAINER pointed to by the pDriverContainer parameter is not "Windows ARM". If this validation fails, return ERROR_NOT_SUPPORTED.

If the installation requested by the print client is a printer driver upgrade, print servers SHOULD perform the following additional validation steps:

  • Validate that the currently installed printer driver is not a class printer driver.

  • Validate that if the currently installed printer driver has a driver version of 0x00000004, the currently installed printer driver does not have a newer driver date, or if the driver dates are the same, that the currently installed printer driver does not have a newer manufacturer-provided driver version number.

  • Validate that if the currently installed printer driver has a driver version of 0x00000004, there are no printers on the print server that are shared and also use the currently installed printer driver.

If this validation fails, the print server MUST return ERROR_PRINTER_DRIVER_BLOCKED.

If parameter validation fails, the server MUST fail the operation immediately and return a nonzero error response to the client. Otherwise, the server MUST process the message and compose a response to the client as follows:

  • Copy the printer driver files to their destinations, in compliance with the settings specified by the value of the dwFileCopyFlags parameter.

  • Create the printer driver object, using an implementation-specific mechanism to determine the Boolean values of each of the attributes of the printer driver.

  • If any clients have registered for notification of server object changes, a notification MUST be broadcast to them.

  • Return the status of the operation.