IXpsOMPackageWriter
COM公式ドキュメント
XPS ドキュメントのパートをパッケージ ファイルに逐次的に書き込みます。
解説(Remarks)
プログレッシブな書き込みにより、アプリケーションは XPS ドキュメントのコンテンツやリソースを、利用可能になった時点で順次シリアル化できます。シリアル化の前にドキュメントのすべての要素を作成しておく必要はありません。
このインターフェイスは、AddPage が呼び出された順序でページをパッケージに書き込みます。このインターフェイスはページを順不同で書き込むことをサポートしていません。したがって、ページのコンテンツが XPS ドキュメント内で現れる順序どおりに生成される、または書き込み可能である場合にのみ使用してください。
メソッド 5
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
パッケージの FixedDocumentSequence 内に新しい FixedDocument を開いて初期化します。
| documentPartName | IOpcPartUri* | in | 新しいドキュメントのパート名を格納する IOpcPartUri インターフェイスへのポインター。 |
| documentPrintTicket | IXpsOMPrintTicketResource* | in | ドキュメント レベルの印刷チケットを格納する IXpsOMPrintTicketResource インターフェイスへのポインター。このパッケージにドキュメント レベルの印刷チケットがない場合、このパラメーターには NULL を設定できます。「解説」も参照してください。 |
| documentStructure | IXpsOMDocumentStructureResource* | in | 初期のドキュメント構造リソースが利用可能な場合に、それを格納する IXpsOMDocumentStructureResource インターフェイスへのポインター。利用できない場合、このパラメーターには NULL を設定できます。 |
| signatureBlockResources | IXpsOMSignatureBlockResourceCollection* | in | ドキュメントに添付するデジタル署名のコレクションを格納する IXpsOMSignatureBlockResourceCollection インターフェイスへのポインター。添付するデジタル署名がない場合、このパラメーターには NULL を設定できます。 |
| restrictedFonts | IXpsOMPartUriCollection* | in | 制限付きフォントのリレーションシップを書き込む必要があるフォントを格納する IXpsOMPartUriCollection インターフェイスへのポインター。フォント データは、AddResource または Close が呼び出されるまで書き込まれません。 ドキュメントに制限付きフォントが含まれていない場合、このパラメーターには NULL を設定できます。 |
戻り値
このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれます (ただしこれらに限定されません)。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 重大なエラーが発生し、XPS OM の内容が回復不能になっている可能性があります。XPS OM の一部のコンポーネントは引き続き使用できる場合もありますが、それは検証済みである場合に限られます。このエラーが返された後は XPS OM の状態を予測できないため、XPS OM のすべてのコンポーネントを解放して破棄してください。 | |
| restrictedFonts に渡された制限付きフォントのコレクションに、制限のないフォントが含まれています。 |
このメソッドは Packaging API を呼び出します。Packaging API の戻り値については、Packaging Errors を参照してください。
解説(Remarks)
IXpsOMPage インターフェイスの内容を書き込むために AddPage を呼び出す前に、このメソッドを呼び出す必要があります。
IXpsOMPackageWriter インターフェイスをインスタンス化した直後は、パッケージには空の Fixed Document Sequence パートだけが含まれています。このメソッドを最初に呼び出すと、FixedDocument パートが Fixed Document Sequence パートに追加され、AddPage メソッドはその FixedDocument パートにページを追加します。2 回目以降にこのメソッドを呼び出すたびに、現在の FixedDocument パートが閉じられ、新しい FixedDocument パートが開かれて Fixed Document Sequence パートに追加されます。それ以降の AddPage メソッドの呼び出しは、最後に開かれた FixedDocument パートにページを追加します。このインターフェイスは、閉じられた FixedDocument パートへのページの追加をサポートしていません。
documentPrintTicket が NULL ポインターで、かつパッケージ ライターがインターリーブを XPS_INTERLEAVING_ON に設定して作成されている場合、このメソッドは空のドキュメント レベルの印刷チケットがまだ存在しなければ、それを作成します。documentPrintTicket に NULL ポインターを指定してこのメソッドを呼び出すたびに、新しいドキュメントから空の印刷チケットへのリレーションシップが追加されます。これは、パッケージのストリーミング処理をより効率的にするために行われます。
documentPrintTicket が NULL ポインターで、かつパッケージ ライターがインターリーブを XPS_INTERLEAVING_OFF に設定して作成されている場合、空の印刷チケットは作成されません。
パッケージ内で現在開いている FixedDocument パートに、新しい FixedPage パートを書き込みます。
| page | IXpsOMPage* | in | パッケージの現在開いている FixedDocument に書き込むページ コンテンツを持つ IXpsOMPage インターフェイス。 |
| advisoryPageDimensions | XPS_SIZE* | in | ページの寸法を格納する XPS_SIZE 構造体。 サイズは XPS 単位で表されます。1 インチは 96 XPS 単位です。たとえば、8.5 インチ × 11.0 インチのページの寸法は 816 × 1,056 XPS 単位になります。 |
| discardableResourceParts | IXpsOMPartUriCollection* | in | 破棄可能なリソース パートのコレクションを格納する IXpsOMPartUriCollection インターフェイス。 |
| storyFragments | IXpsOMStoryFragmentsResource* | in | このページに使用する IXpsOMStoryFragmentsResource インターフェイス。 |
| pagePrintTicket | IXpsOMPrintTicketResource* | in | このページのページ レベルの印刷チケットを格納する IXpsOMPrintTicketResource インターフェイス。「解説」も参照してください。 |
| pageThumbnail | IXpsOMImageResource* | in | このページのサムネイル画像を格納する IXpsOMImageResource インターフェイス。 |
戻り値
このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれます (ただしこれらに限定されません)。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| ページが破棄可能なリソースを参照していますが、DiscardControl パート名が指定されていません。 | |
| このメソッドが StartNewDocument より前に呼び出されました。 | |
| 重大なエラーが発生し、XPS OM の内容が回復不能になっている可能性があります。XPS OM の一部のコンポーネントは引き続き使用できる場合もありますが、それは検証済みである場合に限られます。このエラーが返された後は XPS OM の状態を予測できないため、XPS OM のすべてのコンポーネントを解放して破棄してください。 |
このメソッドは Packaging API を呼び出します。Packaging API の戻り値については、Packaging Errors を参照してください。
解説(Remarks)
このメソッドは、StartNewDocument を呼び出した後に呼び出してください。
このメソッドはパッケージ内に新しい FixedPage パートを作成し、page パラメーターに渡された IXpsOMPage インターフェイスの内容をコピーします。その後、ページがパッケージに書き込まれると、新しい FixedPage パートを閉じます。
pagePrintTicket が NULL ポインターで、かつパッケージ ライターがインターリーブを XPS_INTERLEAVING_ON に設定して作成されている場合、このメソッドは空のページ レベルの印刷チケットがまだ存在しなければ、それを作成します。pagePrintTicket に NULL ポインターを指定してこのメソッドを呼び出すたびに、新しいページから空の印刷チケットへのリレーションシップが追加されます。これは、パッケージのストリーミング処理をより効率的にするために行われます。
pagePrintTicket が NULL ポインターで、かつパッケージ ライターがインターリーブを XPS_INTERLEAVING_OFF に設定して作成されている場合、空の印刷チケットは作成されません。
パッケージ内に新しいパート リソースを作成します。
| resource | IXpsOMResource* | in | パッケージに新しいパートとして追加されるパート リソースの IXpsOMResource インターフェイス。このパラメーターに渡すことができるリソースの種類については、「解説」を参照してください。 |
戻り値
このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれます (ただしこれらに限定されません)。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
|
resource が参照するリソースと同じ名前のリソースが既にストリームに追加されているか、resource が参照するリソースを含むリレーションシップが存在しません。
E_INVALIDARG が返された後、ストリームまたはファイルは無効になり、Close は XPS_E_UNAVAILABLE_PACKAGE を返します。 |
|
| 重大なエラーが発生し、XPS OM の内容が回復不能になっている可能性があります。XPS OM の一部のコンポーネントは引き続き使用できる場合もありますが、それは検証済みである場合に限られます。このエラーが返された後は XPS OM の状態を予測できないため、XPS OM のすべてのコンポーネントを解放して破棄してください。 |
このメソッドは Packaging API を呼び出します。Packaging API の戻り値については、Packaging Errors を参照してください。
解説(Remarks)
このメソッドは、resource に対応する新しいパートをドキュメント パッケージ内に作成し、resource の内容を新しいパートに追加してから、その新しいパートを閉じます。
このメソッドがエラーを返した場合、パッケージ ライターは以降使用できなくなります。
resource パラメーターには、次のいずれかを指定する必要があります。
- 現在のページまたは既に追加済みのページで使用されているフォント リソースの IXpsOMFontResource インターフェイス。
- 現在のページまたは既に追加済みのページで使用されている画像リソースの IXpsOMImageResource インターフェイス。
- 現在のページまたは既に追加済みのページで使用されているカラー プロファイル リソースの IXpsOMColorProfileResource インターフェイス。
- 現在のページまたは既に追加済みのページで使用されているストーリー フラグメント リソースの IXpsOMStoryFragmentsResource インターフェイス。
- 現在のドキュメントまたは既に追加済みのドキュメントで使用されているドキュメント構造リソースの IXpsOMDocumentStructureResource インターフェイス。
- 現在のドキュメントまたは既に追加済みのドキュメントで使用されている署名ブロック リソースの IXpsOMSignatureBlockResource インターフェイス。
resource が次のいずれかを含む場合、このメソッドはエラーを返します。
- リモート リソース ディクショナリの IXpsOMRemoteDictionaryResource インターフェイス。
- 印刷チケットの IXpsOMPrintTicketResource インターフェイス。
- サムネイル画像の IXpsOMImageResource インターフェイス。
resource が、既にストリームに追加されているリソースと同じ名前のリソース、またはリレーションシップが存在しないリソースを参照している場合、このメソッドはエラーを返します。
パッケージ内で開いているすべてのパートを閉じてから、パッケージを閉じます。
戻り値
このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれます (ただしこれらに限定されません)。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 重大なエラーが発生し、XPS OM の内容が回復不能になっている可能性があります。XPS OM の一部のコンポーネントは引き続き使用できる場合もありますが、それは検証済みである場合に限られます。このエラーが返された後は XPS OM の状態を予測できないため、XPS OM のすべてのコンポーネントを解放して破棄してください。 |
このメソッドは Packaging API を呼び出します。Packaging API の戻り値については、Packaging Errors を参照してください。
解説(Remarks)
AddPage の呼び出しで参照されている破棄可能なパートのうち、まだ受け取られていないものがある場合は、エラーが返されます。
このメソッドを呼び出した後に IsClosed 以外の IXpsOMPackageWriter メソッドを呼び出すと、エラーが返されます。
IXpsOMPackageWriter インターフェイスの状態を取得します。
| isClosed | BOOL* | out | IXpsOMPackageWriter インターフェイスの状態を受け取るブール変数へのポインター。
|
戻り値
このメソッドは HRESULT を返します。返される可能性のある値には、次の表に示すものが含まれます (ただしこれらに限定されません)。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| 重大なエラーが発生し、XPS OM の内容が回復不能になっている可能性があります。XPS OM の一部のコンポーネントは引き続き使用できる場合もありますが、それは検証済みである場合に限られます。このエラーが返された後は XPS OM の状態を予測できないため、XPS OM のすべてのコンポーネントを解放して破棄してください。 |
このメソッドは Packaging API を呼び出します。Packaging API の戻り値については、Packaging Errors を参照してください。
解説(Remarks)
IXpsOMPackageWriter インターフェイスが閉じられている場合、パッケージに対する操作は許可されません。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IXpsOMPackageWriter "{4E2AA182-A443-42C6-B41B-4F8E9DE73FF9}" #usecom global IXpsOMPackageWriter IID_IXpsOMPackageWriter "{}" #comfunc global IXpsOMPackageWriter_StartNewDocument 3 sptr,sptr,sptr,sptr,sptr #comfunc global IXpsOMPackageWriter_AddPage 4 sptr,var,sptr,sptr,sptr,sptr #comfunc global IXpsOMPackageWriter_AddResource 5 sptr #comfunc global IXpsOMPackageWriter_Close 6 #comfunc global IXpsOMPackageWriter_IsClosed 7 var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IXpsOMPackageWriter "{4E2AA182-A443-42C6-B41B-4F8E9DE73FF9}" #usecom global IXpsOMPackageWriter IID_IXpsOMPackageWriter "{}" #comfunc global IXpsOMPackageWriter_StartNewDocument 3 sptr,sptr,sptr,sptr,sptr #comfunc global IXpsOMPackageWriter_AddPage 4 sptr,sptr,sptr,sptr,sptr,sptr #comfunc global IXpsOMPackageWriter_AddResource 5 sptr #comfunc global IXpsOMPackageWriter_Close 6 #comfunc global IXpsOMPackageWriter_IsClosed 7 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。