IXpsOMPageReference

XPS ドキュメント内のページの仮想化を可能にします。

次のコード例は、このインターフェイスのインスタンスを作成する方法を示しています。

IXpsOMPageReference    *newInterface;
// 次の値は、この例の外部で定義されています。
XPS_SIZE        advisoryPageDimensions;

// このスレッドで CoInitializeEx が事前に呼び出されている必要があるという
//  暗黙の前提がある点に注意してください。

hr = CoCreateInstance(
    __uuidof(XpsOMObjectFactory),
    NULL,
    CLSCTX_INPROC_SERVER,
    _uuidof(IXpsOMObjectFactory),
    reinterpret_cast<LPVOID*>(&xpsFactory)
    );

if (SUCCEEDED(hr))
{
    hr = xpsFactory->CreatePageReference (
        &advisoryPageDimensions,
        &newInterface);

    if (SUCCEEDED(hr))
    {
        // newInterface を使用します

        newInterface->Release();
    }
    xpsFactory->Release();
}
else
{
    // hr に返された HRESULT エラーを評価します
}

プログラムでこのインターフェイスを使用する方法については、Create a Blank XPS OM および Navigate the XPS OM を参照してください。

ページ参照を含む IXpsOMDocument インターフェイスへのポインターを取得します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

ページを含む IXpsOMPage インターフェイスへのポインターを取得します。

このメソッドは HRESULT を返します。指定できる値には次の表の値が含まれますが、これらに限定されません。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。

このメソッドは Packaging API を呼び出します。Packaging API の戻り値については、Packaging Errors を参照してください。

ページが設定されていない場合でも、そのページ参照を含む IXpsOMPackage インターフェイスが XPS パッケージから読み込まれていれば、このメソッドはページを読み込んで返します。ページが設定されておらず、このページ参照を含む IXpsOMPackage インターフェイスも XPS パッケージから読み込まれていない場合は、NULL ポインターが返されます。

ページの内容によっては、この呼び出しが戻るまでに時間がかかることがあり、ドキュメントツリー内の他のオブジェクトに予期しない変更が生じる場合もあります。たとえば、ページがリモートリソースディクショナリを参照している場合、そのリモートリソースディクショナリが変更されることがあります。

ページ参照の IXpsOMPage インターフェイスを設定します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドで追加するページは、空でも完全に構築済みでもかまいません。

追加するページがリモートディクショナリオブジェクトへの参照を持っている場合、それらのオブジェクトはこの呼び出しではドキュメントオブジェクトにインポートされません。IXpsOMPage::SetDictionaryResource メソッドまたは IXpsOMCanvas::SetDictionaryResource メソッドを個別に呼び出して追加する必要があります。

既にページが設定されている場合、呼び出し側は新しいページで SetPage を呼び出す前に、そのページを解放しておく必要があります。新しいページで SetPage を呼び出した後は、元のページがパッケージ内に残っていても破棄できなくなるためです。

ページをメモリから破棄します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

SetPage が呼び出されていない場合、DiscardPage を呼び出した後に GetPage を呼び出すと、ソースパッケージから仮想化されたページが返されます。SetPage が呼び出されている場合、DiscardPage を呼び出した後に GetPage を呼び出すと NULL が返されます。

この IXpsOMPageReference インターフェイスが参照するページがすべてメモリ上で構築されており、対応するファイルが存在しない場合、DiscardPage はページをメモリから削除し、ページの内容は失われます。ページがファイルから構築されている場合、DiscardPage はページをメモリから削除しますが、元のファイルは変更しません。ページは GetPage を呼び出すことで再構築され、メモリに読み込み直すことができます。

ページがファイルから構築された後に変更されている場合、DiscardPage はページをメモリから破棄し、ページに加えられた変更は失われます。この後に GetPage を呼び出すと、元の内容がファイルから再度読み込まれます。

参照先ページの状態、つまりページが読み込まれているかどうかを取得します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

ページの推奨サイズを取得します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

ページの推奨サイズを設定します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

