ホーム › Graphics.Printing.PrintTicket › PTMergeAndValidatePrintTicket

PTMergeAndValidatePrintTicket

関数

プリントチケットを結合し妥当性を検証する。

DLLprntvpt.dll呼出規約winapi対応OSWindows XP 以降

シグネチャ

// prntvpt.dll
#include <windows.h>

HRESULT PTMergeAndValidatePrintTicket(
    HPTPROVIDER hProvider,
    IStream* pBaseTicket,
    IStream* pDeltaTicket,   // optional
    EPrintTicketScope scope,
    IStream* pResultTicket,
    LPWSTR* pbstrErrorMessage   // optional
);

パラメーター

名前	型	方向	説明
hProvider	HPTPROVIDER	in	開いている印刷チケットプロバイダーへのハンドル。このハンドルは PTOpenProvider 関数または PTOpenProviderEx 関数によって返されます。
pBaseTicket	IStream*	in	印刷チケットへのポインター。ストリームのシーク位置は、印刷チケットの内容の先頭にある必要があります。メモ PTMergeAndValidatePrintTicket は、マージの前にベースチケットを Print Schema Framework に照らして検証します。
pDeltaTicket	IStream*	inoptional	印刷チケットへのポインター。ストリームのシーク位置は、印刷チケットの内容の先頭にある必要があります。このパラメーターには NULL を渡すことができます。「解説」を参照してください。メモ PTMergeAndValidatePrintTicket は、マージの前にデルタチケットを Print Schema Framework に照らして検証します。
scope	EPrintTicketScope	in	pDeltaTicket と pResultTicket のスコープが単一ページか、ドキュメント全体か、印刷ジョブ内のすべてのドキュメントかを指定する値。「解説」を参照してください。
pResultTicket	IStream*	in	実行可能なマージ済みチケットの書き込み先となるストリームへのポインター。シーク位置は印刷チケットの末尾になります。「解説」を参照してください。
pbstrErrorMessage	LPWSTR*	outoptional	pBaseTicket または pDeltaTicket について、無効な点があればその内容を示す文字列へのポインター。両方とも有効な場合、これは NULL になります。実行可能性に関する問題は pbstrErrorMessage には報告されません。

戻り値の型: HRESULT

公式ドキュメント

2 つの印刷チケットをマージし、有効かつ実行可能な印刷チケットを返します。

戻り値

マージされたチケットの設定とプリンターの機能との間に競合がなく、操作が成功した場合、HRESULT は S_PT_NO_CONFLICT になります。

操作は成功したものの、プリンターがサポートしていない機能が要求されていたためにマージされたチケットの 1 つ以上の設定を変更する必要があった場合、HRESULT は S_PT_CONFLICT_RESOLVED になります。「解説」を参照してください。

hProvider が別のスレッドで開かれていた場合、HRESULT は E_INVALIDARG になります。

pBaseTicket が無効な場合、HRESULT は E_PRINTTICKET_FORMAT になります。

pDeltaTicket が無効な場合、HRESULT は E_DELTA_PRINTTICKET_FORMAT になります。

それ以外の場合は、その他のエラーコードが HRESULT として返されます。COM エラーコードの詳細については、Error Handling を参照してください。

解説(Remarks)

メモこれはブロッキング関数 (同期関数) であり、すぐに戻らない場合があります。この関数が戻るまでの時間は、ネットワークの状態、印刷サーバーの構成、プリンタードライバーの実装など、アプリケーションの作成時には予測が困難な実行時の要因に依存します。ユーザーインターフェイスとの対話を管理するスレッドからこの関数を呼び出すと、アプリケーションが応答していないように見えることがあります。

hProvider は、この関数で使用するスレッドと同じスレッドで開かれたハンドルである必要があります。

