Manual Pages for UNIX Operating System command usage for man XpGetDocumentData

XPRINT FUNCTIONS                           XpGetDocumentData(3Xp)



NAME
     XpGetDocumentData - Creates and initializes a new print con-
     text.

SYNOPSIS
     cc [ flag... ] file... -lXp [ library... ]
           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  "consu-
     mer" 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



X Version 11        Last change: libXp 1.0.0                    1






XPRINT FUNCTIONS                           XpGetDocumentData(3Xp)



     equal XPGetData, and is subsequently initiated when XpGetDo-
     cumentData 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 consu-
     mer 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  XPrintNo-
     tify  events,  data_display  must  not be used for any addi-
     tional 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 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  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 finish_proc to be
     called  with a status of XPGetDocError. Any other activities



X Version 11        Last change: libXp 1.0.0                    2






XPRINT FUNCTIONS                           XpGetDocumentData(3Xp)



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



X Version 11        Last change: libXp 1.0.0                    3






XPRINT FUNCTIONS                           XpGetDocumentData(3Xp)



                    prior to making this call.

     XPBadSequence  The function was not  called  in  the  proper
                    order  with respect to the other X Print Ser-
                    vice Extension calls (for example, XpGetDocu-
                    mentData prior to XpStartJob).

SEE ALSO
     XpCancelJob(3Xp), XpEndJob(3Xp), XpStartJob(3Xp)




ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | x11/library/libxp           |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | See XInitThreads(3X11)      |
    |_____________________________|_____________________________|





























X Version 11        Last change: libXp 1.0.0                    4