Using the IXpsOMPackageWriter Interface
The IXpsOMPackageWriter interface creates an XPS document file into which applications can write the contents of the IXpsOMPage interfaces of an XPS OM. The IXpsOMPackageWriter interface is most useful when document contents are being processed or created sequentially. Unlike the WriteToFile and WriteToStream methods of the IXpsOMPackage interface, for the IXpsOMPackageWriter interface to be used neither the entire FixedDocument nor the FixedDocumentSequence has to be finished.
Overview
The IXpsOMPackageWriter interface writes one page at a time, from the first page of an XPS document to the last. The interface can be used to create simple XPS document files and also complex XPS document files that contain more than one FixedDocument in the FixedDocumentSequence. In complex XPS document files, the FixedDocuments are also created in sequence, starting with the first FixedDocument in the FixedDocumentSequence. The IXpsOMPackageWriter interface does not support the creation of document contents in random order. Use it, for example, to create a sequential report or to perform processing in a device driver filter where the document contents are fed to the driver in sequence.
Terminology Review
An XPS document file is an Open Packaging Conventions (OPC) package that conforms to the XML Paper Specification. So, technically, the IXpsOMPackageWriter interface creates an OPC package, but it is an OPC package that conforms to the XML Paper Specification. For this reason, in discussions about XPS documents, the terms XPS document and package are often used interchangeably.
The package created by the IXpsOMPackageWriter interface will contain the required XPS document components: a FixedDocumentSequence, at least one FixedDocument, and at least one FixedPage. The FixedDocumentSequence is created when the IXpsOMPackageWriter interface is instantiated. A FixedDocument is created every time IXpsOMPackageWriter::StartNewDocument is called, and a FixedPage is created every time IXpsOMPackageWriter::AddPage is called. Because the interface writes the document contents sequentially, the AddPage method adds the page to the most recently created FixedDocument.
Using the IXpsOMPackageWriter Interface
The following procedure describes how to create an XPS document file by using the IXpsOMPackageWriter interface. The procedure does not describe how to instantiate an IXpsOMPage interface and its contents. For more information about IXpsOMPage and adding content to a page, see XPS OM Page Interfaces and the topics listed in the See Also section.
.gif "Dd464658.wedge(en-us,VS.85).gif")
Creating a document
Instantiate an IXpsOMPackageWriter interface.
This creates an empty FixedDocumentSequence in the package.
- To create an XPS document in a file, call IXpsOMObjectFactory::CreatePackageWriterOnFile.
- To create an XPS document in a stream, call IXpsOMObjectFactory::CreatePackageWriterOnStream.
Start a new document in the package by calling IXpsOMPackageWriter::StartNewDocument.
Before adding a page, call IXpsOMPackageWriter::StartNewDocument to add a FixedDocument to the FixedDocumentSequence that was created in step 1.
Add content.
- To add a new FixedPage to the document, call IXpsOMPackageWriter::AddPage, passing it a pointer to the IXpsOMPage interface that has the contents of the FixedPage that you want to add.
- To create a new FixedDocument in the FixedDocumentSequence, call IXpsOMPackageWriter::StartNewDocument.
Close the package and its contents by calling IXpsOMPackageWriter::Close.
Advanced Features
The methods of the IXpsOMPackageWriter interface also support the adding of resources, thumbnails, and print tickets. These document components can be added at the package, FixedDocumentSequence, FixedDocument, and FixedPage levels. For more information about using this interface for printing, see Print an XPS OM.
Related topics
Using XPS Digital Signature API
Working with XPS OM Canvas and Visual Interfaces
Working with XPS OM Path Interfaces
Working with XPS OM Text, Graphics, and Image Interfaces