3.1.4.4.10 RpcGetPrinterDriverPackagePath (Opnum 104)

  • Article

RpcGetPrinterDriverPackagePath gets the path to the specified printer driver package.<349>

 HRESULT RpcGetPrinterDriverPackagePath(
   [in, string, unique] STRING_HANDLE pszServer,
   [in, string] const wchar_t* pszEnvironment,
   [in, string, unique] const wchar_t* pszLanguage,
   [in, string] const wchar_t* pszPackageID,
   [in, out, unique, size_is(cchDriverPackageCab)] 
     wchar_t* pszDriverPackageCab,
   [in] DWORD cchDriverPackageCab,
   [out] LPDWORD pcchRequiredSize
 );

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 driver package path MUST be returned. For rules governing environment names, see section 2.2.4.4.

pszLanguage: An optional pointer to a string that specifies the language for which the driver package path MUST<350> be returned.

pszPackageID: A pointer to a string that specifies the package name. The package name MUST be obtained by calling RpcGetCorePrinterDrivers.

pszDriverPackageCab: This parameter is a pointer to a buffer that receives a string that specifies the path name of the driver package file.<351> For rules governing path names, see section 2.2.4.9. pszDriverPackageCab MUST NOT be NULL unless cchDriverPackageCab is zero.

cchDriverPackageCab: This parameter specifies the size, in characters, of the buffer that is referenced by the pszDriverPackageCab parameter. The value of this parameter MAY<352> be zero.

pcchRequiredSize: A pointer to a variable that MUST receive the required size of the buffer that is pointed to by the pszDriverPackageCab parameter.

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.

  • The value of the pszPackageID parameter MUST NOT be NULL; otherwise the server MUST return ERROR_INVALID_PARAMETER.

  • The value of the pcchRequiredSize parameter MUST NOT be NULL; otherwise the server MUST return ERROR_INVALID_PARAMETER.

  • The size specified by cchDriverPackageCab MUST be sufficient to hold the path name of the driver package file; otherwise the server MUST calculate the required number of characters and write this number to the variable pointed to by the pcchRequiredSize output parameter, and return ERROR_INSUFFICIENT_BUFFER.

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:

  • Searching for the driver package cab file for the specified pszPackageID.

  • Returning the driver package cab path for package ID in the output parameter pszDriverPackageCab.

  • Setting the contents of the parameter pcchRequiredSize to the size of the string buffer required to hold the driver package cab.

  • 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 driver package cabs as part of processing this method call.