Functional specification
29
CDE/Motif PST
CDEnext
If
type
is
XPDocRaw
, then the client will provide all the data for the resulting document using
XpPutDocumentData
; the X Print Server will not write any data into the resulting document. Calling
XpStartPage
in a
XPDocRaw
document will generate a
XPBadSequence
error. For more
information, see
XpPutDocumentData
.
If
type
is
XPDocNormal
, then the X Print Server will generate document data, and depending on the
ddx driver, can incorporate additional data from
XpPutDocumentData
into the output. For more
information, see
XpPutDocumentData
.
The
XPDocumentType
values for
type
are defined in <
X11/extensions/Print.h
>:
#define XPDocNormal
1
/* Doc data handled by Xserver*/
#define XPDocRaw
2
/* Doc data passed through Xserver*/
XpEndDoc
signals the end of a print document. All resulting document data is assembled and combined
with data previously sent by
XpPutDocumentData
.
XpCancelDoc
cancels an in-progress document. If
save_data
to
XpStartJob
is
XPGetData
,
then data available to
XpGetDocumentData
is no longer guaranteed to be valid or recoverable for the
current job. If
save_data
to
XpStartJob
is
XPSpool
, then the X Print Server will discard
previously generated document data and reset in preparation for future documents. Depending on the
driver and spooler configuration, a partial page or document may be generated (e.g. the driver is directly
attached to a device, and cannot recall data).
Unlike
XpStartJob
,
XpEndJob
,
XpStartPage
and
XpEndPage
, an application is not required to
call
XpStartDoc
and
XpEndDoc
in the process of printing. The "document" delineation may not be
useful from the application's or spooler's perspective, hence is made optional. If
XpStartPage
is called
immediately after
XpStartJob
, then a synthetic
XpStartDoc
with
XPDocNormal
will be generated
by the X Print Server prior to
XpStartPage
(i.e.,
XPStartDocNotify
and
XPStartPageNotify
will have the same sequence number). Likewise, if
XpEndJob
is called immediately after
XpEndPage
,
then a synthetic
XpEndDoc
will be generated by the X Print Server prior to
XpEndJob
(i.e.,
XPEndDocNotify
and
XPEndJobNotify
will have the same sequence number).
All changes to the
XPDocAttr
attribute pool (see
XpSetAttributes
) must be made prior to calling
XpStartDoc
, after which a
XPBadSequence
will be generated if changes are attempted, until
XpEndDoc
is called.
For clients selecting
XPPrintMask
(see
XpSelectInput
), the event
XPPrintNotify
will be
generated with its detail field set to
XPStartDocNotify
or
XPEndDocNotify
when the X Print
Server has completed
XpStartDoc
and
XpEndDoc
respectively.
XPStartDocNotify
need not be received prior to calling
XpStartPage
.
For more information, see documentation on the Print Dialog Manager (PDM) and X Print Server Drivers.
Conceptually, a "Job" is a collection of "Documents", where each Document is in turn a collection of
"Pages". Depending on the print facilities underlying the X Print Server (for example, the Distributed
Print Management Facility (PDMF)), these delineations may be mapped by a ddx driver into real
functionality (e.g. see the server attribute
multiple-documents-supported
).
ERRORS/WARNINGS
These functions can generate one of the following errors: