StartXpsPrintJob1 function (xpsprint.h)

[StartXpsPrintJob1 is not supported and may be altered or unavailable in the future. ]

Creates a print job for sending XPS document content to a printer.This function creates a more efficient print path than StartXpsPrintJob.

Syntax

HRESULT StartXpsPrintJob1(
  [in]            LPCWSTR             printerName,
  [in, optional]  LPCWSTR             jobName,
  [in, optional]  LPCWSTR             outputFileName,
  [in, optional]  HANDLE              progressEvent,
  [in, optional]  HANDLE              completionEvent,
  [out, optional] IXpsPrintJob        **xpsPrintJob,
  [out]           IXpsOMPackageTarget **printContentReceiver
);

Parameters

[in] printerName

The name of the printer with which this job will be associated.

[in, optional] jobName

A user-specified job name to be associated with this job. You can set this parameter to NULL if the job does not require a separate, user-specified name.

[in, optional] outputFileName

The file name of the file or port into which the output of this job is to be redirected. Setting this value will cause the output of the print job to be directed to the specified file or port. To send the print job to the printer that is specified by printerName, you must set this parameter to NULL.

[in, optional] progressEvent

An event handle that is signaled when one of the following print job changes occur:

• A job ID is assigned to the print job
• Printing of a page has finished
• Printing of a document has finished
• The print job has been canceled or has ended because of an error

The XPS Print API does not reset this event—that is the caller's responsibility.

Set this parameter to NULL if you do not want to be notified about progress.

[in, optional] completionEvent

An event handle that is signaled when the print job finishes. This event is guaranteed to be signaled exactly once per StartXpsPrintJob1 call. The XPS Print API does not reset this event—that is the caller's responsibility.

Set this parameter to NULL if do not want to be notified about completion.

[out, optional] xpsPrintJob

A pointer to the IXpsPrintJob interface that represents the print job that StartXpsPrintJob1 created. To get the status of the print job or to cancel it, use the IXpsPrintJob interface. Set this parameter to NULL if you do not need it.

[out] printContentReceiver

A pointer to the IXpsOMPackageTarget interface that this function created. This parameter is required and you cannot set it to NULL.

To send document content to the print job that this function created, use the IXpsOMPackageWriter interface that you create by calling the CreateXpsOMPackageWriter method of the IXpsOMPackageTarget interface returned in xpsOMPackageTarget.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

Remarks

StartXpsPrintJob1 is an asynchronous function, and therefore it can return before the print spooler creates or starts a print job.

Do not use the interfaces that are returned in xpsPrintJob and xpsOMPackageTarget until StartXpsPrintJob1 has returned successfully.

After the caller starts sending data, it is a good programming practice to monitor the progress events that are signaled to the event that is passed in progressEvent. When the event is signaled, the caller must call IXpsPrintJob::GetJobStatus to get the current status of the print job.

When the print job finishes, whether successfully or not, the event that is passed in completionEvent is signaled only once. To prevent data loss, it is a good programming practice for the caller to monitor the completion event and ensure that neither the thread nor the application that created the print job are terminated until the completion event has been signaled.

Job states are neither stored nor queued by the print spooler. Because job processing does not wait for the status to be read after events are signaled, the caller might miss some state changes, depending on the delay between the time the application received the change notification and the time it called IXpsPrintJob::GetJobStatus. To receive subsequent notifications, the application must reset the progress event after it has received the notification.

If a call to StartXpsPrintJob1 fails, the print spooler updates the job status, signals the completion and progress events, and returns an error code. To get the status of the failed print job, call IXpsPrintJob::GetJobStatus.

StartXpsPrintJob1 calls DuplicateHandle on completionEvent and progressEvent to ensure that they remain valid for the lifetime of the job. Because the print spooler is using a duplicate handle for the events, the caller can close these handles at any point without affecting job execution. However, we recommend for the caller to close these handles only after the completionEvent event has been signaled and the caller observed it.

Requirements

See also

Documents

IXpsOMPackageTarget

IXpsOMPackageWriter

XML Paper Specification