3.1.4.2.8 RpcAsyncUploadPrinterDriverPackage (Opnum 63)

  • Article

RpcAsyncUploadPrinterDriverPackage uploads a driver package so it can be installed with RpcAsyncInstallPrinterDriverFromPackage (section 3.1.4.2.7).

 HRESULT RpcAsyncUploadPrinterDriverPackage(
   [in] handle_t hRemoteBinding,
   [in, string, unique] const wchar_t* pszServer,
   [in, string] const wchar_t* pszInfPath,
   [in, string] const wchar_t* pszEnvironment,
   [in] DWORD dwFlags,
   [in, out, unique, size_is(*pcchDestInfPath)] 
     wchar_t* pszDestInfPath,
   [in, out] DWORD* pcchDestInfPath
 );

hRemoteBinding: An RPC explicit binding handle.

pszServer: A pointer to a string that specifies the name of the print server to which this method will upload the printer driver package.

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 be used to install the driver on a target system.<19> For rules governing path names, see [MS-RPRN] section 2.2.4.9.

The path specified by pszInfPath MUST be accessible by the server.<20>

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

dwFlags: A bitfield that specifies the options for uploading a driver package.

Value

Meaning

0x00000000

This method uploads the driver package that is named by the string pointed to by the pszInfPath parameter to the print server, but only if that driver package is not already present on the server.

UPDP_UPLOAD_ALWAYS

0x00000002

This method uploads the driver package files specified by the pszInfPath parameter even if the driver package is already present on the print server.

UPDP_CHECK_DRIVERSTORE

0x00000004

This method only checks the print server's driver store to see if the driver package specified by the pszInfPath parameter is already present on the print server. If the driver package is not present on the print server, this method returns ERROR_NOT_FOUND; otherwise, the method returns zero.

This flag is ignored if the UPDP_UPLOAD_ALWAYS flag is set.

All other bits are set to zero by the client and ignored by the server upon receipt.

pszDestInfPath: A pointer to a buffer that receives a string that specifies the full path of the directory to which the driver installation control file was copied. For rules governing path names, see [MS-RPRN] section 2.2.4.9.

The value of the string is ignored by the server upon input.

pcchDestInfPath: On input, this parameter is a pointer to a variable that specifies the size, in characters, of the buffer that is referenced by the pszDestInfPath parameter. The specified size is at least 260 characters.

On output, the variable to which this parameter points receives the size, in characters, of the path string. The path string includes the terminating null character that was written into the buffer referenced by the pszDestInfPath parameter.

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 MUST return 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 MUST return ERROR_INVALID_ENVIRONMENT.

  • The size specified by the variable pointed to by pcchDestInfPath is at least 260 characters; otherwise the server MUST return ERROR_INVALID_PARAMETER.

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 as follows:

  • If the dwFlags parameter is 0x00000000 and the driver package does not exist already in the server's driver store, upload the signed driver package to the driver store of the print server so that it can be installed with RpcAsyncInstallPrinterDriverFromPackage.

  • If the dwFlags parameter is 0x00000002, upload the signed driver package to the driver store of the print server, even if it already exists in the server's driver store, so that it can be installed with RpcAsyncInstallPrinterDriverFromPackage.

  • Return the driver store path name of the file that describes the printer driver in the buffer pointed to by the output parameter pszDestInfPath.<21>

  • Set the contents of the output parameter pcchDestInfPath to the size of the data in the buffer.

  • If the dwFlags parameter is 0x00000004, check whether the driver package already exists in the server's driver store. If the driver package exists, return zero; otherwise, return ERROR_FILE_NOT_FOUND.

  • Return a response that contains the specified output parameters and the status of the operation.

If the operation is successful, the server MUST upload the driver package into the system driver store before returning the response.