この関数は 2 つの方法で検証を行います。まず、両方の入力チケットを Print Schema Framework に照らして検証し、エラーを pbstrErrorMessage に報告します。次に、マージされた印刷チケットが実行可能かどうかをプリンタードライバーで確認します。マージされたチケットがプリンターのサポートしていない機能を要求している場合、実行できない設定は置き換えられ、どの設定で代替するかはプリンタードライバーが決定します。通常、プリンタードライバーはユーザーの既定の印刷チケットの設定を使用します。プリンタードライバーが代替値の取得元として pBaseTicket が指す印刷チケットを使用しない場合、pResultTicket は 2 つの入力印刷チケットのいずれとも異なる設定になる可能性があります。

通常、pBaseTicket にはジョブ、ドキュメント、ページの各設定が一通り含まれます。通常は、ユーザーの既定またはデバイスの既定の印刷チケットが pBaseTicket に使用されます。

pDeltaTicket が NULL の場合、このメソッドは pBaseTicket を検証し、その実行可能性を確認したうえで、必要に応じて変更を加えたものを pResultTicket が指すストリームに返します。

scope の範囲外にある pDeltaTicket の値は無視されます。たとえば、スコープが単一ページのみの場合、ジョブ全体の設定とドキュメント全体の設定は無視されます。ジョブスコープにはドキュメントスコープとページスコープが含まれます。ドキュメントスコープにはページスコープが含まれます。

scope の範囲外にある設定は pResultTicket には含まれません。

この関数が値を返すとき、pResultTicket のシーク位置は印刷チケットの内容の末尾にあります。データを読み取る前にシーク位置をリセットするのは、呼び出し元の役割です。

関数が戻ったときに pbstrErrorMessage が NULL でない場合、呼び出し元は SysFreeString でその文字列を解放する必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// prntvpt.dll
#include <windows.h>

HRESULT PTMergeAndValidatePrintTicket(
    HPTPROVIDER hProvider,
    IStream* pBaseTicket,
    IStream* pDeltaTicket,   // optional
    EPrintTicketScope scope,
    IStream* pResultTicket,
    LPWSTR* pbstrErrorMessage   // optional
);

[DllImport("prntvpt.dll", ExactSpelling = true)]
static extern int PTMergeAndValidatePrintTicket(
    IntPtr hProvider,   // HPTPROVIDER
    IntPtr pBaseTicket,   // IStream*
    IntPtr pDeltaTicket,   // IStream* optional
    int scope,   // EPrintTicketScope
    IntPtr pResultTicket,   // IStream*
    IntPtr pbstrErrorMessage   // LPWSTR* optional, out
);

<DllImport("prntvpt.dll", ExactSpelling:=True)>
Public Shared Function PTMergeAndValidatePrintTicket(
    hProvider As IntPtr,   ' HPTPROVIDER
    pBaseTicket As IntPtr,   ' IStream*
    pDeltaTicket As IntPtr,   ' IStream* optional
    scope As Integer,   ' EPrintTicketScope
    pResultTicket As IntPtr,   ' IStream*
    pbstrErrorMessage As IntPtr   ' LPWSTR* optional, out
) As Integer
End Function

