216 lines
8.5 KiB
Groff
216 lines
8.5 KiB
Groff
.\" $XdotOrg: xc/doc/man/Xp/XpGetDocumentData.man,v 1.1 2004/05/22 06:27:25 alanc Exp $
|
|
.\"
|
|
.\" Copyright 1996 Hewlett-Packard Company
|
|
.\" Copyright 1996 International Business Machines Corp.
|
|
.\" Copyright 1996, 1999, 2004 Sun Microsystems, Inc.
|
|
.\" Copyright 1996 Novell, Inc.
|
|
.\" Copyright 1996 Digital Equipment Corp.
|
|
.\" Copyright 1996 Fujitsu Limited
|
|
.\" Copyright 1996 Hitachi, Ltd.
|
|
.\" Copyright 1996 X Consortium, Inc.
|
|
.\"
|
|
.\" Permission is hereby granted, free of charge, to any person obtaining a
|
|
.\" copy of this software and associated documentation files (the "Software"),
|
|
.\" to deal in the Software without restriction, including without limitation
|
|
.\" the rights to use, copy, modify, merge, publish, distribute,
|
|
.\" sublicense, and/or sell copies of the Software, and to permit persons
|
|
.\" to whom the Software is furnished to do so, subject to the following
|
|
.\" conditions:
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall be
|
|
.\" included in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
.\" IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
|
|
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
|
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
|
|
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the names of the copyright holders
|
|
.\" shall not be used in advertising or otherwise to promote the sale, use
|
|
.\" or other dealings in this Software without prior written authorization
|
|
.\" from said copyright holders.
|
|
.\"
|
|
.TH XpGetDocumentData 3Xp __xorgversion__ "XPRINT FUNCTIONS"
|
|
.SH NAME
|
|
XpGetDocumentData \- Creates and initializes a new print context.
|
|
.SH SYNOPSIS
|
|
.br
|
|
cc [ flag... ] file... -lXp [ library... ]
|
|
.br
|
|
#include <X11/extensions/Print.h>
|
|
.LP
|
|
.B Status XpGetDocumentData
|
|
(
|
|
.I data_display,
|
|
.I context,
|
|
.I save_proc,
|
|
.I finish_proc,
|
|
.I client_data
|
|
)
|
|
.br
|
|
Display *\fIdata_display\fP\^;
|
|
.br
|
|
XPContext \fIcontext\fP\^;
|
|
.br
|
|
XPSaveProc \fIsave_proc\fP\^;
|
|
.br
|
|
XPFinishProc \fIfinish_proc\fP\^;
|
|
.br
|
|
XPointer \fIclient_data\fP\^;
|
|
.if n .ti +5n
|
|
.if t .ti +.5i
|
|
.SH ARGUMENTS
|
|
.TP
|
|
.I data_display
|
|
Specifies a pointer to the Display structure; returned from XOpenDisplay.
|
|
.TP
|
|
.I context
|
|
The print context from which document data is to be retrieved.
|
|
.TP
|
|
.I save_proc
|
|
A procedure to be registered and called repeatedly to save blocks of document
|
|
data.
|
|
.TP
|
|
.I 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.
|
|
.TP
|
|
.I client_data
|
|
Specifies client data to be passed to save_proc and finish_proc when called.
|
|
.SH DESCRIPTION
|
|
.LP
|
|
XpGetDocumentData registers callbacks that allow a "consumer" to continuously
|
|
retrieve document data generated in the
|
|
.I X Print Server
|
|
by a separate "producer",
|
|
where both are referencing the same print context by way of
|
|
.I 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
|
|
.I X Print Server
|
|
until XpGetDocumentData is called on the consumer's display connection.
|
|
|
|
Following a successful call to
|
|
.I 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.
|
|
|
|
.SH STRUCTURES
|
|
The save_proc is defined in <X11/extensions/Print.h> as:
|
|
.LP
|
|
.nf
|
|
typedef void (*XPSaveProc)( Display *data_display,
|
|
XPContext context,
|
|
unsigned char *data,
|
|
unsigned int data_len,
|
|
XPointer client_data);
|
|
.fi
|
|
|
|
.LP
|
|
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:
|
|
.LP
|
|
.nf
|
|
typedef void (*XPFinishProc)( Display *data_display,
|
|
XPContext context,
|
|
XPGetDocStatus status,
|
|
XPointer client_data);
|
|
.fi
|
|
.LP
|
|
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 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 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 generating data and the consumer cannot consume data
|
|
quickly enough, then the producer's display connection will be blocked by the
|
|
.I 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:
|
|
.LP
|
|
.nf
|
|
#define XPGetDocFinished 0 /\(** normal termination */
|
|
#define XPGetDocSecondConsumer 1 /\(** setup error */
|
|
#define XPGetDocError 2 /\(** progress error */
|
|
.fi
|
|
.LP
|
|
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
|
|
.I 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
|
|
.I X Print Server
|
|
to save_proc.
|
|
|
|
After finish_proc returns, save_proc and finish_proc are unregistered and will
|
|
no longer be called.
|
|
.SH DIAGNOSTICS
|
|
.TP 15
|
|
.SM XPBadContext
|
|
A valid print context-id has not been set prior to making this call.
|
|
.TP 15
|
|
.SM 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).
|
|
.SH "SEE ALSO"
|
|
.BR XpCancelJob (3Xp),
|
|
.BR XpEndJob (3Xp),
|
|
.BR XpStartJob (3Xp)
|
|
|
|
|