IXpsOMPackageWriter::AddPage method (xpsobjectmodel.h)

Article
10/13/2021

Writes a new FixedPage part to the currently open FixedDocument part in the package.

Syntax

HRESULT AddPage(
  [in] IXpsOMPage                   *page,
  [in] const XPS_SIZE               *advisoryPageDimensions,
  [in] IXpsOMPartUriCollection      *discardableResourceParts,
  [in] IXpsOMStoryFragmentsResource *storyFragments,
  [in] IXpsOMPrintTicketResource    *pagePrintTicket,
  [in] IXpsOMImageResource          *pageThumbnail
);

Parameters

[in] page

The IXpsOMPage interface whose page content is to be written to the currently open FixedDocument of the package.

[in] advisoryPageDimensions

The XPS_SIZE structure that contains page dimensions.

Size is described in XPS units. There are 96 XPS units per inch. For example, the dimensions of an 8.5" by 11.0" page are 816 by 1,056 XPS units.

[in] discardableResourceParts

The IXpsOMPartUriCollection interface that contains a collection of the discardable resource parts.

[in] storyFragments

The IXpsOMStoryFragmentsResource interface that is to be used for this page.

[in] pagePrintTicket

The IXpsOMPrintTicketResource interface that contains the page-level print ticket for this page. See also Remarks.

[in] pageThumbnail

The IXpsOMImageResource interface that contains the thumbnail image of this page.

Return value

The method returns an HRESULT. Possible values include, but are not limited to, those in the table that follows. For information about XPS document API return values that are not listed in this table, see XPS Document Errors.

Return code	Description
S_OK	The method succeeded.
XPS_E_MISSING_DISCARDCONTROL	A page refers to discardable resources but does not specify a DiscardControl part name.
XPS_E_MISSING_DOCUMENT	This method was called before StartNewDocument.
XPS_E_UNAVAILABLE_PACKAGE	A severe error occurred and the contents of the XPS OM might be unrecoverable. Some components of the XPS OM might still be usable but only after they have been verified. Because the state of the XPS OM cannot be predicted after this error is returned, all components of the XPS OM should be released and discarded.

This method calls the Packaging API. For information about the Packaging API return values, see Packaging Errors.

Remarks

Call this method after calling StartNewDocument.

This method creates a new FixedPage part in the package, copies the contents of the IXpsOMPage interface that is passed in the page parameter, and then closes the new FixedPage part after the page has been written to the package.

If pagePrintTicket contains a NULL pointer and the package writer was created with interleaving set to XPS_INTERLEAVING_ON, this method creates a blank page-level print ticket, if one does not already exist. Each time method is called with a NULL pointer in pagePrintTicket, it adds a relationship from the new page to the blank print ticket. This is done to provide more efficient streaming consumption of the package.

If pagePrintTicket contains a NULL pointer and the package writer was created with interleaving set to XPS_INTERLEAVING_OFF, no blank print ticket is created.

Requirements

Requirement	Value
Minimum supported client	Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	xpsobjectmodel.h