' hProvider : HPTPROVIDER
' pBaseTicket : IStream*
' pDeltaTicket : IStream* optional
' scope : EPrintTicketScope
' pResultTicket : IStream*
' pbstrErrorMessage : LPWSTR* optional, out
Declare PtrSafe Function PTMergeAndValidatePrintTicket Lib "prntvpt" ( _
    ByVal hProvider As LongPtr, _
    ByVal pBaseTicket As LongPtr, _
    ByVal pDeltaTicket As LongPtr, _
    ByVal scope As Long, _
    ByVal pResultTicket As LongPtr, _
    ByVal pbstrErrorMessage As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

PTMergeAndValidatePrintTicket = ctypes.windll.prntvpt.PTMergeAndValidatePrintTicket
PTMergeAndValidatePrintTicket.restype = ctypes.c_int
PTMergeAndValidatePrintTicket.argtypes = [
    wintypes.HANDLE,  # hProvider : HPTPROVIDER
    ctypes.c_void_p,  # pBaseTicket : IStream*
    ctypes.c_void_p,  # pDeltaTicket : IStream* optional
    ctypes.c_int,  # scope : EPrintTicketScope
    ctypes.c_void_p,  # pResultTicket : IStream*
    ctypes.c_void_p,  # pbstrErrorMessage : LPWSTR* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('prntvpt.dll')
PTMergeAndValidatePrintTicket = Fiddle::Function.new(
  lib['PTMergeAndValidatePrintTicket'],
  [
    Fiddle::TYPE_VOIDP,  # hProvider : HPTPROVIDER
    Fiddle::TYPE_VOIDP,  # pBaseTicket : IStream*
    Fiddle::TYPE_VOIDP,  # pDeltaTicket : IStream* optional
    Fiddle::TYPE_INT,  # scope : EPrintTicketScope
    Fiddle::TYPE_VOIDP,  # pResultTicket : IStream*
    Fiddle::TYPE_VOIDP,  # pbstrErrorMessage : LPWSTR* optional, out
  ],
  Fiddle::TYPE_INT)

#[link(name = "prntvpt")]
extern "system" {
    fn PTMergeAndValidatePrintTicket(
        hProvider: *mut core::ffi::c_void,  // HPTPROVIDER
        pBaseTicket: *mut core::ffi::c_void,  // IStream*
        pDeltaTicket: *mut core::ffi::c_void,  // IStream* optional
        scope: i32,  // EPrintTicketScope
        pResultTicket: *mut core::ffi::c_void,  // IStream*
        pbstrErrorMessage: *mut *mut u16  // LPWSTR* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("prntvpt.dll")]
public static extern int PTMergeAndValidatePrintTicket(IntPtr hProvider, IntPtr pBaseTicket, IntPtr pDeltaTicket, int scope, IntPtr pResultTicket, IntPtr pbstrErrorMessage);
"@
$api = Add-Type -MemberDefinition $sig -Name 'prntvpt_PTMergeAndValidatePrintTicket' -Namespace Win32 -PassThru
# $api::PTMergeAndValidatePrintTicket(hProvider, pBaseTicket, pDeltaTicket, scope, pResultTicket, pbstrErrorMessage)

#uselib "prntvpt.dll"
#func global PTMergeAndValidatePrintTicket "PTMergeAndValidatePrintTicket" sptr, sptr, sptr, sptr, sptr, sptr
; PTMergeAndValidatePrintTicket hProvider, pBaseTicket, pDeltaTicket, scope, pResultTicket, varptr(pbstrErrorMessage)   ; 戻り値は stat
; hProvider : HPTPROVIDER -> "sptr"
; pBaseTicket : IStream* -> "sptr"
; pDeltaTicket : IStream* optional -> "sptr"
; scope : EPrintTicketScope -> "sptr"
; pResultTicket : IStream* -> "sptr"
; pbstrErrorMessage : LPWSTR* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "prntvpt.dll"
#cfunc global PTMergeAndValidatePrintTicket "PTMergeAndValidatePrintTicket" sptr, sptr, sptr, int, sptr, var
; res = PTMergeAndValidatePrintTicket(hProvider, pBaseTicket, pDeltaTicket, scope, pResultTicket, pbstrErrorMessage)
; hProvider : HPTPROVIDER -> "sptr"
; pBaseTicket : IStream* -> "sptr"
; pDeltaTicket : IStream* optional -> "sptr"
; scope : EPrintTicketScope -> "int"
; pResultTicket : IStream* -> "sptr"
; pbstrErrorMessage : LPWSTR* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "prntvpt.dll"
#cfunc global PTMergeAndValidatePrintTicket "PTMergeAndValidatePrintTicket" sptr, sptr, sptr, int, sptr, sptr
; res = PTMergeAndValidatePrintTicket(hProvider, pBaseTicket, pDeltaTicket, scope, pResultTicket, varptr(pbstrErrorMessage))
; hProvider : HPTPROVIDER -> "sptr"
; pBaseTicket : IStream* -> "sptr"
; pDeltaTicket : IStream* optional -> "sptr"
; scope : EPrintTicketScope -> "int"
; pResultTicket : IStream* -> "sptr"
; pbstrErrorMessage : LPWSTR* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。