XpGetDocumentData(3Xp) XPRINT FUNCTIONS XpGetDocumentData(3Xp)
NAME
XpGetDocumentData - Creates and initializes a new print context.
SYNOPSIS
cc [ flag... ] file... -lXp [ library... ]
#include <X11/extensions/Print.h>
Status XpGetDocumentData ( data_display, context, save_proc, fin-
ish_proc, client_data )
Display *data_display;
XPContext context;
XPSaveProc save_proc;
XPFinishProc finish_proc;
XPointer client_data;
ARGUMENTS
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.
DESCRIPTION
XpGetDocumentData registers callbacks that allow a "consumer" to con-
tinuously retrieve document data generated 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 XpEnd-
Job. 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 out-
put_mode equal XPGetData, and is subsequently initiated when XpGetDocu-
mentData is called by the consumer. Though XpStartJob will return imme-
diately, further attempts to use the producer's display connection may
be blocked by the X Print Server until XpGetDocumentData is called on
the consumer's display connection.
Following a successful call to XpGetDocumentData, the consumer must
enter a loop to process events from the server, for example, by calling
XNextEvent. The event processing code will invoke save_proc and fin-
ish_proc as needed to consume incoming data. To avoid blocking indefi-
nitely in XNextEvent, the consumer should select for XPPrintNotify
events, and watch for XPEndJobNotify. This event will be sent following
the call to finish_proc and the consumer can safely exit the loop at
this point. Aside from this processing of XPrintNotify events,
data_display must not be used for any additional X requests until fin-
ish_proc is called and returns.
STRUCTURES
The save_proc is defined in <X11/extensions/Print.h> as:
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 gen-
erated 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 con-
text) that prove fatal to the progress of XpGetDocumentData will also
cause finish_proc to be called with a status of XPGetDocError.
If XpGetDocumentData is called prior to XpStartJob, then an XPBadSe-
quence 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 fin-
ish_proc is called with XPGetDocError. If the producer starts generat-
ing 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 completes successfully
(i.e. without being canceled or generating an error).
When finish_proc is called, sometime after XpGetDocumentData is called
and returns, status gives the completion 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 */
XPGetDocFinished indicates that all intended document data has been
delivered by way of save_proc. All cancellation 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.
DIAGNOSTICS
XPBadContext A valid print context-id has not been set prior to mak-
ing this call.
XPBadSequence The function was not called in the proper order with
respect to the other X Print Service Extension calls
(for example, XpGetDocumentData prior to XpStartJob).
SEE ALSO
XpCancelJob(3), XpEndJob(3), XpStartJob(3)
X Version 11 libXp 1.0.3 XpGetDocumentData(3Xp)
libXp 1.0.3 - Generated Mon Mar 23 07:56:03 CDT 2015