pageDimensions が参照する XPS_SIZE 構造体の height メンバーと width メンバーには、値を設定する場合は +1.0 以上の値を、設定しない場合は –1.0 を指定する必要があります。たとえば、ページの幅にだけ推奨サイズを設定する場合は、pageDimensions.width に目的の値を指定し、pageDimensions.height には –1.0 を指定します。

ページに関連付けられている StoryFragments パートのリソースの IXpsOMStoryFragmentsResource インターフェイスへのポインターを取得します。

このメソッドは HRESULT を返します。指定できる値には次の表の値が含まれますが、これらに限定されません。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。

このメソッドは Packaging API を呼び出します。Packaging API の戻り値については、Packaging Errors を参照してください。

リソースが解析されて XPS OM に読み込まれた後、このメソッドが別のリソースに関するエラーを返す場合があります。これは、リソースの読み込み時にすべてのリレーションシップが解析されるためです。

ページの StoryFragments パートには、1 つの固定ページに関連付けられた 1 つ以上のストーリーの一部を記述する XML マークアップが含まれます。StoryFragments パートの XML マークアップが記述するドキュメントの内容には、そのページ上にあるストーリーの表や段落などがあります。

DocumentStructure パートと StoryFragments パートの XML マークアップについては、XML Paper Specification で説明されています。

ページに割り当てる StoryFragments リソースの IXpsOMStoryFragmentsResource インターフェイスポインターを設定します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

ページの StoryFragments パートには、1 つの固定ページに関連付けられた 1 つ以上のストーリーの一部を記述する XML マークアップが含まれます。StoryFragments パートの XML マークアップが記述するドキュメントの内容には、そのページ上にあるストーリーの表や段落などがあります。

DocumentStructure パートと StoryFragments パートの XML マークアップについては、XML Paper Specification で説明されています。

ページに関連付けられているページレベルの印刷チケットリソースの IXpsOMPrintTicketResource インターフェイスへのポインターを取得します。

このメソッドは HRESULT を返します。指定できる値には次の表の値が含まれますが、これらに限定されません。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。

このメソッドは Packaging API を呼び出します。Packaging API の戻り値については、Packaging Errors を参照してください。

リソースを XPS OM に読み込んで解析した後、このメソッドが別のリソースに関するエラーを返す場合があります。これは、リソースの読み込み時にすべてのリレーションシップが解析されるためです。

ページに割り当てるページレベルの印刷チケットリソースの IXpsOMPrintTicketResource インターフェイスポインターを設定します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

ページに関連付けられているサムネイル画像リソースの IXpsOMImageResource インターフェイスへのポインターを取得します。

このメソッドは HRESULT を返します。指定できる値には次の表の値が含まれますが、これらに限定されません。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。

このメソッドは Packaging API を呼び出します。Packaging API の戻り値については、Packaging Errors を参照してください。

サムネイル画像は、ページの内容を小さく視覚的に表したものです。

リソースを XPS OM に読み込んで解析した後、このメソッドが別のリソースに関するエラーを返す場合があります。これは、リソースの読み込み時にすべてのリレーションシップが解析されるためです。

ページに割り当てるサムネイル画像リソースの IXpsOMImageResource インターフェイスへのポインターを設定します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

サムネイル画像は、ドキュメントの内容を小さく視覚的に表したものです。

画像リソースの画像形式は、XPS_IMAGE_TYPE_JPEG または XPS_IMAGE_TYPE_PNG のいずれかである必要があります。

IsHyperlinkTarget プロパティが TRUE に設定されている、ドキュメントサブツリー内のすべてのオブジェクトの名前を格納した IXpsOMNameCollection インターフェイスを取得します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

ページが元々パッケージから読み込まれたものであり、現在オブジェクトモデルに読み込まれていない場合、このメソッドは元の PageContent.LinkTargets マークアップで指定された値を返します。

ドキュメントにリンクターゲットが 1 つも存在しない場合、linkTargets に返される名前コレクションは空になります。

linkTargets に返されるコレクションの要素数を取得するには、コレクションの GetCount メソッドを呼び出します。

このメソッドは、呼び出すたびに新しいコレクションへのポインターを返します。メモリリークを防ぐため、以前のコレクションへのポインターは、不要になった時点、またはポインター変数をこのメソッドの次の呼び出しに再利用する前に解放してください。次のコード例は、プログラムでこれを行う方法を示しています。

    HRESULT                         hr = S_OK;
    IXpsOMPage                      *page = NULL;
    IXpsOMNameCollection            *linkTargets = NULL;

    UINT32 numTargets = 0;
    UINT32 thisTarget = 0;
    LPWSTR thisTargetName = NULL;

    // pageRef には現在のページ参照が格納されています

    // ページがまだ読み込まれていない場合(たとえば XPS OM が XPS ドキュメントから
    //  読み込まれた場合)、CollectLinkTargets は <PageContent.LinkTargets> マークアップから
    //  リンクターゲットの一覧を取得します
    hr = pageRef->CollectLinkTargets(&linkTargets);

    // このページ参照のページコンテンツを取得します
    hr = pageRef->GetPage (&page);

    // GetPage の呼び出しによってページオブジェクトが読み込まれた後、または
    //  XPS OM でページを作成した後は、CollectLinkTargets が各ページ要素を
    //  調べて一覧を返すため、XPS OM がファイルから作成された場合、この
    //  CollectLinkTargets の呼び出しは上記の呼び出しよりも時間がかかることがあります
    linkTargets->Release(); // 以前のコレクションを解放します
    hr = pageRef->CollectLinkTargets(&linkTargets);
    
    // 返されたリンクターゲットの一覧を走査します
    hr = linkTargets->GetCount( &numTargets );
    thisTarget = 0;
    while (thisTarget < numTargets) {
        hr = linkTargets->GetAt (thisTarget, &thisTargetName);
        printf ("%s\n", thisTargetName);
        // メモリリークを防ぐため、返されたターゲット文字列を解放します
        CoTaskMemFree (thisTargetName);
        // 一覧内の次のターゲットを取得します
        thisTarget++;
    }
    // ページとリンクターゲットコレクションを解放します
    page->Release();
    linkTargets->Release();

ページに関連付けられているすべてのパートベースのリソースの一覧を作成します。

このメソッドは HRESULT を返します。指定できる値には次の表の値が含まれますが、これらに限定されません。この表に記載されていない XPS ドキュメント API の戻り値については、XPS Document Errors を参照してください。

このメソッドは Packaging API を呼び出します。Packaging API の戻り値については、Packaging Errors を参照してください。

このメソッドの呼び出し時にページが読み込まれていない場合、このメソッドはページのリレーションシップパートを解析してこのページに関連付けられたパートベースのリソースを検出し、partResources パラメーターに返します。ページが読み込まれている場合は、ページのオブジェクトモデルをたどってパートベースのリソースを検出し、partResources に返します。

IXpsOMPartResources インターフェイスに返されるリソースパートの一覧は、メソッドが呼び出された時点のドキュメント構造のスナップショットです。この呼び出しの後にドキュメントに加えられた変更は、このメソッドが返した IXpsOMPartResources インターフェイスには反映されません。同様に、このメソッドが返した IXpsOMPartResources インターフェイスに加えた変更も、ドキュメントの内容には反映されません。

参照先ページのドキュメントサブツリーに、EmbeddingOption プロパティが XPS_FONT_EMBEDDING_RESTRICTED に設定されたフォントリソースを持つ Glyphs が含まれているかどうかを示すブール値を取得します。

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

この値は自動的には更新されません。フォントやグリフの追加や削除によって値が変化する場合は、HasRestrictedFonts を再度呼び出して現在の値を取得する必要があります。

インターフェイスのディープコピーを作成します。(IXpsOMPageReference.Clone)

メソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドは、新しい IXpsOMPageReference インターフェイス内のリソースポインターを更新しません。