XpGetDocumentData(3Xp)   XPRINT FUNCTIONS  XpGetDocumentData(3Xp)



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 "con-
       sumer" 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 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 con-
       sumer 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 docu-
       ment 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 call-
       backs, 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 fin-
       ish_proc to be called with a status of XPGetDocError.  Any
       other activities (for example, a separate process destroy-
       ing 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 gen-
       erating 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  con-
       sistency  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 XpGetDocument-
       Data 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  fin-
       ished_proc  is  called, and they should be taken into con-
       sideration 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)





X Version 11               libXp 1.0.0     XpGetDocumentData(3Xp)