Source for file squirrelmail_rpc.php

Documentation is available at 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 1999-2020 The SquirrelMail Project Team
  17.   * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  18.   * @version $Id: squirrelmail_rpc.php 14845 2020-01-07 08:09:34Z pdontthink $
  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. $oTemplate->header('Pragma: no-cache');
  104. $oTemplate->header('Cache-Control: no-cache, no-store, must-revalidate, max-age=0');
  105. $oTemplate->header('Expires: Sat, 1 Jan 2000 00:00:00 GMT');
  106. //TODO: is this needed? $oTemplate->header('Last-Modified: ' . gmdate('D, d M Y H:i:s') . 'GMT');
  107.  
  108.  
  109.  
  110. /**
  111.   * Allow plugins to add their own RPC action
  112.   * or modify behavior of SM core RPC actions...
  113.   *
  114.   * A plugin that handles a custom RPC action must
  115.   * return TRUE to the hook so that it knows that
  116.   * the action was handled and was not an unknown
  117.   * action.  If the action was not handled, the plugin
  118.   * should return FALSE to the hook.
  119.   *
  120.   * Developer note: the $rpc_action parameter is passed
  121.   * in an array in case we can think of more parameters
  122.   * to add in the future.
  123.   *
  124.   * Known users of this hook:
  125.   *    empty_folders
  126.   *    mark_read
  127.   *
  128.   */
  129. $temp = array(&$rpc_action);
  130. $handled_by_plugin = boolean_hook_function('squirrelmail_rpc', $temp, 1);
  131.  
  132.  
  133.  
  134. /**
  135.   * Go take care of each RPC action (unless plugin already did)
  136.   *
  137.   */
  138. if (!$handled_by_plugin) switch (strtolower($rpc_action)) {
  139.  
  140.     /**
  141.       * Delete Messages
  142.       *
  143.       */
  144.     case 'delete_messages':
  145.  
  146.         require_once(SM_PATH . 'functions/mailbox_display.php');
  147.         require_once(SM_PATH . 'functions/imap.php');
  148.  
  149.         if (!sqGetGlobalVar('delete_ids', $delete_ids, SQ_FORM)) {
  150.             sm_rpc_return_error($rpc_action, 99, _("No deletion ID given"), 'client', 400, 'Bad Request');
  151.         }
  152.         $delete_ids = explode(',', $delete_ids);
  153.         if (!sqGetGlobalVar('mailbox', $mailbox, SQ_FORM)) {
  154.             sm_rpc_return_error($rpc_action, 99, _("No mailbox given"), 'client', 400, 'Bad Request');
  155.         }
  156.         if (sqGetGlobalVar('startMessage', $startMessage, SQ_INORDER, 1)) {
  157.             $startMessage = (int) $startMessage;
  158.         }
  159.         sqGetGlobalVar('what', $what, SQ_FORM, 0);
  160.         if (sqGetGlobalVar('account', $iAccount,  SQ_GET, 0)) {
  161.             $iAccount = (int) $iAccount;
  162.         }
  163. //FIXME: need to grab the bypass trash variable here too!  probably other vars...
  164.  
  165. /* FIXME: --- The following code was just experimental/proof-of-concept; the rest 
  166.               of the implementation of this functionality still needs to be done "for real"
  167.         $oImapMessage = new IMAP_Message(0, $mailbox, $startMessage, $what, $iAccount);
  168.         foreach ($delete_ids as $id) {
  169.             $oImapMessage->setUid($id);
  170.             //FIXME: establish constants for $hide values (the 3 below indicates not to show errors, but to return any error string)
  171.             $result = $oImapMessage->deleteMessage(3);
  172.             if ($result !== TRUE) {
  173.                 sm_rpc_return_error($rpc_action, 99, $result, 'server', 500, 'Server Error');
  174.             }
  175.         }
  176. --- */
  177.  
  178.         sm_rpc_return_success();
  179.         //FIXME: Just for testing the line above can be changed to something like this:
  180.         //sm_rpc_return_success($rpc_action, 0, 'Hooray!  Message(s) deleted.  Refresh your message list and make sure.');
  181.         break;
  182.  
  183.  
  184.     /**
  185.       * Default: error out
  186.       *
  187.       */
  188.     default:
  189.         sm_rpc_return_error($rpc_action, 2, _("RPC action not understood"), 'client', 400, 'Bad Request');
  190.         break;
  191.  
  192. }
  193.  
  194.  
  195.  
  196. /**
  197.   * Returns an error message to the RPC caller and exits
  198.   *
  199.   * NOTE that this function exits and will never return
  200.   *
  201.   * @param string $rpc_action   The RPC action that is being handled
  202.   *                              (OPTIONAL; default attempt to grab from GET/POST)
  203.   * @param int    $error_code   The (application-level) error code for the current
  204.   *                              error condition
  205.   * @param string $error_text   Any error message associated with the error
  206.   *                              condition (OPTIONAL; default empty string)
  207.   * @param string $guilty_party A string indicating the party who caused the
  208.   *                              error: either "client" or "server" (OPTIONAL;
  209.   *                              default unspecified)
  210.   * @param int    $http_status_code When non-zero, this value will be sent to
  211.   *                                  the browser in the HTTP headers as the request
  212.   *                                  status code (OPTIONAL; default not used)
  213.   * @param string $http_status_text A string naming the HTTP status, usually the
  214.   *                                  title of the corresponding status code as
  215.   *                                  found on:
  216.   *                                  http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
  217.   *                                  (OPTIONAL; default not used; $http_status_code
  218.   *                                  must also be provided).
  219.   *
  220.   */
  221. function sm_rpc_return_error($rpc_action=NULL, $error_code,
  222.                              $error_text='', $guilty_party='',
  223.                              $http_status_code=0, $http_status_text='') {
  224.  
  225.     global $oTemplate;
  226.  
  227.     if (is_null($rpc_action)) sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM);
  228.  
  229.     if ($http_status_code) {
  230.        $oTemplate->header('HTTP/1.1 ' . $http_status_code . ' ' . $http_status_text);
  231.        $oTemplate->header('Status: ' . $http_status_code . ' ' . $http_status_text);
  232.     }
  233.  
  234.     $oTemplate->assign('rpc_action',   $rpc_action);
  235.     $oTemplate->assign('error_code',   $error_code);
  236.     $oTemplate->assign('error_text',   $error_text);
  237.     $oTemplate->assign('guilty_party', $guilty_party);
  238.  
  239.     $oTemplate->display('rpc_response_error.tpl');
  240.  
  241.     exit;
  242.  
  243. }
  244.  
  245.  
  246.  
  247. /**
  248.   * Returns a standard success result to the RPC caller and exits
  249.   *
  250.   * NOTE that this function exits and will never return
  251.   *
  252.   * @param string $rpc_action  The RPC action that is being handled
  253.   *                             (OPTIONAL; default attempt to grab from GET/POST)
  254.   * @param int    $result_code The result code (OPTIONAL; default 0)
  255.   * @param string $result_text Any result message (OPTIONAL; default
  256.   *                             empty string)
  257.   *
  258.   */
  259. function sm_rpc_return_success($rpc_action=NULL, $result_code=0, $result_text='') {
  260.  
  261.     if (is_null($rpc_action)) sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM);
  262.  
  263.     global $oTemplate;
  264.     $oTemplate->assign('rpc_action', $rpc_action);
  265.     $oTemplate->assign('result_code', $result_code);
  266.     $oTemplate->assign('result_text', $result_text);
  267.  
  268.     $oTemplate->display('rpc_response_success.tpl');
  269.  
  270.     exit;
  271.  
  272. }

Documentation generated on Mon, 13 Jan 2020 04:23:36 +0100 by phpDocumentor 1.4.3