Share via

StartXpsPrintJob 関数 (xpsprint.h)

  • [アーティクル]

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

XPS ドキュメント ストリームのプリンターへの印刷を開始します。

構文

HRESULT StartXpsPrintJob(
  [in]  LPCWSTR            printerName,
  [in]  LPCWSTR            jobName,
  [in]  LPCWSTR            outputFileName,
  [in]  HANDLE             progressEvent,
  [in]  HANDLE             completionEvent,
  [in]  UINT8              *printablePagesOn,
  [in]  UINT32             printablePagesOnCount,
  [out] IXpsPrintJob       **xpsPrintJob,
  [out] IXpsPrintJobStream **documentStream,
  [out] IXpsPrintJobStream **printTicketStream
);

パラメーター

[in] printerName

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

[in] jobName

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

[in] outputFileName

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

[in] progressEvent

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

  • ジョブ ID が印刷ジョブに割り当てられている
  • ページの印刷が完了しました
  • 文書の印刷が完了しました
  • 印刷ジョブが取り消されたか、エラーが原因で終了しました
メモ このイベントは、アプリケーションが印刷ジョブへのデータの送信を開始するまで通知されません。
 

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

進行状況の通知が必要ない場合は、このパラメーターを NULL に設定できます。

[in] completionEvent

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

完了通知が必要ない場合は、このパラメーターを NULL に設定できます。

[in] printablePagesOn

パラメーターは、印刷するドキュメントのページのサブセットを指定する要素を持つ UINT8 配列を参照します。 次の表に示すように、各要素の値は、ページを印刷するかどうかを示します。

配列要素の値 意味
0
 ページを印刷しないでください。
0 以外
 ページを印刷します。
 

進行状況イベントは、印刷用に指定されたページに対してのみ通知されます。

配列内の要素は、XPS パッケージのすべてのドキュメントで、印刷用に指定されたすべてのページを表します。 たとえば、パッケージにそれぞれ 3 つのページがある 2 つのドキュメントが含まれている場合、次の表に示す配列は、ドキュメント 1 のページ 0 と 2、ドキュメント 2 のページ 0 と 2 の印刷を指定します。

要素インデックス 要素の値 印刷。 ドキュメント番号 ページ番号
5 1 はい 2 2
4 0 いいえ 2 1
3 1 はい 2 0
2 1 はい 1 2
1 0 いいえ 1 1
0 1 はい 1 0
 

printablePagesOn が NULL の場合、パッケージ内のすべてのページが印刷されます。

printablePagesOn にパッケージ内のページよりも多くの要素がある場合、余分な要素は無視されます。

配列の要素数が文書内のページ数よりも少ない場合は、配列の最後の配列要素の値が残りのページに適用されます。 このルールを使用すると、未処理の範囲や、大きな文書の数ページのみが印刷される範囲を簡単に指定できます。

[in] printablePagesOnCount

printablePagesOn によって参照される配列内の要素の数。 printablePagesOn が NULL の場合、このパラメーターは無視されます。

[out] xpsPrintJob

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

[out] documentStream

呼び出し元がこの印刷ジョブによって印刷される XPS ドキュメントを書き込む IXpsPrintJobStream インターフェイスへのポインター。

[out] printTicketStream

呼び出し元が、このジョブに関連付けるジョブ レベルの印刷チケットを書き込む際に使用する IXpsPrintJobStream インターフェイスへのポインター。 このパラメーターが NULL に設定されている場合、 documentStream に書き込まれた XPS ドキュメントの印刷チケット (存在する場合) が使用されます。

戻り値

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

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

注釈

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

xpsPrintJob、documentStream、および printTicketStream で返されるインターフェイスは、StartXpsPrintJob が正常に返されるまで使用しないでください。

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

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

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

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

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

documentStream および printTicketStream で返される IXpsPrintJobStream インターフェイスは、シークを許可しないが閉じることができる書き込み専用ストリームです。 呼び出し元は XPS ドキュメントを書き込み、チケットの内容をこれらのストリームに出力し、すべてのデータが書き込まれた後に Close を 呼び出します。 ストリームの Write メソッドの呼び出しはスレッド セーフです。ただし、このような呼び出しが異なるスレッドから行われた場合、期待される順序でストリームにコミットされる保証はありません。

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

要件

   
サポートされている最小のクライアント Windows 7 [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 R2 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー xpsprint.h
Library XpsPrint.lib
[DLL] XpsPrint.dll

関連項目

ドキュメント

StartXpsPrintJob1

XML Paper Specification