PDFindPageSize(3)

NAME
     PDFindPageSize, PDGetSizeCodeByName, PDGetNameBySizeCode - page size
     convenience functions

SYNOPSIS
     #include <pod.h>

     PDSizeTableStruct* PDFindPageSize(PDInfoStruct *info,
                                       int size_code);

     int PDGetSizeCodeByName(char *size_name);

     char* PDGetNameBySizeCode(int size_code);

DESCRIPTION
     PDFindPageSize, PDGetSizeCodeByName and PDGetNameBySizeCode are
     convenience functions for specifying and querying page size information.

     PDFindPageSize is a convenience function for determining whether a given
     media size is supported on a given printer. This function is especially
     useful for obtaining information about the currently loaded media.

     PDFindPageSize searches the page size table of the specified PDInfoStruct
     for the page size specified by size_code. info may be obtained with a
     call to either PDLocalReadInfo or PDReadInfo. The values for size_code
     are all designated PD_SIZE_[size name] and can be found in pod.h.  Of
     particular interest is the value PD_SIZE_CURRENT. Specifying this value
     returns the currently loaded media size information.

     Often a page size is provided to an application as a name (e.g. "A4").
     However, most libpod functions require a page size code rather than a
     page name string. The PDGetSizeCodeByName function provides the page size
     code corresponding to the specified page size name. The complete list of
     page size names and codes can be found in pod.h.

     The PDGetNameBySizeCode function performs the inverse operation of
     PDGetSizeCodeByName. The page size name string corresponding to the
     specified page size code is returned.  The complete list of page size
     names and codes can be found in pod.h.

     The PDSizeTableStruct is defined as follows.

          typedef struct _pdSizeTableStruct {
              int   media_size;         /* Generic media name token */
              int   horizontal_addr;    /* Horizontal dots */
              int   vertical_addr;      /* Vertical dots */
              float width;              /* Width in inches */
              float length;             /* Length in inches */
              float left_margin;        /* Left margin in inches */
              float top_margin;         /* Top margin in inches */
              char  raster_definition;  /* Raster direction and */
                                        /* orientation bits */
              char  validation_mask;    /* Entry validation */
              char  variable_page_size; /* Variable width or length bits */
          } PDSizeTableStruct;


     media_size          Media size code (see pod.h).

     horizontal_addr, vertical_addr
                         Number of horizontal and vertical dots. This is also
                         the length of each raster line and the number of
                         raster lines, respectively.

     width               Width of the medium in inches along the raster line.

     length              Length of the medium in inches perpendicular to the
                         raster line.

     left_margin         Non-printable distance in inches to the left of each
                         raster line.

     top_margin          Non-printable distance in inches before the first
                         raster line.

     raster_definition   Code describing the direction and orientation of the
                         printer raster (see pod.h).

     validation_mask     Size table entry validation bit mask.

     variable_page_size  Variable page size code (see pod.h).

RETURN VALUE
     PDFindPageSize returns a pointer to a PDSizeTableStruct if the page size
     specified by size_code is found. Note that the pointer returned points
     into the specified PDInfoStruct and should not be freed. Also note that
     this pointer will become invalid upon subsequent calls to PDLocalReadInfo
     and PDReadInfo. If the specified page size is not found or an execution
     error occurs, NULL is returned and PDerrno will be set. Test the value of
     PDerrno to determine whether an execution error occurred or the page size
     was not found (see Execution Error Codes below).

     PDGetSizeCodeByName returns the page size code corresponding to the
     specified page size name. If an execution error occurs or the page name
     cannot be found, -1 is returned and PDerrno will be set. To distinguish
     between execution error and name not found test the value of PDerrno.

     PDGetNameBySizeCode always returns a pointer to a page name string. If
     the size code is invalid, an empty string may be returned. Note that the
     pointer returned points to library static storage. To preserve the name
     string across subsequent calls to the function, copy the string to caller
     allocated storage.

EXECUTION ERROR CODES
     PDFindPageSize will fail under the following circumstances.

     PD_LIBERR_NO_PAGESIZE    Page size corresponding to the specified page
                              size code could not be found.

     PD_LIBERR_BAD_STRUCT     A NULL structure pointer has been specified.

     PDGetSizeCodeByName will fail under the following circumstances.

     PD_LIBERR_NO_PAGECODE    Page size code corresponding to the specified
                              page size name could not be found.

     PD_LIBERR_BAD_SIZENAME   Page size name is a NULL pointer.

     PDGetNameBySizeCode always returns a pointer to a string.

SEE ALSO
     PDReadInfo(3), libpod(3)