IXpsOMPackageWriter::StartNewDocument method

Opens and initializes a new FixedDocument in the FixedDocumentSequence of the package.

Syntax

HRESULT StartNewDocument(
  [in] IOpcPartUri                            *documentPartName,
  [in] IXpsOMPrintTicketResource              *documentPrintTicket,
  [in] IXpsOMDocumentStructureResource        *documentStructure,
  [in] IXpsOMSignatureBlockResourceCollection *signatureBlockResources,
  [in] IXpsOMPartUriCollection                *restrictedFonts
);

Parameters

  • documentPartName [in]
    A pointer to an IOpcPartUri interface that contains the part name of the new document.

  • documentPrintTicket [in]
    A pointer to an IXpsOMPrintTicketResource interface that contains the document-level print ticket. If there is no document-level print ticket for this package, this parameter can be set to NULL. See also Remarks.

  • documentStructure [in]
    A pointer to an IXpsOMDocumentStructureResource interface that contains the initial document structure resource, if the resource is available; if it is not available, this parameter can be set to NULL.

  • signatureBlockResources [in]
    A pointer to an IXpsOMSignatureBlockResourceCollection interface that contains a collection of digital signatures to be attached to the document. If there are no digital signatures to be attached, this parameter can be set to NULL.

  • restrictedFonts [in]
    A pointer to an IXpsOMPartUriCollection interface that contains the fonts that must have restricted font relationships written for them. The font data are not written until AddResource or Close is called.

    If the document does not contain any restricted fonts, this parameter can be set to NULL.

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_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.

XPS_E_UNEXPECTED_RESTRICTED_FONT_RELATIONSHIP

The restricted font collection passed in restrictedFonts contains an unrestricted font.

 

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

Remarks

This method must be called before AddPage can be called to write the contents of an IXpsOMPage interface.

Immediately after the IXpsOMPackageWriter interface has been instantiated, the package contains only an empty Fixed Document Sequence part. The first time this method is called, a FixedDocument part is added to the Fixed Document Sequence part and the AddPage method will add pages to that FixedDocument part. Each time this method is called after the first time, the current FixedDocument part is closed, and a new FixedDocument part is opened and added to the Fixed Document Sequence part. All subsequent calls to the AddPage method add pages to the most recently opened FixedDocument part. This interface does not support adding pages to closed FixedDocument parts.

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

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

Note  Creating a new document in the package does not automatically create a thumbnail for the XPS document. To create a thumbnail of the XPS document, use the IXpsOMThumbnailGenerator interface.

 

Requirements

Minimum supported client

Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps | Windows Store apps]

Header

Xpsobjectmodel.h

IDL

XpsObjectModel.idl

See also

IXpsOMPackageWriter

IXpsOMPackageWriter3D

Using the IXpsOMPackageWriter Interface

IOpcPartUri

IXpsOMDocumentStructureResource

IXpsOMPrintTicketResource

IXpsOMSignatureBlockResourceCollection

Packaging Errors

XPS Document Errors

XML Paper Specification