banana/protocoleinterface.inc.php

   1 <?php
   2 /********************************************************************************
   3 * banana/protocoleinterface.inc.php : interface for box access
   4 * ------------------------
   5 *
   6 * This file is part of the banana distribution
   7 * Copyright: See COPYING files that comes with this distribution
   8 ********************************************************************************/
   9
  10 require_once dirname(__FILE__) . '/banana.inc.php';
  11
  12 interface BananaProtocoleInterface
  13 {
  14     /** Build a protocole handler plugged on the given box
  15      */
  16     public function __construct();
  17
  18     /** Indicate if the Protocole handler has been succesfully built
  19      */
  20     public function isValid();
  21
  22     /** Indicate last error n°
  23      */
  24     public function lastErrNo();
  25
  26     /** Indicate last error text
  27      */
  28     public function lastError();
  29
  30     /** Return the description of the current box
  31      */
  32     public function getDescription();
  33
  34     /** Return the list of the boxes
  35      * @param mode Kind of boxes to list
  36      * @param since date of last check (for new boxes and new messages)
  37      * @param withstats Indicated whether msgnum and unread must be set in the result
  38      * @return Array(boxname => array(desc => boxdescripton, msgnum => number of message, unread =>number of unread messages)
  39      */
  40     public function getBoxList($mode = Banana::BOXES_ALL, $since = 0, $withstats = false);
  41
  42     /** Return a message
  43      * @param id Id of the emssage (can be either an Message-id or a message index)
  44      * @return A BananaMessage or null if the given id can't be retreived
  45      */
  46     public function &getMessage($id);
  47
  48     /** Return the sources of a message
  49      * @param id Id of the emssage (can be either an Message-id or a message index)
  50      * @return The sources of the message (or null)
  51      */
  52     public function getMessageSource($id);
  53
  54     /** Return the indexes of the messages presents in the Box
  55      * @return Array(number of messages, MSGNUM of the first message, MSGNUM of the last message)
  56      */
  57     public function getIndexes();
  58
  59     /** Return the message headers (in BananaMessage) for messages from firstid to lastid
  60      * @return Array(id => array(headername => headervalue))
  61      */
  62     public function &getMessageHeaders($firstid, $lastid, array $msg_headers = array());
  63
  64     /** Update the spool to add protocole specifics data
  65      * @param Array(id => message headers)
  66      */
  67     public function updateSpool(array &$messages);
  68
  69     /** Return the indexes of the new messages since the give date
  70      * @return Array(MSGNUM of new messages)
  71      */
  72     public function getNewIndexes($since);
  73
  74     /** Return wether or not the protocole can be used to add new messages
  75      */
  76     public function canSend();
  77
  78     /** Return wether or not the protocole allow message deletion
  79      */
  80     public function canCancel();
  81
  82     /** Return the list of requested headers
  83      * @return Array('header1', 'header2', ...) with the key 'dest' for the destination header
  84      * and 'reply' for the reply header, eg:
  85      * * for a mail: Array('From', 'Subject', 'dest' => 'To', 'Cc', 'Bcc', 'reply' => 'Reply-To')
  86      * * for a post: Array('From', 'Subject', 'dest' => 'Newsgroups', 'reply' => 'Followup-To')
  87      */
  88     public function requestedHeaders();
  89
  90     /** Send a message
  91      * @return true if it was successfull
  92      */
  93     public function send(BananaMessage $message);
  94
  95     /** Cancel a message
  96      * @return true if it was successfull
  97      */
  98     public function cancel(BananaMessage $message);
  99
 100     /** Return the protocole name
 101      */
 102     public function name();
 103
 104     /** Return the spool filename to use for the given box
 105      * @param box STRING boxname
 106      */
 107     public function filename();
 108
 109     /** Return the execution backtrace of the protocole
 110      * @return array(trace1, trace2, ...)
 111      * a trace has the following structure:
 112      *  array('action' => action, 'time' => microtime, 'code' => return code, 'response' => size of the response)
 113      * if no backtrace is available, return null
 114      */
 115     public function backtrace();
 116 }
 117
 118 // vim:set et sw=4 sts=4 ts=4 enc=utf-8:
 119 ?>