This manual page is for Mac OS X version 10.6.3

Reading manual pages

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 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 XpGetDocu-mentData XpGetDocumentData
       mentData 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 destroy-ing destroying
       ing the print context) that prove fatal to the progress of XpGetDocumentData  will  also  cause  fin-ish_proc finish_proc
       ish_proc to be called with a status of XPGetDocError.

       If XpGetDocumentData is called prior to XpStartJob, then an XPBadSequence error is generated and fin-ish_proc finish_proc
       ish_proc is called with XPGetDocError. If XpGetDocumentData  is  called  after  XpStartJob  and  out-put_mode output_mode
       put_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 guar-anteed guaranteed
       anteed 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 Ser-vice Service
                      vice 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)