root / pykota / trunk / docs / filterpykota.sgml @ 1185

<!-- $Id$ -->

<chapter>
  <title id="filter">The pykota filter</title>
  
  <para>Last modified on $Date$</para>
  
  <para>
    To account for pages or eventually ink usage 
    <footnote>
      <para>
        PyKota doesn't currently account for ink usage, it only accounts
        pages. To account for ink usage, you should use PrintBill instead.
      </para>  
    </footnote>  
    , you must plug your accounting
    system somewhere into the printing system you use, be it either <application>CUPS</application>
    or <application>LPRng</application>. One way to do this without having
    to modify the printing system itself, is by using a <firstterm>filter</firstterm>.
  </para>
  
  <para>
    A filter is a computer program which takes data in one format as its input, and outputs the
    same data but transformed into another format. <application>CUPS</application> already
    contains many filters. For example there's one filter named <application>pstops</application> which accepts 
    PostScript data as its input, and, as its name implies, outputs PostScript data too, but after having
    eventually rearranged the pages to fit several pages on a single sheet of paper, or other manipulations
    like that. 
  </para>
  
  <para>
    The <application>pstops</application> filter described above is also in charge of doing basic page
    accounting, but <application>PyKota</application> currently doesn't use this facility since it may
    prove to be unreliable depending on the drivers used or if a paper jam occurs for example.
  </para>
  
  <para>
    <application>LPRng</application> can also use filters, one often used in combination with
    <application>LPRng</application> is <application>magicfilter</application> which can convert 
    different input formats to native printers languages like PostScript or ESC/P2.
  </para>  
  
  <para>
    So to do its own accounting, <application>PyKota</application> has its own filter, named <application>pykota</application>,
    which you have to plug into the different set of filters used by your printing system of choice. The procedure to 
    install the <application>pykota</application> filter is described in the 
    <xref linkend="installation" endterm="installation"> chapter.
  </para>
  
  <para>
    Currently with a <application>CUPS</application> backend, the <application>pykota</application> filter is used at the very last stage of the print mechanism,
    just before the final data is sent to the printer, but it may eventually be used earlier with some
    modifications to <application>CUPS</application>'s filtering configuration. 
    You can find in the mailing list archives of July 2003 an explanation on how to do this.
    This may allow you to use PyKota with a not-PostScript printer or with a PostScript printer
    which really needs to have
    a specific filter like <application>magicfilter</application> or <application>cupsomatic</application>.
  </para>
  
  <para>
    When used with an <application>LPRng</application> backend, the accounting filter is not defined the same way 
    input filters are, so the problem described above doesn't exist, and <application>PyKota</application>
    may work with non-postscript printers, provided they can report their page counter and you know how to retrieve
    it.
  </para>
  
  <para>
    When you submit a print job, <application>pykota</application> is automatically launched by your printing system,
    so it has to detect which system you are using (<application>CUPS</application> or <application>LPRng</application>)
    and behave like if it was specifically designed for your printing system. Fortunately there's not a lot
    of differences, the more important one is the exit codes used to tell the printing environment if a job
    has to be accepted or rejected. 
  </para>
  
  <para>
    When using the <literal>querying</literal> accounting method,
    <application>pykota</application> then asks the printer for its internal page counter, read from the Quota DataBase the internal
    page counter for this printer when the previous job was launched, computes the difference, and report it as the 
    previous job's size in the Quota DataBase. It then updates the last user's print quota and account balance, and
    warn him if he is over quota or if his account balance is below 0. Finally it checks if the user who launched the 
    current job is below or above his print quota, and either allows or denies the job's datas to pass to the underlying 
    layer (the printer itself).
  </para>
  
  <para>
    When using the <literal>external</literal> accounting method,
    and if the user is still allowed to print,
    the command you specified is launched with the job's data on its 
    standard input. Your command must print the job's size in number of
    pages on a single line on its standard output. This number is then
    read by PyKota and used to update the current user's quota information.
    Of course checks are also done like with the <literal>querying</literal>
    accounting method, to see if the current job is allowed to be printed or not.
  </para>
  
  <para>
    If a problem occurs, it is logged either to the filter's standard output or to the system logger, depending on
    your preferences in <application>PyKota</application>'s configuration files. Also if a print quota is reached
    you may choose if the administrator, the user, both or no-one will receive an email message explaining
    the situation and proposing a solution.
  </para>
  
</chapter>

<!--

$Log$
Revision 1.7  2003/10/14 20:26:53  jalet
Better documentation.
1.15 is out !

Revision 1.6  2003/07/25 13:10:58  jalet
Improved documentation

Revision 1.5  2003/07/25 10:41:29  jalet
Better documentation.
pykotme now displays the current user's account balance.
Some test changed in ldap module.

Revision 1.4  2003/04/30 20:00:51  jalet
Typo

Revision 1.3  2003/04/24 21:09:47  jalet
Documentation slightly improved.

Revision 1.2  2003/03/25 09:32:06  jalet
Improved documentation.

Revision 1.1  2003/02/08 00:03:35  jalet
Documentation skeleton added


-->