Share via

3.1.4.2.7 RpcAsyncInstallPrinterDriverFromPackage (Opnum 62)

  • Article

RpcAsyncInstallPrinterDriverFromPackage installs a printer driver from a driver package.

 HRESULT RpcAsyncInstallPrinterDriverFromPackage(
   [in] handle_t hRemoteBinding,
   [in, string, unique] const wchar_t* pszServer,
   [in, string, unique] const wchar_t* pszInfPath,
   [in, string] const wchar_t* pszDriverName,
   [in, string] const wchar_t* pszEnvironment,
   [in] DWORD dwFlags
 );

hRemoteBinding: An RPC explicit binding handle.

pszServer: A pointer to a string that specifies the name of the print server on which to install the printer driver.

This string contains the server name that was used to create the hRemoteBinding parameter. For RPC bind handles, refer to [MS-RPCE]. For rules governing server names, refer to [MS-RPRN] section 2.2.4.16.

pszInfPath: A pointer to a string that specifies the path to a driver installation control file that specifies the printer driver.

This control file MAY<11> be used to install the driver on a target system. For rules governing path names, refer to [MS-RPRN] section 2.2.4.9.

pszDriverName: A pointer to a string that specifies the name of the printer driver.

pszEnvironment: A pointer to a string that specifies the environment name for which the printer driver is installed. For rules governing environment names, refer to [MS-RPRN] section 2.2.4.4.

dwFlags: A bitfield that specifies the options for installing printer driver files from a driver package.

Value

Meaning

0x00000000

Only the files that will not overwrite files with a newer version SHOULD be installed.

IPDFP_COPY_ALL_FILES

0x00000001

All files SHOULD be installed, even if doing so would overwrite some newer versions.

All other bits SHOULD be set to zero by the client and MUST be ignored by the server upon receipt.

Return Values: This method returns either an HRESULT success value ([MS-ERREF] section 2.1) or an HRESULT error value to indicate failure.

Exceptions Thrown: This method MUST NOT throw any exceptions other than those that are thrown by the underlying RPC protocol [MS-RPCE].

Parameter Validation Requirements: Upon receiving this method call, the server MUST validate parameters as follows:

  • The string pointed to by the pszInfPath parameter contains a valid path name; otherwise the server returns ERROR_INVALID PARAMETER.

  • The string pointed to by the pszEnvironment parameter specifies one of the supported environment names on this server for that type of driver; otherwise the server returns ERROR_INVALID_ENVIRONMENT.

The print server SHOULD<12> perform the following additional validation steps:

  • Validate that, if the printer driver specified by the client has a driver version of 0x00000004 (cVersion in [MS-RPRN] section 2.2.1.3.1), the driver package specified by the printer client contains exactly one printer driver manifest for the printer driver and the printer driver manifest conforms to the implementation-specific rules governing the format of printer driver manifests; otherwise, the server returns ERROR_INVALID_PRINTER_DRIVER_MANIFEST.

  • Validate that, if the printer driver specified by the client is a derived printer driver, either the class printer driver on which the derived printer driver depends is already installed on the print server, or a driver package containing the class printer driver is installed in the print server's driver store, or the print server can locate a driver package containing the class printer driver through some other implementation-specific mechanism;<13> otherwise, the server returns ERROR_UNKNOWN_PRINTER_DRIVER. This HRESULT error code is constructed by using the HRESULT from WIN32 Error Code Macro ([MS-ERREF] section 2.1.2) on the 16-bit Win32 value for this error ([MS-ERREF] section 2.2).

  • Validate that any files referenced in the driver installation control file specified by the print client or in the printer driver manifest in the driver package specified by the print client are present on the print server; otherwise, the server returns ERROR_FILE_NOT_FOUND.

  • Validate that, if the printer driver specified by the client has a driver version of 0x00000003 (cVersion parameter in [MS-RPRN] section 2.2.1.3.1), the string pointed to by the pszEnvironment parameter is not "Windows ARM"; otherwise, the server returns ERROR_NOT_SUPPORTED.

If the installation requested by the print client is a printer driver upgrade and the new printer driver has a driver version of 0x00000003, the print server 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, 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 returns ERROR_PRINTER_DRIVER_BLOCKED.<14>

If the installation requested by the print client is a printer driver upgrade and the new printer driver has a driver version of 0x00000004, the print server SHOULD perform the following additional validation steps:

  • Validate that, if the currently installed printer driver is a class printer driver, the new printer driver is also a class printer driver.

  • Validate that, unless the currently installed printer driver is not a class printer driver and the new printer driver is a class printer driver, the currently installed printer driver does not have a newer driver date than the new printer driver, 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 there are one or more printers on the print server that are shared and also use the currently installed printer driver, the new printer driver does not indicate that printers using that printer driver cannot be shared.

If this validation fails, the print server returns S_FALSE.<15>

If parameter validation fails, the server MUST fail the operation immediately and return a nonzero error response to the client.

For general information about driver installation control files, see [MSDN-INFS]. For printer-specific information about printer-driver installation control files, see [MSDN-PRNINF].

Processing and Response Requirements: If parameter validation succeeds, the server MUST process the method call by:

  • Installing a printer driver from the driver package that is located in the print server's driver store, using an implementation-specific mechanism to determine the Boolean values of each of the attributes of the printer driver object.<16> If the printer driver is a derived printer driver and the class printer driver on which the derived printer driver depends is not currently installed, the print server MUST first install the class printer driver. If a driver package containing the class printer driver on which the derived printer driver depends is also located in the print server's driver store, the print server SHOULD install the class printer driver from the driver package that contains it. If a driver package containing the class printer driver is not located in the print server's driver store but the print server can locate a driver package containing the class printer driver through some other implementation-specific mechanism,<17> the print server SHOULD install the driver package containing the class printer driver and then SHOULD install the class printer driver from that driver package.<18>

  • Returning the status of the operation.

If the operation is successful, the server MUST install the printer driver from the driver package before returning the response.