IXpsOMDictionary
COM公式ドキュメント
ディクショナリは、XPS パッケージがリソースを共有するために使用されます。
解説(Remarks)
ディクショナリに格納されるインターフェイスポインターは通常、IXpsOMBrush や IXpsOMVisual など、IXpsOMShareable インターフェイスから派生したインターフェイスを指します。インターフェイスの種類を判別するには、IXpsOMShareable::GetType メソッドを呼び出します。
ディクショナリに重複したインターフェイスポインターを格納することはできません。
メソッド 10
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
ディクショナリを保持しているインターフェイスへのポインターを取得します。
| owner | IUnknown** | out | ディクショナリを保持しているインターフェイスの IUnknown インターフェイスです。 |
戻り値
メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
ディクショナリ内のエントリ数を取得します。
| count | DWORD* | out | ディクショナリ内のエントリ数です。 |
戻り値
メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
ディクショナリ内の指定されたインデックスにあるエントリの IXpsOMShareable インターフェイスポインターとキー名文字列を取得します。
| index | DWORD | in | 取得するディクショナリエントリの 0 から始まるインデックスです。 |
| key | LPWSTR* | out | index で指定された位置にあるキー文字列です。 |
| entry | IXpsOMShareable** | out | index で指定された位置にある IXpsOMShareable インターフェイスポインターです。 |
戻り値
メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
ディクショナリに格納されるインターフェイスポインターは通常、IXpsOMBrush や IXpsOMVisual など、IXpsOMShareable インターフェイスから派生したインターフェイスを指します。インターフェイスの種類を判別するには、IXpsOMShareable::GetType メソッドを呼び出します。
このメソッドは、key で返される文字列が使用するメモリを割り当てます。key が NULL でない場合は、CoTaskMemFree 関数を使用してメモリを解放してください。
指定されたキーを持つエントリの IXpsOMShareable インターフェイスポインターを取得します。
| key | LPWSTR | in | ディクショナリ内で検索するエントリのキーです。 |
| beforeEntry | IXpsOMShareable* | in | key の検索対象となる、ディクショナリ内の最後のエントリを指す IXpsOMShareable インターフェイスポインターです。beforeEntry が NULL であるか、ディクショナリに存在しないエントリへのインターフェイスポインターである場合は、ディクショナリ全体が検索されます。 |
| entry | IXpsOMShareable** | out | キーが key と一致するディクショナリエントリへのインターフェイスポインターです。 |
戻り値
メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
ディクショナリに格納されるインターフェイスポインターは通常、IXpsOMBrush や IXpsOMVisual など、IXpsOMShareable インターフェイスから派生したインターフェイスを指します。インターフェイスの種類を判別するには、IXpsOMShareable::GetType メソッドを呼び出します。
ディクショナリから IXpsOMShareable インターフェイスのインデックスを取得します。
| entry | IXpsOMShareable* | in | ディクショナリ内で検索する IXpsOMShareable インターフェイスポインターです。 |
| index | DWORD* | out | ディクショナリ内における entry の 0 から始まるインデックスです。 |
戻り値
このメソッドは HRESULT を返します。戻り値には次の表に示す値が含まれますが、これらに限定されるものではありません。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| entry が参照するオブジェクトがディクショナリ内に存在しません。 |
IXpsOMShareable インターフェイスをそのキーとともにディクショナリの末尾に追加します。
| key | LPWSTR | in | このエントリに使用するキーです。 key が参照する文字列は、ディクショナリ内で一意である必要があります。 |
| entry | IXpsOMShareable* | in | ディクショナリに追加する IXpsOMShareable インターフェイスへのポインターです。 ディクショナリに重複したインターフェイスポインターを格納することはできません。このパラメーターには、ディクショナリにまだ存在しないインターフェイスポインターを指定する必要があります。 |
戻り値
このメソッドは HRESULT を返します。戻り値には次の表に示す値が含まれますが、これらに限定されるものではありません。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| entry が認識可能なインターフェイス実装を指していません。XPS ドキュメント API インターフェイスの独自実装はサポートされていません。 |
解説(Remarks)
ディクショナリに格納されるインターフェイスポインターは通常、IXpsOMBrush や IXpsOMVisual など、IXpsOMShareable インターフェイスから派生したインターフェイスを指します。インターフェイスの種類を判別するには、IXpsOMShareable::GetType メソッドを呼び出します。
次の図は、Append メソッドによってディクショナリがどのように変化するかを示しています。
ディクショナリ内の指定された位置に IXpsOMShareable インターフェイスを挿入し、そのインターフェイスを識別するキーを設定します。
| index | DWORD | in | IXpsOMShareable インターフェイスを挿入するディクショナリ内の 0 から始まるインデックスです。 |
| key | LPWSTR | in | ディクショナリ内で IXpsOMShareable インターフェイスを識別するために使用するキーです。 key が参照する文字列は、ディクショナリ内で一意である必要があります。 |
| entry | IXpsOMShareable* | in | index で指定された位置に挿入する IXpsOMShareable インターフェイスポインターです。 ディクショナリに重複したインターフェイスポインターを格納することはできません。このパラメーターには、ディクショナリにまだ存在しないインターフェイスポインターを指定する必要があります。 |
戻り値
このメソッドは HRESULT を返します。戻り値には次の表に示す値が含まれますが、これらに限定されるものではありません。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| entry が認識可能なインターフェイス実装を指していません。XPS ドキュメント API インターフェイスの独自実装はサポートされていません。 |
解説(Remarks)
ディクショナリに格納されるインターフェイスポインターは通常、IXpsOMBrush や IXpsOMVisual など、IXpsOMShareable インターフェイスから派生したインターフェイスへのポインターです。インターフェイスの種類を判別するには、IXpsOMShareable::GetType メソッドを呼び出します。
このメソッドは、index で指定された位置に IXpsOMShareable インターフェイスポインターを挿入し、キーを設定します。インターフェイスポインターとキーは、それぞれ value と key で渡します。value と key が挿入される前に、この位置およびそれ以降のすべての位置にあるインターフェイスポインターとキーのインデックスが 1 つずつ繰り上げられます。
次の図は、InsertAt メソッドによってディクショナリがどのように変化するかを示しています。
ディクショナリ内の指定された位置のエントリを削除して解放します。
| index | DWORD | in | エントリを削除して解放するディクショナリ内の 0 から始まるインデックスです。 |
戻り値
メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
このメソッドは、index で指定された位置にあるポインターが参照するインターフェイスを解放します。インターフェイスを解放した後、index より後ろにある各ポインターのインデックスを 1 つずつ減らして、ディクショナリを詰めます。
次の図は、RemoveAt メソッドによってディクショナリがどのように変化するかを示しています。
ディクショナリ内の指定された位置のエントリを置き換えます。
| index | DWORD | in | エントリを置き換えるディクショナリ内の 0 から始まるインデックスです。 |
| key | LPWSTR | in | 新しいエントリに使用するキーです。 key が参照する文字列は、ディクショナリ内で一意である必要があります。 |
| entry | IXpsOMShareable* | in | index で指定された位置の現在の内容を置き換える IXpsOMShareable インターフェイスポインターです。 ディクショナリに重複したインターフェイスポインターを格納することはできません。このパラメーターには、ディクショナリにまだ存在しないインターフェイスポインターを指定する必要があります。 |
戻り値
このメソッドは HRESULT を返します。戻り値には次の表に示す値が含まれますが、これらに限定されるものではありません。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| entry が認識可能なインターフェイス実装を指していません。XPS ドキュメント API インターフェイスの独自実装はサポートされていません。 |
解説(Remarks)
このメソッドは、index で指定された位置にある既存のポインターが参照する IXpsOMShareable インターフェイスを解放し、entry で渡されたインターフェイスポインターで置き換えて、key で渡されたキーを割り当てます。
ディクショナリに格納されるインターフェイスポインターは通常、IXpsOMBrush や IXpsOMVisual など、IXpsOMShareable インターフェイスから派生したインターフェイスを指します。インターフェイスの種類を判別するには、GetType メソッドを呼び出します。
次の図は、SetAt メソッドによってディクショナリがどのように変化するかを示しています。
インターフェイスのディープコピーを作成します。(IXpsOMDictionary.Clone)
| dictionary | IXpsOMDictionary** | out | インターフェイスのコピーへのポインターです。 |
戻り値
このメソッドは HRESULT を返します。戻り値には次の表に示す値が含まれますが、これらに限定されるものではありません。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。
| 戻り値 | 説明 |
|---|---|
| メソッドは成功しました。 | |
| この操作を実行するのに十分なメモリがありません。 | |
| dictionary が NULL です。 |
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IXpsOMDictionary "{897C86B8-8EAF-4AE3-BDDE-56419FCF4236}" #usecom global IXpsOMDictionary IID_IXpsOMDictionary "{}" #comfunc global IXpsOMDictionary_GetOwner 3 sptr #comfunc global IXpsOMDictionary_GetCount 4 var #comfunc global IXpsOMDictionary_GetAt 5 int,var,sptr #comfunc global IXpsOMDictionary_GetByKey 6 wstr,sptr,sptr #comfunc global IXpsOMDictionary_GetIndex 7 sptr,var #comfunc global IXpsOMDictionary_Append 8 wstr,sptr #comfunc global IXpsOMDictionary_InsertAt 9 int,wstr,sptr #comfunc global IXpsOMDictionary_RemoveAt 10 int #comfunc global IXpsOMDictionary_SetAt 11 int,wstr,sptr #comfunc global IXpsOMDictionary_Clone 12 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IXpsOMDictionary "{897C86B8-8EAF-4AE3-BDDE-56419FCF4236}" #usecom global IXpsOMDictionary IID_IXpsOMDictionary "{}" #comfunc global IXpsOMDictionary_GetOwner 3 sptr #comfunc global IXpsOMDictionary_GetCount 4 sptr #comfunc global IXpsOMDictionary_GetAt 5 int,sptr,sptr #comfunc global IXpsOMDictionary_GetByKey 6 wstr,sptr,sptr #comfunc global IXpsOMDictionary_GetIndex 7 sptr,sptr #comfunc global IXpsOMDictionary_Append 8 wstr,sptr #comfunc global IXpsOMDictionary_InsertAt 9 int,wstr,sptr #comfunc global IXpsOMDictionary_RemoveAt 10 int #comfunc global IXpsOMDictionary_SetAt 11 int,wstr,sptr #comfunc global IXpsOMDictionary_Clone 12 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。