StartXpsPrintJob1 関数 (xpsprint.h)
[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 を返します。 有効な値を次の表に示しますが、これ以外にもあります。
リターン コード | 説明 |
---|---|
|
メソッドが成功しました。 |
|
printerName または xpsOMPackageTarget が NULL です。 |
|
新しい IXpsPrintJob オブジェクトを作成するのに十分なメモリがありません。 |
注釈
StartXpsPrintJob1 は非同期関数であるため、印刷スプーラーが印刷ジョブを作成または開始する前に を返すことができます。
StartXpsPrintJob1 が正常に返されるまで、xpsPrintJob と xpsOMPackageTarget で返されるインターフェイスを使用しないでください。
呼び出し元がデータの送信を開始した後、 progressEvent に渡されるイベントに通知される進行状況イベントを監視することをお勧めします。 イベントが通知されると、呼び出し元は IXpsPrintJob::GetJobStatus を呼び出して、印刷ジョブの現在の状態を取得する必要があります。
印刷ジョブが正常に終了したかどうかにかかわらず、 completionEvent で渡されるイベントは 1 回だけ通知されます。 データ損失を防ぐために、呼び出し元が完了イベントを監視し、完了イベントが通知されるまで、スレッドも印刷ジョブを作成したアプリケーションも終了しないようにすることをお勧めします。
ジョブの状態は、印刷スプーラーによって格納されたりキューに入されたりすることはありません。 ジョブ処理では、イベントが通知された後に状態が読み取られるのを待機しないため、アプリケーションが変更通知を受信してから IXpsPrintJob::GetJobStatus と呼ばれるまでの遅延に応じて、呼び出し元は状態の変更を見逃す可能性があります。 後続の通知を受信するには、アプリケーションが通知を受信した後に進行状況イベントをリセットする必要があります。
StartXpsPrintJob1 の呼び出しが失敗した場合、印刷スプーラーはジョブの状態を更新し、完了イベントと進行状況イベントを通知し、エラー コードを返します。 失敗した印刷ジョブの状態を取得するには、 IXpsPrintJob::GetJobStatus を呼び出します。
StartXpsPrintJob1 は、completionEvent と progressEvent で DuplicateHandle を呼び出して、それらがジョブの有効期間にわたって有効であることを確認します。 印刷スプーラーはイベントに重複するハンドルを使用しているため、呼び出し元はジョブの実行に影響を与えることなく、いつでもこれらのハンドルを閉じることができます。 ただし、呼び出し元がこれらのハンドルを閉じるのは、 completionEvent イベントが通知され、呼び出し元がそれを観察した後にのみ行うことをお勧めします。
要件
要件 | 値 |
---|---|
サポートされている最小のクライアント | 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 |