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, 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  some-
       time 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 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 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 finish_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  sta-
       tus.

       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 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 fin-
       ish_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 <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 docu-
       ment 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)

X Version 11							    libXp 1.0.0 					    XpGetDocumentData(3Xp)