@node Functions, Programs, Integrating libgimpprint, Top
@chapter Functions
@cindex functions

This section of the manual is a complete reference to all of the functions
comprising libgimpprint, with examples.

All of the libgimpprint functions can be declared by including the master
libgimpprint header, @file{<gimp-print/gimp-print.h>}.  This should be done in
every source file that uses gimpprint functions by putting

@example
#include <gimp-print/gimp-print.h>
@end example

@noindent
at the top of each file.

@menu
* Main functions::              Essential functions every program must call.
* stp_vars_t functions::        Using stp_vars_t.
* Dither functions::            Dither algorithms.
* Options functions::           Options.
* Paper functions::             Paper size and orientation.
* Printer functions::           Printer selection.
* Settings functions::          Getting and changing settings.
* Version functions::           Getting libgimpprint version information.
@end menu

@node Main functions, stp_vars_t functions, , Functions
@section Main functions
@cindex main functions

These functions are essential to the correct functioning of
libgimpprint.  All or most other functions in the library depend
absolutely upon them.  In the case of @code{stp_init}, this function
@emph{must} be called before any of the other functions in the library.


@cindex initialising libgimpprint
@deftypefun int stp_init (void)

This function initialises the libgimpprint library. It must be called before
any of the other libgimpprint functions are called. It is responsible for
setting up message catalogues (for internationalisation). This function
may be called more than once, at any stage during the execution of a
program.

It returns zero on success, nonzero on failure.
@end deftypefun

@code{stp_init} might be used as follows:

@example
int
main (int argc, char **argv)
@{
  stp_init();

  @dots{}

@}
@end example

@cindex memory allocation
@deftypefun {void *} stp_malloc (size_t @var{size})

Where @var{size} is the amount of memory to allocate (in bytes).

This function allocates memory. It will always return a pointer to the
allocated memory. It will not return on failure.

It returns a pointer to the allocated memory.
@end deftypefun

@node stp_vars_t functions, Dither functions, Main functions, Functions
@section @code{stp_vars_t} functions
@cindex @code{stp_vars_t} functions

@deftypevr {Data type} {void *} stp_vars_t
This is an opaque data type, whose structure is not visible to the
user.  This object contains all of the information about settings for
a given printer, such as color (contrast, brightness), the type of
printer, the dithering algorithm in use, and so forth.  Please see the
@code{stp_set_*} and @code{stp_get_*} functions below for the
accessors and mutators for this data type.
@end deftypevr


@deftypefun stp_vars_t stp_allocate_vars (void)
Allocate a new @code{stp_vars_t} with default settings for all members.
@end deftypefun

@deftypefun void stp_copy_vars (stp_vars_t @var{vd}, const stp_vars_t @var{vs})
Copy the settings from @var{vs} to @var{vd}.
@end deftypefun

@deftypefun stp_vars_t stp_allocate_copy (const stp_vars_t @var{vs})
Allocate a new @code{stp_vars_t}, copying settings from @var{vs}.
@end deftypefun

@deftypefun void stp_free_vars (stp_vars_t @var{vv})
Free all resources associated with @var{vv}.  @var{vv} must not be
used in any way following this call.
@end deftypefun

@deftypefun {const char *} stp_get_output_to (const stp_vars_t @var{vv})
@deftypefunx void stp_set_output_to (stp_vars_t @var{vv}, const char *@var{val})
@deftypefunx void stp_set_output_to_n (stp_vars_t @var{vv}, const char *@var{val}, int @var{bytes})
Get or set the name of the command that this job will be printed to.
This is used by front ends; the driver library always prints to a
stream provided by the front end and never uses this directly.
@end deftypefun

@deftypefun {const char *} stp_get_driver (const stp_vars_t @var{vv})
@deftypefunx void stp_set_driver (stp_vars_t @var{vv}, const char *@var{val})
@deftypefunx void stp_set_driver_n (stp_vars_t @var{vv}, const char *@var{val}, int @var{bytes})
Get or set the name of the driver (the type of printer).
@end deftypefun

@deftypefun {const char *} stp_get_ppd_file (const stp_vars_t @var{vv})
@deftypefunx void stp_set_ppd_file (stp_vars_t @var{vv}, const char *@var{val})
@deftypefunx void stp_set_ppd_file_n (stp_vars_t @var{vv}, const char *@var{val}, int @var{bytes})
Get or set the name of the PPD file used by this print job.  Normally,
only PostScript printers use PPD files.
@end deftypefun

@deftypefun {const char *} stp_get_resolution (const stp_vars_t @var{vv})
@deftypefunx void stp_set_resolution (stp_vars_t @var{vv}, const char *@var{val})
@deftypefunx void stp_set_resolution_n (stp_vars_t @var{vv}, const char *@var{val}, int @var{bytes})
Get or set the resolution to be used in this print job.  Different
drivers support different resolutions, and many drivers support
multiple quality settings for a given DPI resolution.
@end deftypefun

@deftypefun {const char *} stp_get_media_size (const stp_vars_t @var{vv})
@deftypefunx void stp_set_media_size (stp_vars_t @var{vv}, const char *@var{val})
@deftypefunx void stp_set_media_size_n (stp_vars_t @var{vv}, const char *@var{val}, int @var{bytes})
Get or set the name of the media size (e. g. A3, letter, legal) to be
used in this print job.
@end deftypefun

@deftypefun {const char *} stp_get_media_type (const stp_vars_t @var{vv})
@deftypefunx void stp_set_media_type (stp_vars_t @var{vv}, const char *@var{val})
@deftypefunx void stp_set_media_type_n (stp_vars_t @var{vv}, const char *@var{val}, int @var{bytes})
Get or set the name of the media type (e. g. plain paper, photo
quality inkjet paper) to be used in this print job.
@end deftypefun

@deftypefun {const char *} stp_get_media_source (const stp_vars_t @var{vv})
@deftypefunx void stp_set_media_source (stp_vars_t @var{vv}, const char *@var{val})
@deftypefunx void stp_set_media_source_n (stp_vars_t @var{vv}, const char *@var{val}, int @var{bytes})
Get or set the name of the media source (e. g. manual feed, tray A) to
be used in this print job.
@end deftypefun

@deftypefun {const char *} stp_get_ink_type (const stp_vars_t @var{vv})
@deftypefunx void stp_set_ink_type (stp_vars_t @var{vv}, const char *@var{val})
@deftypefunx void stp_set_ink_type_n (stp_vars_t @var{vv}, const char *@var{val}, int @var{bytes})
Get or set the name of the ink type (e. g. four color standard, six
color photo) to be used in this print job.
@end deftypefun

@deftypefun {const char *} stp_get_dither_algorithm (const stp_vars_t @var{vv})
@deftypefunx void stp_set_dither_algorithm (stp_vars_t @var{vv}, const char *@var{val})
@deftypefunx void stp_set_dither_algorithm_n (stp_vars_t @var{vv}, const char *@var{val}, int @var{bytes})
Get or set the dither algorithm to be used in this print job.
@end deftypefun

@deftypefun int stp_get_output_type (const stp_vars_t @var{vv})
@deftypefunx void stp_set_output_type (stp_vars_t @var{vv}, int @var{val})
Get or set the output type (color, grayscale, black and white) for
this print job.
@end deftypefun

@deftypefun int stp_get_orientation (const stp_vars_t @var{vv})
@deftypefunx void stp_set_orientation (stp_vars_t @var{vv}, int @var{val})
Get or set the paper orientation for this print job.
@end deftypefun

@deftypefun int stp_get_left (const stp_vars_t @var{vv})
@deftypefunx void stp_set_left (stp_vars_t @var{vv}, int @var{val})
Get or set the left margin (in 1/72 inch units, or "points") for this
print job.
@end deftypefun

@deftypefun int stp_get_top (const stp_vars_t @var{vv})
@deftypefunx void stp_set_top (stp_vars_t @var{vv}, int @var{val})
Get or set the top margin (in 1/72 inch units, or "points") for this
print job.
@end deftypefun

@deftypefun int stp_get_image_type (const stp_vars_t @var{vv})
@deftypefunx void stp_set_image_type (stp_vars_t @var{vv}, int @var{val})
Get or set the image type (line art, continuous tone, solid colors)
for this print job.
@end deftypefun

@deftypefun int stp_get_unit (const stp_vars_t @var{vv})
@deftypefunx void stp_set_unit (stp_vars_t @var{vv}, int @var{val})
Get or set the base unit (inches or centimeters) for this print job.
This is provided for front ends; the package itself uses points as its
unit of measurement.
@end deftypefun

@deftypefun int stp_get_page_width (const stp_vars_t @var{vv})
@deftypefunx void stp_set_page_width (stp_vars_t @var{vv}, int @var{val})
Get or set the width of the printed region of the page.
@end deftypefun

@deftypefun int stp_get_page_height (const stp_vars_t @var{vv})
@deftypefunx void stp_set_page_height (stp_vars_t @var{vv}, int @var{val})
Get or set the height of the printed region of the page.
@end deftypefun

@deftypefun int stp_get_input_color_model (const stp_vars_t @var{vv})
@deftypefunx void stp_set_input_color_model (stp_vars_t @var{vv}, int @var{val})
Get or set the color model (currently RGB or CMY) of the input to the
driver.  Most front ends will use RGB input.
@end deftypefun

@deftypefun int stp_get_output_color_model (const stp_vars_t @var{vv})
@deftypefunx void stp_set_output_color_model (stp_vars_t @var{vv}, int @var{val})
Get or set the color model (currently RGB or CMY) of the output of the
driver.  Most printers will use CMY.
@end deftypefun

@deftypefun float stp_get_scaling (const stp_vars_t @var{vv})
@deftypefunx void stp_set_scaling (stp_vars_t @var{vv}, float @var{val})
Get or set the scaling factor of the image.  If the scaling factor is
greater than 0, it is interpreted as a percent (5.0-100.0 is the valid
range) of the printable page region, using the more restrictive axis.
For example, if the image to be printed should be 3" (wide) x 2"
(high), and the printable page region is 8"x10.5", the scale factor
should be 37.5 (3"/8").

If the scaling is less than zero, it is interpreted as pixels per
inch.

It is likely that in the future this will be migrated into the front
end.  There is no particular reason why the driver needs to know about
this.
@end deftypefun

@deftypefun float stp_get_gamma (const stp_vars_t @var{vv})
@deftypefunx void stp_set_gamma (stp_vars_t @var{vv}, float @var{val})
Get or set the gamma of the print job (valid range: 0.1-4.0; default
1.0).  Note that this is not the absolute gamma used by the print job;
it is scaled by the gamma appropriate for the printer.  This is true
for all of the numerical parameters.
@end deftypefun

@deftypefun float stp_get_brightness (const stp_vars_t @var{vv})
@deftypefunx void stp_set_brightness (stp_vars_t @var{vv}, float @var{val})
Get or set the brightness of the print job (valid range: 0.0-2.0;
default: 1.0).  Any value other than 1.0 will result in some possible
values not being used; if brightness is less than 1.0, no output point
will be pure white, and if brightness is greater than 1.0, no output
point will be pure black (or cyan, or magenta, or yellow).
@end deftypefun

@deftypefun float stp_get_contrast (const stp_vars_t @var{vv})
@deftypefunx void stp_set_contrast (stp_vars_t @var{vv}, float @var{val})
Get or set the contrast of the print job (valid range: 0.0-4.0;
default: 1.0).  Values less than 1.0 will result in pure white or
black not being used (0.0 will make the entire image 50% gray).
Values greater than 1.0 do not hard clip; while the contrast in the
midtones increases, it only asymptotically approaches the limits.
@end deftypefun

@deftypefun float stp_get_cyan (const stp_vars_t @var{vv})
@deftypefunx void stp_set_cyan (stp_vars_t @var{vv}, float @var{val})
Get or set the cyan adjustment of the print job (range: 0.0-4.0; default:
1.0).  This currently adjusts the gamma of the cyan curve.  It is
scaled by the cyan adjustment for the printer model in question.
@end deftypefun

@deftypefun float stp_get_magenta (const stp_vars_t @var{vv})
@deftypefunx void stp_set_magenta (stp_vars_t @var{vv}, float @var{val})
Get or set the magenta adjustment of the print job (range: 0.0-4.0; default:
1.0).  This currently adjusts the gamma of the magenta curve.  It is
scaled by the magenta adjustment for the printer model in question.
@end deftypefun

@deftypefun float stp_get_yellow (const stp_vars_t @var{vv})
@deftypefunx void stp_set_yellow (stp_vars_t @var{vv}, float @var{val})
Get or set the yellow adjustment of the print job (range: 0.0-4.0; default:
1.0).  This currently adjusts the gamma of the yellow curve.  It is
scaled by the yellow adjustment for the printer model in question.
@end deftypefun

@deftypefun float stp_get_saturation (const stp_vars_t @var{vv})
@deftypefunx void stp_set_saturation (stp_vars_t @var{vv}, float @var{val})
Get or set the saturation of the print job (range: 0.0-9.0; default: 1.0).
Saturation of 0.0 produces grayscale output using composite (CMY or
CMYK, as appropriate for the printer) color.
@end deftypefun

@deftypefun float stp_get_density (const stp_vars_t @var{vv})
@deftypefunx void stp_set_density (stp_vars_t @var{vv}, float @var{val})
Get or set the density of the print job (range: 0.0-2.0; default:
1.0).  This adjusts the amount of ink deposited in a linear fashion
for all channels.  It is scaled by the density appropriate for the
choice of printer, resolution, paper type, and other factors that the
driver may deem appropriate.
@end deftypefun

@deftypefun float stp_get_app_gamma (const stp_vars_t @var{vv})
@deftypefunx void stp_set_app_gamma (stp_vars_t @var{vv}, float @var{val})
Get or set the gamma of the input (i. e. what the driving application
uses).
@end deftypefun

@deftypefun {void *} stp_get_lut (const stp_vars_t @var{vv})
@deftypefunx void stp_set_lut (stp_vars_t @var{vv}, void *@var{val})
Get or set the color lookup table for the print job.  This is useful
outside of the library for computing a preview of the printed result.
The lookup table itself should be treated as an opaque handle.
@end deftypefun

@deftypefun {unsigned char *} stp_get_cmap (const stp_vars_t @var{vv})
@deftypefunx void stp_set_cmap (stp_vars_t @var{vv}, unsigned char *@var{val})
Get or set the color map for the print job.  This is a table of R,G,B
values for 8-bit indexed input.  This may be moved outside of the
library in the future; in this case, the front end would be required
to do its own mapping and supply true-color RGB to the driver.
@end deftypefun

The following methods are used to perform output and error reporting
by the driver.  The driver supplies a stream of output bytes; the
front end is responsible for providing methods that accept this output
and handle it appropriately.

@deftypefun stp_outfunc_t stp_get_outfunc (const stp_vars_t @var{vv})
@deftypefunx void stp_set_outfunc (const stp_vars_t @var{vv}, stp_outfunc_t @var{val})
@deftypefunx {void *} stp_get_outdata (const stp_vars_t @var{vv})
@deftypefunx void stp_set_outdata (stp_vars_t @var{vv}, void *@var{val})

@deftypevr {Data type} {} stp_outfunc_t
@example
typedef void (*stp_outfunc_t) (void *data,
              const char *buffer, size_t bytes);
@end example
@end deftypevr
Get or set the output function the driver will use.  The front end
must supply a suitable function for accepting the output data.  The
@code{stp_set_outdata} method provides a way of passing an appropriate
object to the output function.
@end deftypefun

@deftypefun stp_outfunc_t stp_get_errfunc (const stp_vars_t @var{vv})
@deftypefunx void stp_set_errfunc (const stp_vars_t @var{vv}, stp_outfunc_t @var{val})
@deftypefunx {void *} stp_get_errdata (const stp_vars_t @var{vv})
@deftypefunx void stp_set_errdata (stp_vars_t @var{vv}, void *@var{val})
Get or set the error reporting function that the driver will use.
This is used to report errors or debugging information, and must be
supplied.  A typical errfunc will simply print whatever it's passed to
stderr.
@end deftypefun

/*
 * hue_map is an array of 49 doubles representing the mapping of hue
 * from (0..6) to (0..6) in increments of .125.  The hue_map is in CMY space,
 * so hue=0 is cyan.
 */
typedef void (*stp_convert_t)(const stp_vars_t vars, const unsigned char *in,
                              unsigned short *out, int *zero_mask,
                              int width, int bpp, const unsigned char *cmap,
                              const double *hue_map, const double *lum_map,
                              const double *sat_map);

@deftypefun void stp_merge_printvars (stp_vars_t @var{user}, const stp_vars_t @var{print})

@end deftypefun

@deftypefun void stp_allocate_lut (stp_vars_t @var{v}, size_t @var{steps})

@end deftypefun

@deftypefun void stp_free_lut (stp_vars_t @var{v})

@end deftypefun

@deftypefun void stp_compute_lut (stp_vars_t @var{v}, size_t @var{steps})

@end deftypefun


@node Dither functions, Options functions, stp_vars_t functions, Functions
@section Dither functions
@cindex dither functions

@deftypefun size_t stp_dither_algorithm_count (void)

@end deftypefun

@deftypefun {const char *} stp_dither_algorithm_name (int @var{id})

@end deftypefun

@deftypefun {const char *} stp_default_dither_algorithm (void)

@end deftypefun



@node Options functions, Paper functions, Dither functions, Functions
@section Options functions
@cindex options functions

@deftypevr {Data type} {void *} stp_option_t
This is an opaque data type, whose structure is not visible to the
user.
@end deftypevr

@deftypefun void stp_set_option(stp_vars_t @var{v}, const char *@var{name}, const char *@var{data}, int @var{bytes})

@end deftypefun

@deftypefun void stp_clear_option (stp_vars_t @var{v}, const char *@var{name})

@end deftypefun

@deftypefun void stp_clear_all_options (stp_vars_t @var{v})

@end deftypefun

@deftypefun size_t stp_option_count (const stp_vars_t @var{v})

@end deftypefun

@deftypefun {const stp_option_t} stp_get_option_by_index (const stp_vars_t @var{v}, size_t @var{idx})

@end deftypefun

@deftypefun {const stp_option_t} stp_get_option_by_name (const stp_vars_t @var{v}, const char *@var{name})

@end deftypefun

@deftypefun {const char *} stp_option_data (const stp_option_t @var{option})
@strong{Note}: not null delimited!
@end deftypefun

@deftypefun {const char *} stp_option_name (const stp_option_t @var{option})

@end deftypefun

@deftypefun size_t stp_option_length (const stp_option_t @var{option})

@end deftypefun


@node Paper functions, Printer functions, Options functions, Functions
@section Paper functions
@cindex paper functions

@deftypevr {Data type} {void *} stp_papersize_t
This is an opaque data type, whose structure is not visible to the
user.
@end deftypevr

@deftypevr {Data type} {} stp_papersize_unit_t
@example
typedef enum papersize_unit
@{
  PAPERSIZE_ENGLISH,
  PAPERSIZE_METRIC
@} stp_papersize_unit_t;
@end example
@end deftypevr

@deftypefun int stp_known_papersizes (void)

@end deftypefun

@deftypefun {const stp_papersize_t} stp_get_papersize_by_name (const char *@var{name})

@end deftypefun

@deftypefun {const stp_papersize_t} stp_get_papersize_by_size (int @var{l}, int @var{w})

@end deftypefun

@deftypefun {const stp_papersize_t} stp_get_papersize_by_index (int @var{index})

@end deftypefun

@deftypefun {const char *} stp_papersize_get_name (const stp_papersize_t @var{pt})

@end deftypefun

@deftypefun unsigned stp_papersize_get_width (const stp_papersize_t @var{pt})

@end deftypefun

@deftypefun unsigned stp_papersize_get_height (const stp_papersize_t @var{pt})

@end deftypefun

@deftypefun unsigned stp_papersize_get_top (const stp_papersize_t @var{pt})

@end deftypefun

@deftypefun unsigned stp_papersize_get_left (const stp_papersize_t @var{pt})

@end deftypefun

@deftypefun unsigned stp_papersize_get_bottom (const stp_papersize_t @var{pt})

@end deftypefun

@deftypefun unsigned stp_papersize_get_right (const stp_papersize_t @var{pt})

@end deftypefun


@deftypefun stp_papersize_unit_t stp_papersize_get_unit (const stp_papersize_t @var{pt})

@end deftypefun


@node Printer functions, Settings functions, Paper functions, Functions
@section Printer functions
@cindex printer functions

@deftypevr {Data type} {void *} stp_printer_t
This is an opaque data type, whose structure is not visible to the
user.
@end deftypevr

@deftypefun int stp_known_printers (void)

@end deftypefun


@deftypefun {const stp_printer_t} stp_get_printer_by_index (int @var{idx})

@end deftypefun


@deftypefun {const char *} stp_printer_get_long_name (const stp_printer_t @var{p})

@end deftypefun


@deftypefun {const stp_printer_t} stp_get_printer_by_long_name (const char *@var{long_name})

@end deftypefun


@deftypefun {const stp_printer_t} stp_get_printer_by_driver (const char *@var{driver})

@end deftypefun


@deftypefun int stp_get_printer_index_by_driver (const char *@var{driver})

@end deftypefun


@deftypefun {const char *} stp_printer_get_driver (const stp_printer_t @var{p})

@end deftypefun


@deftypefun int stp_printer_get_model (const stp_printer_t @var{p})

@end deftypefun


@deftypefun {const stp_printfuncs_t *} stp_printer_get_printfuncs (const stp_printer_t @var{p})

@end deftypefun

@deftypevr {Data type} {} stp_printfuncs_t
@example
typedef struct
@{
  char  **(*parameters)(const stp_printer_t printer,
                        const char *ppd_file,
                        const char *name, int *count);
  void  (*media_size)(const stp_printer_t printer,
                      const stp_vars_t v, int *width,
                      int *height);
  void  (*imageable_area)(const stp_printer_t printer,
                          const stp_vars_t v,
                          int *left, int *right,
                          int *bottom, int *top);
  void  (*limit)(const stp_printer_t printer,
                 const stp_vars_t v,
                 int *width, int *height);
  void  (*print)(const stp_printer_t printer,
                 stp_image_t *image, const stp_vars_t v);
  const char *(*default_parameters)(const stp_printer_t printer,
                                    const char *ppd_file,
                                    const char *name);
  void  (*describe_resolution)(const stp_printer_t printer,
                               const char *resolution,
                               int *x, int *y);
  int   (*verify)(const stp_printer_t p, const stp_vars_t v);
@} stp_printfuncs_t;
@end example
@end deftypevr

@deftypevr {Data type} {} stp_image_t
@example
typedef struct stp_image
@{
  void (*init)(struct stp_image *image);
  void (*reset)(struct stp_image *image);
  void (*transpose)(struct stp_image *image);
  void (*hflip)(struct stp_image *image);
  void (*vflip)(struct stp_image *image);
  void (*crop)(struct stp_image *image,
               int left, int top, int right,
               int bottom);
  void (*rotate_ccw)(struct stp_image *image);
  void (*rotate_cw)(struct stp_image *image);
  void (*rotate_180)(struct stp_image *image);
  int  (*bpp)(struct stp_image *image);
  int  (*width)(struct stp_image *image);
  int  (*height)(struct stp_image *image);
  void (*get_row)(struct stp_image *image,
        unsigned char *data, int row);
  const char *(*get_appname)(struct stp_image *image);
  void (*progress_init)(struct stp_image *image);
  void (*note_progress)(struct stp_image *image,
        double current, double total);
  void (*progress_conclude)(struct stp_image *image);
  void *rep;
@} stp_image_t;
@end example
This is an abstract data type for interfacing with the program which
created the image.
@end deftypevr

@deftypefun {const stp_vars_t} stp_printer_get_printvars (const stp_printer_t @var{p})

@end deftypefun


@node Settings functions, Version functions, Printer functions, Functions
@section Settings functions
@cindex settings functions

@deftypefun stp_convert_t stp_choose_colorfunc (int @var{output_type}, int @var{image_bpp}, const unsigned char *@var{cmap}, int *@var{out_bpp}, const stp_vars_t @var{v})

@end deftypefun


@deftypefun void stp_compute_page_parameters (int @var{page_right}, int @var{page_left}, int @var{page_top}, int @var{page_bottom}, double @var{scaling}, int @var{image_width}, int @var{image_height}, stp_image_t *@var{image}, int *@var{orientation}, int *{page_width}, int *@var{page_height}, int *@var{out_width}, int *@var{out_height}, int *@var{left}, int *@var{top})

@end deftypefun


@deftypefun {const stp_vars_t} stp_default_settings (void)

@end deftypefun


@deftypefun {const stp_vars_t} stp_maximum_settings (void)

@end deftypefun


@deftypefun {const stp_vars_t} stp_minimum_settings (void)

@end deftypefun




@node Version functions, , Settings functions, Functions
@section Version functions
@cindex version functions

@deftypefun {const char *} stp_check_version (unsigned int @var{required_major},
unsigned int @var{required_minor}, unsigned int @var{required_micro})

This function checks whether the version of libgimpprint that the program
is linked with is equal to the version number passed to it. If the version
is the same, the function returns @code{NULL}. If any of the version
numbers do not match (i.e. the library version is too old or too new), a string containing a desription of the difference is
returned. The first error found is returned. The function checks in the order
major, minor, micro.
@end deftypefun

@subsection Version macros

@defmac GIMPPRINT_CHECK_VERSION (major,minor,micro)

This macro returns zero if the version of the libgimpprint headers are
greater or equal to the version given as an argument. It returns nonzero
if the version of the libgimpprint headers are less than the argument.
@end defmac

@defmac GIMPPRINT_MAJOR_VERSION
@end defmac

@defmac GIMPPRINT_MINOR_VERSION
@end defmac

@defmac GIMPPRINT_MICRO_VERSION
@end defmac

@defmac GIMPPRINT_CURRENT_INTERFACE
@end defmac

@defmac GIMPPRINT_BINARY_AGE
@end defmac

@defmac GIMPPRINT_INTERFACE_AGE
@end defmac

These macros are integers holding the version numbers. They should be
used for compile-time checking only. To check version numbers at
run-time, use the equivalent variables. Note that at present (4.1.x
development branch) the library interface version numbers are not used.

@subsection Version variables

@deftypevar {const unsigned int} gimpprint_major_version
@end deftypevar

@deftypevar {const unsigned int} gimpprint_minor_version
@end deftypevar

@deftypevar {const unsigned int} gimpprint_micro_version
@end deftypevar

@deftypevar {const unsigned int} gimpprint_current_interface
@end deftypevar

@deftypevar {const unsigned int} gimpprint_binary_age
@end deftypevar

@deftypevar {const unsigned int} gimpprint_interface_age
@end deftypevar

These variables hold the library version numbers. Because the version of
the library may change on a system using shared libraries, these should
be used instead of the equivalent macros when checking the library
version at run-time. Note that library interface version numbers are not
used in the development branch, but are in the stable branch.
