IXpsOMObjectFactory::CreatePackageWriterOnFile method (xpsobjectmodel.h)

Article
10/13/2021

Opens a file for writing the contents of an XPS OM to an XPS package.

Syntax

HRESULT CreatePackageWriterOnFile(
  [in]          LPCWSTR                   fileName,
  [in]          LPSECURITY_ATTRIBUTES     securityAttributes,
  [in]          DWORD                     flagsAndAttributes,
  [in]          BOOL                      optimizeMarkupSize,
  [in]          XPS_INTERLEAVING          interleaving,
  [in]          IOpcPartUri               *documentSequencePartName,
  [in]          IXpsOMCoreProperties      *coreProperties,
  [in]          IXpsOMImageResource       *packageThumbnail,
  [in]          IXpsOMPrintTicketResource *documentSequencePrintTicket,
  [in]          IOpcPartUri               *discardControlPartName,
  [out, retval] IXpsOMPackageWriter       **packageWriter
);

Parameters

[in] fileName

The name of the file to be created.

[in] securityAttributes

The SECURITY_ATTRIBUTES structure, which contains two separate but related members:

lpSecurityDescriptor: an optional security descriptor
bInheritHandle: a Boolean value that determines whether the returned handle can be inherited by child processes

If lpSecurityDescriptor is NULL, the file or device associated with the returned handle is assigned a default security descriptor.

For more information about securityAttributes, see CreateFile.

[in] flagsAndAttributes

Specifies the settings and attributes of the file to be created. For most files, the FILE_ATTRIBUTE_NORMAL value can be used.

See CreateFile for more information about this parameter.

[in] optimizeMarkupSize

A Boolean value that indicates whether the document markup will be optimized for size when the contents of the XPS OM are written to the XPS package.

Value	Meaning
TRUE	The package writer will try to optimize the markup for minimum size.
FALSE	The package writer will not try to perform any optimization.

[in] interleaving

Specifies whether the content of the XPS OM will be interleaved when it is written to the file.

[in] documentSequencePartName

The IOpcPartUri interface that contains the part name of the document sequence in the new file.

[in] coreProperties

The IXpsOMCoreProperties interface that contains the core document properties to be given to the new file. This parameter can be set to NULL.

[in] packageThumbnail

The IXpsOMImageResource interface that contains the thumbnail image to be assigned to the new file. This parameter can be set to NULL.

[in] documentSequencePrintTicket

The IXpsOMPrintTicketResource interface that contains the package-level print ticket to be assigned to the new file. This parameter can be set to NULL.

[in] discardControlPartName

The IOpcPartUri interface that contains the name of the discard control part. This parameter can be set to NULL.

[out, retval] packageWriter

A pointer to the new IXpsOMPackageWriter interface created by this method.

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.
E_POINTER	filename, documentSequencePartName, or packageWriter is NULL.
XPS_E_NO_CUSTOM_OBJECTS	coreProperties, documentSequencePrintTicket, or packageThumbnail does not point to a recognized interface implementation. Custom implementation of XPS Document API interfaces is not supported.

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

Remarks

The file is opened and initialized and the IXpsOMPackageWriter interface that is returned is then used to write content types, package relationships, core properties, document sequence resources, and document sequence relationships.

If documentSequencePrintTicket is set to NULL and the value of interleaving is XPS_INTERLEAVING_ON, this method creates a blank job-level print ticket and adds a relationship to the blank print ticket. This is done to provide more efficient streaming consumption of the package.

If documentSequencePrintTicket is set to NULL and the value of interleaving is 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