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 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 <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 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 <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 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)