Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
XpGetDocumentData(3Xp)	       XPRINT FUNCTIONS		XpGetDocumentData(3Xp)

       XpGetDocumentData - Creates and initializes a new print context.

	     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;

	      Specifies	a pointer to  the  Display  structure;	returned  from

	      The print	context	from which document data is to be retrieved.

	      A	 procedure  to	be  registered	and  called repeatedly to save
	      blocks of	document data.

	      A	procedure to be	registered and called once when	the print  job
	      has completed and	all document data has been sent	to save_proc.

	      Specifies	 client	data to	be passed to save_proc and finish_proc
	      when called.

       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 re-
       trieves 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  ex-
       change  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 en-
       ter  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.

       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 it-
       self is owned by	the library, so	save_proc should copy data to  another
       location	before returning. After	the last block of data has been	deliv-
       ered 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, XP-
       BadContext 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  ac-
       tivities	(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 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 de-
       fined 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 de-
       livered	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  es-
       tablished  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.

       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 re-
		      spect  to	the other X Print Service Extension calls (for
		      example, XpGetDocumentData prior to XpStartJob).

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

X Version 11			  libXp	1.0.3		XpGetDocumentData(3Xp)


Want to link to this manual page? Use this URL:

home | help