--- name: "XpGetDocumentData" section: "3" platform: "linux" package: "libxp" version: "1.0.4-3" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/XpGetDocumentData" --- # XpGetDocumentData(3) Creates and initializes a new print context. ## NAME XpGetDocumentData - Creates and initializes a new print context. ## SYNOPSIS cc \[ flag... \] file... -lXp \[ library... \]\ \ \#include \ **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*; ## 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 continuously 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 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 initiated 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 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 finish\_proc as needed to consume incoming data. To avoid blocking indefinitely 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 finish\_proc is called and returns. ## STRUCTURES The save\_proc is defined in \ 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 \ 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 XPGetDocError. 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 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 \ 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 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, XpGetDocumentData prior to XpStartJob). ## SEE ALSO **XpCancelJob**(3Xp), **XpEndJob**(3Xp), **XpStartJob**(3Xp)