DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

XpGetDocumentData(3)





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(3Xp), XpEndJob(3Xp), XpStartJob(3Xp)

X Version 11                      libXp 1.0.0           XpGetDocumentData(3Xp)

Man(1) output converted with man2html