16
December 15, 1997
X Print Service Extension Library
16
X Print Service Extension Library
Release 6.4
X Version 11
Depending on the DDX driver implementation in use,
XpPutDocumentData might be used, for example, to
send a simple text file to a Postscript DDX driver that is capable of wrapping the appropriate document and
page control constructs around the text so that it can be printed on a Postscript printer. Likewise, Encapsu-
lated Postscript Files might be handled. Another use could be to send a TIFF file to a PCL DDX driver that
can convert the image from TIFF into PCL and then integrate it into the current PCL output.
There is no limit to the value of data_len.
XpPutDocumentData automatically decomposes the call into multi-
ple protocol requests to make sure that the maximum request size of the server is not exceeded.
XpPutDocumentData can generate one of the following errors:
XPBadContext
A valid print context-id has not been set prior to making this call.
XPBadSequence
The function was not called in the proper order with respect to the other X Print
Service Extension calls (for example,
XpPutDocumentData prior to XpStartDoc).
BadValue
The value specified for doc_fmt is not supported.
BadMatch
The value specified for doc_fmt is not valid for the current document type or the
value specified for drawable is not valid for the print context and print screen.
BadDrawable
The value specified for drawable is not valid.
Use
XpGetDocumentData to setup callbacks to retrieve document data from a print context.
Status XpGetDocumentData (data_display, context, save_proc, finish_proc, client_data)
Display *data_display;
XPContext context;
XPSaveProc save_proc;
XPFinishProc finish_proc;
XPointer client_data;
data_display
Specifies a pointer to the Display structure; returned from XOpenDisplay.
context
The print context from which document data is to be retrieved.
save_proc
A procedure to be registered and called repeatedly to save blocks of document data.
finish_proc
A procedure to be registered and called once when the print job has completed and all
document data has been sent to save_proc
.
client_data
Specifies client data to be passed to save_proc and finish_proc when called.
The return value is
NULL if XpGetDocumentData encounters an error, non-NULL otherwise.
XpGetDocumentData registers callbacks that allow a "consumer" to continuously retrieve document data gen-
erated in the X Print Server by a separate "producer", where both are referencing the same print context by
way of different display connections. Though
XpGetDocumentData retrieves document data, its effect is
bounded by
XpStartJob and XpEndJob. XpGetDocumentData always returns immediately; if an error occurs and
the callbacks cannot be registered, the return status is 0, else the return status is non-zero and the callbacks
will be called sometime after the return from
XpGetDocumentData. This producer/consumer exchange is set
up when
XpStartJob is called by the producer with output_mode equal XPGetData, and is subsequently initi-
ated when
XpGetDocumentData is called by the consumer. Though XpStartJob will return immediately, further
attempts to use the producer's display connection may be blocked by the X Print Server until
XpGetDocu-
mentData is called on the consumer's display connection.
Once
XpGetDocumentData is called on data_display, data_display cannot be used for any additional X
requests until finish_proc is called and returns. Further, data_display cannot be closed from within save_proc
or finish_proc. To avoid deadlock, the producer and consumer must run in separate processes, or in separate
threads of a single process.
The save_proc is defined in <X11/extensions/Print.h> as: