IPrint::Print

Prints an object on the specified printer, using the specified job requirements.

HRESULT Print(

DWORD grfFlags,	// A bit field
DVTARGETDEVICE **pptd,	// On return, Indirect pointer to the target device
PAGESET **pppageset,	// On return, Indirect pointer to the set of pages to be printed
STGMEDIUM *pstgmOptions,	// Pointer to object-specific printing options
IContinueCallback *pcallback,	// Pointer to callback interface
LONG nFirstPage,	// Number of first page to be printed
LONG *pcPagesPrinted,	// Pointer to total number of pages printed
LONG *pnLastPage	// Pointer to number of last page to be printed
);

Parameters

grfFlags

[in] A bit field whose values are taken from the enumeration PRINTFLAG.

pptd

[in, out]The target device on which the printing is to occur.

ppPageSet

[in, out] Indicates which pages are to be printed.

ppstgmOptions

[unique][in, out] Contains object-specific printing options in the form of a serialized OLE property set. May be NULL in one or both directions.

pCallback

[in] A callback interface which is to be periodically polled at human-response speeds to determine whether printing should be abandoned. May be NULL.

nFirstPage

[in] The page number of the first page to be printed. This value overrides any value previously passed to IPrint::SetInitialPageNum.

pcPagesPrinted

[out] The place at which the object is to return the actual number of pages that were successfully printed.

pnLastPage

[out] The place at which the object is to return the last legal page number.

Return Values

S_OK

Success

PRINT_E_CANCELED

The print process was canceled. *pcPagesPrinted indicates the number of pages that were in fact successfully printed before this error occurred.

PRINT_E_NOSUCHPAGE

An attempt has been made to print a page which does not exist.

E_UNEXPECTED

An unexpected error occurred.

Remarks

The printer on which the object is to be printed is indicated by the DVTARGETDEVICE structure in ptd. The DEVMODE structure in the target device indicates whole-job printer-specific options, such as number of copies, paper size, print quality, and other options. The DEVMODE structure may or may not also contain orientation information in the dmOrientation field (this is indicated in the dmFields field). If present, then this paper orientation should be used; if absent, then natural orientation as determined by the object content is to be used.

Due to the possibility of user input, the parameters pptd and ppPageSet are both [in,out] structures. In the absence of user interaction (that is, without PRINTFLAG_PROMPTUSER), both the target device and the page set will necessarily be the same for input and output. However, if the user is prompted for print options, then the object returns target device and page-set information appropriate to what the user has actually chosen.

The ppstgmOptions parameter is also [in,out]. On exit, the object should return through *ppstgmOptions any object-specific information that it would need to reproduce this exact print job. Examples might include whether the user selected “sheet, notes, or both” in a spreadsheet application. The data returned is in the format of a serialized property set. The returned data is normally useful only when passed back in a subsequent call to the same object. Because a subsequent call may specify different user interaction flags, target device, or other settings, the caller can cause the exact same document to be printed multiple times in slightly different printing contexts.

See Also

TBD