StartXpsPrintJob1 関数 (xpsprint.h)

[アーティクル]
08/28/2023

[StartXpsPrintJob1 はサポートされていないため、今後変更または使用できない場合があります。 ]

XPS ドキュメントコンテンツをプリンターに送信するための印刷ジョブを作成します。この関数は、 StartXpsPrintJob よりも効率的な印刷パスを作成します。

構文

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
);

パラメーター

[in] printerName

このジョブが関連付けられるプリンターの名前。

[in, optional] jobName

このジョブに関連付けるユーザー指定のジョブ名。ジョブに個別のユーザー指定名が必要ない場合は、このパラメーターを NULL に 設定できます。

[in, optional] outputFileName

このジョブの出力をリダイレクトするファイルまたはポートのファイル名。この値を設定すると、印刷ジョブの出力が指定したファイルまたはポートに転送されます。 printerName で指定されたプリンターに印刷ジョブを送信するには、このパラメーターを NULL に設定する必要があります。

[in, optional] progressEvent

次のいずれかの印刷ジョブが変更されたときに通知されるイベントハンドル。

ジョブ ID が印刷ジョブに割り当てられている
ページの印刷が完了しました
文書の印刷が完了しました
印刷ジョブが取り消されたか、エラーが原因で終了しました

メモこのイベントは、アプリケーションが印刷ジョブへのデータの送信を開始するまで通知されません。

XPS Print API は、呼び出し元の責任であるこのイベントをリセットしません。

進行状況について通知を受け取らない場合は、このパラメーターを NULL に設定します。

[in, optional] completionEvent

印刷ジョブの終了時に通知されるイベントハンドル。このイベントは、 StartXpsPrintJob1 呼び出しごとに 1 回だけ通知されます。 XPS Print API は、呼び出し元の責任であるこのイベントをリセットしません。

完了について通知を受け取らない場合は、このパラメーターを NULL に設定します。

[out, optional] xpsPrintJob

StartXpsPrintJob1 が作成した印刷ジョブを表す IXpsPrintJob インターフェイスへのポインター。印刷ジョブの状態を取得したり、取り消したりするには、 IXpsPrintJob インターフェイスを使用します。必要がない場合は、このパラメーターを NULL に 設定します。

[out] printContentReceiver

この関数が作成した IXpsOMPackageTarget インターフェイスへのポインター。このパラメーターは必須であり、 NULL に設定することはできません。

この関数が作成した印刷ジョブにドキュメントコンテンツを送信するには、xpsOMPackageTarget で返される IXpsOMPackageTarget インターフェイスの CreateXpsOMPackageWriter メソッドを呼び出して作成する IXpsOMPackageWriter インターフェイスを使用します。

戻り値

このメソッドは HRESULT を返します。有効な値を次の表に示しますが、これ以外にもあります。

リターンコード	説明
S_OK	メソッドが成功しました。
E_POINTER	printerName または xpsOMPackageTarget が NULL です。
E_OUTOFMEMORY	新しい IXpsPrintJob オブジェクトを作成するのに十分なメモリがありません。

注釈

StartXpsPrintJob1 は非同期関数であるため、印刷スプーラーが印刷ジョブを作成または開始する前にを返すことができます。

StartXpsPrintJob1 が正常に返されるまで、xpsPrintJob と xpsOMPackageTarget で返されるインターフェイスを使用しないでください。

呼び出し元がデータの送信を開始した後、 progressEvent に渡されるイベントに通知される進行状況イベントを監視することをお勧めします。イベントが通知されると、呼び出し元は IXpsPrintJob::GetJobStatus を呼び出して、印刷ジョブの現在の状態を取得する必要があります。

印刷ジョブが正常に終了したかどうかにかかわらず、 completionEvent で渡されるイベントは 1 回だけ通知されます。データ損失を防ぐために、呼び出し元が完了イベントを監視し、完了イベントが通知されるまで、スレッドも印刷ジョブを作成したアプリケーションも終了しないようにすることをお勧めします。

ジョブの状態は、印刷スプーラーによって格納されたりキューに入されたりすることはありません。ジョブ処理では、イベントが通知された後に状態が読み取られるのを待機しないため、アプリケーションが変更通知を受信してから IXpsPrintJob::GetJobStatus と呼ばれるまでの遅延に応じて、呼び出し元は状態の変更を見逃す可能性があります。後続の通知を受信するには、アプリケーションが通知を受信した後に進行状況イベントをリセットする必要があります。

StartXpsPrintJob1 の呼び出しが失敗した場合、印刷スプーラーはジョブの状態を更新し、完了イベントと進行状況イベントを通知し、エラーコードを返します。失敗した印刷ジョブの状態を取得するには、 IXpsPrintJob::GetJobStatus を呼び出します。

StartXpsPrintJob1 は、completionEvent と progressEvent で DuplicateHandle を呼び出して、それらがジョブの有効期間にわたって有効であることを確認します。印刷スプーラーはイベントに重複するハンドルを使用しているため、呼び出し元はジョブの実行に影響を与えることなく、いつでもこれらのハンドルを閉じることができます。ただし、呼び出し元がこれらのハンドルを閉じるのは、 completionEvent イベントが通知され、呼び出し元がそれを観察した後にのみ行うことをお勧めします。

メモアプリケーションがファイルに出力する場合、アプリケーションは、ファイルへの印刷操作のために outputFileName パラメーターを渡す値を指定する必要があります。 FILE: ポートに出力するドライバーを使用するプリンターに印刷するには、呼び出し元が共通のファイルダイアログボックスを表示してユーザーからファイル名を取得する必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows 7 と SP1、Windows Vista、および Windows Vista のプラットフォーム更新プログラムの補足 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 R2 SP1、Windows Server 2008、および Windows Server 2008 のプラットフォーム更新プログラムの補足 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	xpsprint.h
Library	XpsPrint.lib
[DLL]	XpsPrint.dll

StartXpsPrintJob1 関数 (xpsprint.h)

構文

パラメーター

戻り値

注釈

要件

関連項目

フィードバック

フィードバック

その他のリソース