X Version 11
Release 6.4
X Print Service Extension Library
17
typedef void (*XPSaveProc)( Display
*
data_display,
XPContext
context,
unsigned char
*
data,
unsigned int
data_len,
XPointer
client_data);
The save_proc is repeatedly called on each chunk of document data sent by the X Print Server until either
XpEndJob or XpCancelJob is called. data_len specifies the number of bytes in data. The memory for data itself
is owned by the library, so save_proc should copy data to another location before returning. After the last
block of data has been delivered to save_proc, finish_proc is called with final status.
The finish_proc is defined in <X11/extensions/Print.h> as:
typedef void (*XPFinishProc)( Display
*
data_display,
XPContext
context,
XPGetDocStatus
status,
XPointer
client_data);
After
XpGetDocumentData successfully registers the callbacks, any generated X errors (for example, BadAlloc)
or Xp errors (for example,
XPBadContext or XPBadSequence) that are the result of XpGetDocumentData will
cause the Xlib error handler to be invoked, and then will cause finish_proc to be called with a status of
XPGetDocError. Any other activities (for example, a separate process destroying the print context) that prove
fatal to the progress of
XpGetDocumentData will also cause finish_proc to be called with a status of XPGet-
DocError.
If
XpGetDocumentData is called prior to XpStartJob, then an XPBadSequence error is generated and finish_proc
is called with
XPGetDocError. If XpGetDocumentData is called after XpStartJob and output_mode was specified
as
XPSpool, then an XPBadSequence error is generated and finish_proc is called with XPGetDocError. If the
producer starts generating data and the consumer cannot consume data quickly enough, then the producer's
display connection will be blocked by the X Print Server.
Until
XpEndJob or XpCancelJob is called, it is possible that various XPPrintNotify events will be generated (for
example, a page has been canceled). The data passed to save_proc is not necessarily organized according to
the consumer's requests or any generated events, and its consistency is guaranteed only if the entire job com-
pletes successfully (i.e. without being canceled or generating an error). Consumers may want to select for
XPPrintNotify events and terminate save processing upon receipt of cancellation events.
When finish_proc is called, sometime after
XpGetDocumentData is called and returns, status gives the com-
pletion status of the job and is defined in <X11/extensions/Print.h> as:
#define XPGetDocFinished
0
/* normal termination */
#define XPGetDocSecondConsumer
1
/* setup error */
#define XPGetDocError
2
/* progress error */
XPGetDocFinshed indicates that all intended document data has been delivered by way of save_proc. All can-
cellation events are guaranteed to have arrived by the time finished_proc is called, and they should be taken
into consideration for evaluating the validity of the document data returned.
XPGetDocSecondConsumer indicates that a consumer had already been established for the print context. The
X Print Server only supports one consumer per print context.
XPGetDocError indicates that an error has been generated (for example, XPBadContext or XPBadSequence) and
that no further document data will be delivered by the X Print Server to save_proc.
After finish_proc returns, save_proc and finish_proc are unregistered and will no longer be called.
XpGetDocumentData can generate one of the following errors:
XPBadContext
The specified print context-id is not valid.