scripting/php/README

README - 02/25/2006
-------------------

INTRODUCTION

    This directory contains a dynamically loadable CUPS extension
    module for PHP 4 and 5.  The CUPS 1.2 module has been
    substantially updated to provide an API more consistent with
    the C API and is NOT compatible with the CUPS 1.1 module.


COMPILING AND INSTALLING

    Run "make" to compile the PHP CUPS extension:

	make

    To install it, type:

	make install


RESOURCES AND SUPPORT

    Questions should be reported to the CUPS newsgroups/mailing
    lists at:

	http://www.cups.org/newsgroups.php

    Bug reports and enhancement requests can be submitted via the
    form at:

	http://www.cups.org/str.php


QUICK REFERENCE DOCUMENTATION

    In lieu of actual documentation, the following definitions
    can be used as a quick reference to the supported functions:


    CUPS_CANCEL_JOB

    Cancels a job on the named destination:

        bool cups_cancel_job(string dest, int id)

    The return value is TRUE on success and FALSE on failure.

    Example:

        if (!cups_cancel_job("myprinter", 123))
	  print("Unable to cancel job: " . cups_last_error_string() . "\n");


    CUPS_GET_DESTS

    Gets a list of available destinations:

        array cups_get_dests()

    The return value is an array of objects with the following
    properties:

        name        The name of the printer or class
	instance    The instance of the printer or class
	is_default  TRUE if the printer or class is the default destination
	options     Associative array of options and their values

    Example:

        $dest = cups_get_dests();


    CUPS_GET_JOBS

    Gets a list of jobs:

        array cups_get_jobs(string dest, bool myjobs, int completed)

    The "dest" string can be blank for jobs on all destinations.
    Pass TRUE for "myjobs" to only get jobs for the current user.
    The "completed" argument can be 0 for pending jobs, 1 for
    completed jobs, and -1 for all jobs.

    The return value is an array of objects with the following
    properties:

        id                The job ID
        dest              Printer or class name
        title             Title/job name
        user              User the submitted the job
        format            Document format
        state             Job state
        size              Size in kilobytes
        priority          Priority (1-100)
        completed_time    Time the job was completed
        creation_time     Time the job was created
        processing_time   Time the job was processed

    Example:

        $jobs = cups_get_jobs("", FALSE, -1);


    CUPS_LAST_ERROR
    
    Returns the IPP status code for the most recent request:

        int cups_last_error()

    Example:

        $error = cups_last_error();


    CUPS_LAST_ERROR_STRING
    
    Returns the IPP status-message string for the most recent request:

        string cups_last_error_string()

    Example:

        $message = cups_last_error_string();


    CUPS_PRINT_FILE

    Prints a single file to a printer or class:

        int cups_print_file(string dest, string filename, string title,
	                    array options)

    The return value is the job ID or 0 if there was an error.

    Example:

        $options = array("name" => "value", "name2" => "value2");
	$id      = cups_print_file("dest", "filename", "title", $options);


    CUPS_PRINT_FILES

    Prints one or more files to a printer or class:

        int cups_print_files(string dest, array files, string title,
	                     array options);

    The return value is the job ID or 0 if there was an error.

    Example:

        $files   = array("file1", "file2", "file3");
        $options = array("name" => "value", "name2" => "value2");
	$id      = cups_print_file("dest", $files, "title", $options);