src/squirrelmail_rpc.php

   1 <?php
   2
   3 /**
   4   * squirrelmail_rpc.php
   5   *
   6   * This file contains the entry point to the "SquirrelMail API" -- the
   7   * remote procedure call request receiver.
   8   *
   9   * RPC requests are currently understood as simple HTTP GET or POST
  10   * requests.  The SquirrelMail default_rpc template set responds in a
  11   * SOAP (currently v1.2) compliant manner, but this interface does not
  12   * (yet?) understand SOAP requests.  The format of responses can be
  13   * changed by creating a different RPC template set and pointing to it
  14   * with $rpc_templateset in the main SquirrelMail configuration file.
  15   *
  16   * @copyright &copy; 1999-2008 The SquirrelMail Project Team
  17   * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  18   * @version $Id$
  19   * @package squirrelmail
  20   * @since 1.5.2
  21   *
  22   */
  23
  24 /** This is the squirrelmail_rpc page */
  25 define('PAGE_NAME', 'squirrelmail_rpc');
  26
  27 //FIXME: If we decide to route ALL requests, even normal page
  28 //       requests through this file, need to change page requests
  29 //       to something like this
  30 //http://example.org/squirrelmail/src/squirrelmail_rpc.php?page=read_body&passed_id=47633...
  31 //       This file would then add ".php" to the "page" variable
  32 //       and pass the request on to that page by simply require()ing
  33 //       that page and exiting.
  34 //       Does this present problems, security or otherwise?  What
  35 //       problems are created by the fact that the page request
  36 //       is always the same thing (some parts of the code and some
  37 //       plugins switch functionality based on $PHP_SELF and other
  38 //       $_SERVER variables that look for specific page names -- those
  39 //       can be fixed by looking at the "page" GET argument, but what
  40 //       other issues are created)?  What about plugins?  How would
  41 //       they work in this scheme?  Would they be a lot more difficult
  42 //       to develop?
  43 //NOTE:  It is not entirely clear if doing the above is even desirable.
  44 //       Initial conversations on the squirrelmail-devel list were
  45 //       inconclusive.  On one hand, doing so would give us one master
  46 //       file that handles any and all incoming requests, no matter
  47 //       where they came from or what format/type they are.  On the
  48 //       other, keeping page requests out of this file keeps this file
  49 //       lean and specific to one technology: our RPC interface.
  50
  51
  52 /**
  53  * Include the SquirrelMail initialization file.
  54  */
  55 //FIXME: init.php assumes it is being called by a browser, so some error
  56 //       conditions are handled by immediately calling error_box() or
  57 //       otherwise trying to push something to the browser, which should
  58 //       be avoided at all costs.  This is also pervasive in the whole
  59 //       core and must be cleaned up entirely before this can be a very
  60 //       functional RPC interface
  61 require('../include/init.php');
  62
  63
  64
  65 //FIXME: do we need to put this list somewhere else?
  66 //FIXME: do we want to use constants instead?  probably not a bad idea, although plugins probably won't, so we still want to try to keep track of the plugin error codes too if possible (new plugin website should help)
  67 /**
  68   * Known core error codes:
  69   *
  70   * 1    - No RPC action was given in request (please use "rpc_action")
  71   * 2    - RPC action was not understood (perhaps a needed plugin is
  72   *        not installed and activated?)
  73   *
  74   * Known plugin error codes:
  75   *
  76   * 500  - Empty Folders plugin empty_folders_purge_trash action failed
  77   * 501  - Empty Folders plugin empty_folders_purge_all action failed
  78   * 502  - Empty Folders plugin empty_folders_delete_all action failed
  79   * 503  - Mark Read plugin mark_read_read_all action failed
  80   * 504  - Mark Read plugin mark_read_unread_all action failed
  81   *
  82   */
  83
  84
  85
  86 /**
  87   * Get RPC Action (can be in either GET or POST)
  88   *
  89   */
  90 if (!sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM)) {
  91     sm_rpc_return_error('', 1, _("No RPC action given"), 'client', 400, 'Bad Request');
  92 }
  93
  94
  95
  96 /**
  97   * No matter what our response is, the headers
  98   * will not change.
  99   *
 100   */
 101 $oTemplate->header('Content-Type: text/xml');
 102 $oTemplate->header('Content-Type: application/xml'); // required by IE
 103 //FIXME: which anti-cache headers do we want to use?
 104 $oTemplate->header('Cache-Control: no-cache');
 105 // $oTemplate->header("Expires: Sat, 1 Jan 2000 00:00:00 GMT");
 106 // $oTemplate->header("Last-Modified: " . gmdate("D, d M Y H:i:s") . "GMT");
 107 // $oTemplate->header("Cache-Control: no-cache, must-revalidate");
 108 // $oTemplate->header("Pragma: no-cache");
 109
 110
 111
 112 /**
 113   * Allow plugins to add their own RPC action
 114   * or modify behavior of SM core RPC actions...
 115   *
 116   * A plugin that handles a custom RPC action must
 117   * return TRUE to the hook so that it knows that
 118   * the action was handled and was not an unknown
 119   * action.  If the action was not handled, the plugin
 120   * should return FALSE to the hook.
 121   *
 122   * Developer note: the $rpc_action parameter is passed
 123   * in an array in case we can think of more parameters
 124   * to add in the future.
 125   *
 126   * Known users of this hook:
 127   *    empty_folders
 128   *    mark_read
 129   *
 130   */
 131 $temp = array(&$rpc_action);
 132 $handled_by_plugin = boolean_hook_function('squirrelmail_rpc', $temp, 1);
 133
 134
 135
 136 /**
 137   * Go take care of each RPC action (unless plugin already did)
 138   *
 139   */
 140 if (!$handled_by_plugin) switch (strtolower($rpc_action)) {
 141
 142     /**
 143       * Delete Messages
 144       *
 145       */
 146     case 'delete_messages':
 147
 148         require_once(SM_PATH . 'functions/mailbox_display.php');
 149         require_once(SM_PATH . 'functions/imap.php');
 150
 151         if (!sqGetGlobalVar('delete_ids', $delete_ids, SQ_FORM)) {
 152             sm_rpc_return_error($rpc_action, 99, _("No deletion ID given"), 'client', 400, 'Bad Request');
 153         }
 154         $delete_ids = explode(',', $delete_ids);
 155         if (!sqGetGlobalVar('mailbox', $mailbox, SQ_FORM)) {
 156             sm_rpc_return_error($rpc_action, 99, _("No mailbox given"), 'client', 400, 'Bad Request');
 157         }
 158         if (sqGetGlobalVar('startMessage', $startMessage, SQ_INORDER, 1)) {
 159             $startMessage = (int) $startMessage;
 160         }
 161         sqGetGlobalVar('what', $what, SQ_FORM, 0);
 162         if (sqGetGlobalVar('account', $iAccount,  SQ_GET, 0)) {
 163             $iAccount = (int) $iAccount;
 164         }
 165 //FIXME: need to grab the bypass trash variable here too!  probably other vars...
 166
 167 /* FIXME: --- The following code was just experimental/proof-of-concept; the rest
 168               of the implementation of this functionality still needs to be done "for real"
 169         $oImapMessage = new IMAP_Message(0, $mailbox, $startMessage, $what, $iAccount);
 170         foreach ($delete_ids as $id) {
 171             $oImapMessage->setUid($id);
 172             //FIXME: establish constants for $hide values (the 3 below indicates not to show errors, but to return any error string)
 173             $result = $oImapMessage->deleteMessage(3);
 174             if ($result !== TRUE) {
 175                 sm_rpc_return_error($rpc_action, 99, $result, 'server', 500, 'Server Error');
 176             }
 177         }
 178 --- */
 179
 180         sm_rpc_return_success();
 181         //FIXME: Just for testing the line above can be changed to something like this:
 182         //sm_rpc_return_success($rpc_action, 0, 'Hooray!  Message(s) deleted.  Refresh your message list and make sure.');
 183         break;
 184
 185
 186     /**
 187       * Default: error out
 188       *
 189       */
 190     default:
 191         sm_rpc_return_error($rpc_action, 2, _("RPC action not understood"), 'client', 400, 'Bad Request');
 192         break;
 193
 194 }
 195
 196
 197
 198 /**
 199   * Returns an error message to the RPC caller and exits
 200   *
 201   * NOTE that this function exits and will never return
 202   *
 203   * @param string $rpc_action   The RPC action that is being handled
 204   *                             (OPTIONAL; default attempt to grab from GET/POST)
 205   * @param int    $error_code   The (application-level) error code for the current
 206   *                             error condition
 207   * @param string $error_text   Any error message associated with the error
 208   *                             condition (OPTIONAL; default empty string)
 209   * @param string $guilty_party A string indicating the party who caused the
 210   *                             error: either "client" or "server" (OPTIONAL;
 211   *                             default unspecified)
 212   * @param int    $http_status_code When non-zero, this value will be sent to
 213   *                                 the browser in the HTTP headers as the request
 214   *                                 status code (OPTIONAL; default not used)
 215   * @param string $http_status_text A string naming the HTTP status, usually the
 216   *                                 title of the corresponding status code as
 217   *                                 found on:
 218   *                                 http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
 219   *                                 (OPTIONAL; default not used; $http_status_code
 220   *                                 must also be provided).
 221   *
 222   */
 223 function sm_rpc_return_error($rpc_action=NULL, $error_code,
 224                              $error_text='', $guilty_party='',
 225                              $http_status_code=0, $http_status_text='') {
 226
 227     global $oTemplate;
 228
 229     if (is_null($rpc_action)) sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM);
 230
 231     if ($http_status_code) {
 232        $oTemplate->header('HTTP/1.1 ' . $http_status_code . ' ' . $http_status_text);
 233        $oTemplate->header('Status: ' . $http_status_code . ' ' . $http_status_text);
 234     }
 235
 236     $oTemplate->assign('rpc_action',   $rpc_action);
 237     $oTemplate->assign('error_code',   $error_code);
 238     $oTemplate->assign('error_text',   $error_text);
 239     $oTemplate->assign('guilty_party', $guilty_party);
 240
 241     $oTemplate->display('rpc_response_error.tpl');
 242
 243     exit;
 244
 245 }
 246
 247
 248
 249 /**
 250   * Returns a standard success result to the RPC caller and exits
 251   *
 252   * NOTE that this function exits and will never return
 253   *
 254   * @param string $rpc_action  The RPC action that is being handled
 255   *                            (OPTIONAL; default attempt to grab from GET/POST)
 256   * @param int    $result_code The result code (OPTIONAL; default 0)
 257   * @param string $result_text Any result message (OPTIONAL; default
 258   *                            empty string)
 259   *
 260   */
 261 function sm_rpc_return_success($rpc_action=NULL, $result_code=0, $result_text='') {
 262
 263     if (is_null($rpc_action)) sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM);
 264
 265     global $oTemplate;
 266     $oTemplate->assign('rpc_action', $rpc_action);
 267     $oTemplate->assign('result_code', $result_code);
 268     $oTemplate->assign('result_text', $result_text);
 269
 270     $oTemplate->display('rpc_response_success.tpl');
 271
 272     exit;
 273
 274 }
 275
 276
 277