3.1.4.4.9 RpcGetCorePrinterDrivers (Opnum 102)

  • Article

RpcGetCorePrinterDrivers gets the GUIDs, versions, and publish dates of the specified core printer drivers, and the paths to their packages.<347>

 HRESULT RpcGetCorePrinterDrivers(
   [in, string, unique] STRING_HANDLE pszServer,
   [in, string] const wchar_t* pszEnvironment,
   [in] DWORD cchCoreDrivers,
   [in, size_is(cchCoreDrivers)] const wchar_t* pszzCoreDriverDependencies,
   [in] DWORD cCorePrinterDrivers,
   [out, size_is(cCorePrinterDrivers)] 
     CORE_PRINTER_DRIVER* pCorePrinterDrivers
 );

pszServer: A STRING_HANDLE (section 2.2.1.1.7) for a server object. This parameter MUST adhere to the specification in Print Server Name Parameters (section 3.1.4.1.4).

pszEnvironment: A pointer to a string that specifies the environment name for which the core printer driver information is returned. For rules governing environment names and product behaviors, see section 2.2.4.4.

cchCoreDrivers: The size, in bytes, of the buffer that is referenced by the pszzCoreDriverDependencies parameter.

pszzCoreDriverDependencies: A pointer to a multisz that contains a list of IDs of the core printer drivers to be retrieved.<348>

A print client SHOULD obtain this list of IDs as follows:

  1. Call RpcGetPrinterDriver (section 3.1.4.4.3) with a Level parameter value of 0x00000008.

  2. A pointer to a _DRIVER_INFO_8 custom-marshaled structure (section 2.2.2.4.8) is returned in the pDriver parameter.

  3. In the _DRIVER_INFO_8 structure, the szzCoreDependenciesOffset member contains an offset to a multisz that contains the list of IDs.

cCorePrinterDrivers: The count of CORE_PRINTER_DRIVER (section 2.2.2.13) structures that are contained in the buffer that is pointed to by the pCorePrinterDrivers parameter. It MUST equal the number of IDs that are specified in the multisz that is pointed to by the pszzCoreDriverDependencies parameter.

pCorePrinterDrivers: A pointer to a buffer that receives an array of CORE_PRINTER_DRIVER structures.

Return Values: This method MUST return zero or an HRESULT success value ([MS-ERREF] section 2.1) to indicate successful completion 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 pszEnvironment parameter specifies one of the supported environment names on the server for that type of driver; otherwise the server MUST return ERROR_INVALID_ENVIRONMENT.

  • cCorePrinterDrivers MUST be equal to or greater than 1; otherwise the server MUST return ERROR_INVALID_PARAMETER.

  • cCorePrinterDrivers MUST be equal to the number of GUIDs present in pszzCoreDriverDependencies; otherwise the server MUST return ERROR_INVALID_PARAMETER.

  • The pCorePrinterDrivers parameter MUST NOT be NULL.

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

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

  • Enumerating the CORE_PRINTER_DRIVER structures in the system.

  • Populating each CORE_PRINTER_DRIVER structure in the supplied buffer with information about the core printer driver.

  • Returning a response that MUST contain the output parameters mentioned above and the status of the operation.

The server MUST NOT change the List of Core Printer Drivers as part of processing this method call.