*
* This file contains the entry point to the "SquirrelMail API" -- the
* remote procedure call request receiver.
+ *
+ * RPC requests are currently understood as simple HTTP GET or POST
+ * requests. The SquirrelMail default_rpc template set responds in a
+ * SOAP (currently v1.2) compliant manner, but this interface does not
+ * (yet?) understand SOAP requests. The format of responses can be
+ * changed by creating a different RPC template set and pointing to it
+ * with $rpc_templateset in the main SquirrelMail configuration file.
*
- * @copyright © 1999-2007 The SquirrelMail Project Team
+ * @copyright 1999-2020 The SquirrelMail Project Team
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
* @version $Id$
* @package squirrelmail
+//FIXME: do we need to put this list somewhere else?
+//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)
+/**
+ * Known core error codes:
+ *
+ * 1 - No RPC action was given in request (please use "rpc_action")
+ * 2 - RPC action was not understood (perhaps a needed plugin is
+ * not installed and activated?)
+ *
+ * Known plugin error codes:
+ *
+ * 500 - Empty Folders plugin empty_folders_purge_trash action failed
+ * 501 - Empty Folders plugin empty_folders_purge_all action failed
+ * 502 - Empty Folders plugin empty_folders_delete_all action failed
+ * 503 - Mark Read plugin mark_read_read_all action failed
+ * 504 - Mark Read plugin mark_read_unread_all action failed
+ *
+ */
+
+
+
/**
* Get RPC Action (can be in either GET or POST)
*
*/
if (!sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM)) {
-//FIXME: establish error codes (using 99 in the interim)
- sm_rpc_return_error(99, _("No RPC action given"));
+ sm_rpc_return_error('', 1, _("No RPC action given"), 'client', 400, 'Bad Request');
}
*/
$oTemplate->header('Content-Type: text/xml');
$oTemplate->header('Content-Type: application/xml'); // required by IE
-//FIXME: which anti-cache headers do we want to use?
-$oTemplate->header('Cache-Control: no-cache');
-// $oTemplate->header("Expires: Sat, 1 Jan 2000 00:00:00 GMT");
-// $oTemplate->header("Last-Modified: " . gmdate("D, d M Y H:i:s") . "GMT");
-// $oTemplate->header("Cache-Control: no-cache, must-revalidate");
-// $oTemplate->header("Pragma: no-cache");
+$oTemplate->header('Pragma: no-cache');
+$oTemplate->header('Cache-Control: no-cache, no-store, must-revalidate, max-age=0');
+$oTemplate->header('Expires: Sat, 1 Jan 2000 00:00:00 GMT');
+//TODO: is this needed? $oTemplate->header('Last-Modified: ' . gmdate('D, d M Y H:i:s') . 'GMT');
* in an array in case we can think of more parameters
* to add in the future.
*
+ * Known users of this hook:
+ * empty_folders
+ * mark_read
+ *
*/
-$handled_by_plugin = boolean_hook_function('squirrelmail_rpc',
- $temp=array(&$rpc_action),
- 1);
+$temp = array(&$rpc_action);
+$handled_by_plugin = boolean_hook_function('squirrelmail_rpc', $temp, 1);
require_once(SM_PATH . 'functions/imap.php');
if (!sqGetGlobalVar('delete_ids', $delete_ids, SQ_FORM)) {
- sm_rpc_return_error(99, _("No deletion ID given"));
+ sm_rpc_return_error($rpc_action, 99, _("No deletion ID given"), 'client', 400, 'Bad Request');
}
$delete_ids = explode(',', $delete_ids);
if (!sqGetGlobalVar('mailbox', $mailbox, SQ_FORM)) {
- sm_rpc_return_error(99, _("No mailbox given"));
+ sm_rpc_return_error($rpc_action, 99, _("No mailbox given"), 'client', 400, 'Bad Request');
}
if (sqGetGlobalVar('startMessage', $startMessage, SQ_INORDER, 1)) {
$startMessage = (int) $startMessage;
//FIXME: establish constants for $hide values (the 3 below indicates not to show errors, but to return any error string)
$result = $oImapMessage->deleteMessage(3);
if ($result !== TRUE) {
- sm_rpc_return_error(99, $result);
+ sm_rpc_return_error($rpc_action, 99, $result, 'server', 500, 'Server Error');
}
}
--- */
sm_rpc_return_success();
//FIXME: Just for testing the line above can be changed to something like this:
- //sm_rpc_return_success(0, 'Hooray! Message(s) deleted. Refresh your message list and make sure.');
+ //sm_rpc_return_success($rpc_action, 0, 'Hooray! Message(s) deleted. Refresh your message list and make sure.');
break;
*
*/
default:
- sm_rpc_return_error(99, _("RPC action not understood"));
+ sm_rpc_return_error($rpc_action, 2, _("RPC action not understood"), 'client', 400, 'Bad Request');
break;
}
*
* NOTE that this function exits and will never return
*
- * @param int $error_code The error code for the current error condition
- * @param string $error_text Any error message associated with the error
- * condition (OPTIONAL; default empty string)
+ * @param string $rpc_action The RPC action that is being handled
+ * (OPTIONAL; default attempt to grab from GET/POST)
+ * @param int $error_code The (application-level) error code for the current
+ * error condition
+ * @param string $error_text Any error message associated with the error
+ * condition (OPTIONAL; default empty string)
+ * @param string $guilty_party A string indicating the party who caused the
+ * error: either "client" or "server" (OPTIONAL;
+ * default unspecified)
+ * @param int $http_status_code When non-zero, this value will be sent to
+ * the browser in the HTTP headers as the request
+ * status code (OPTIONAL; default not used)
+ * @param string $http_status_text A string naming the HTTP status, usually the
+ * title of the corresponding status code as
+ * found on:
+ * http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
+ * (OPTIONAL; default not used; $http_status_code
+ * must also be provided).
*
*/
-function sm_rpc_return_error($error_code, $error_text='') {
+function sm_rpc_return_error($rpc_action=NULL, $error_code,
+ $error_text='', $guilty_party='',
+ $http_status_code=0, $http_status_text='') {
global $oTemplate;
- $oTemplate->assign('error_code', $error_code);
- $oTemplate->assign('error_text', $error_text);
+
+ if (is_null($rpc_action)) sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM);
+
+ if ($http_status_code) {
+ $oTemplate->header('HTTP/1.1 ' . $http_status_code . ' ' . $http_status_text);
+ $oTemplate->header('Status: ' . $http_status_code . ' ' . $http_status_text);
+ }
+
+ $oTemplate->assign('rpc_action', $rpc_action);
+ $oTemplate->assign('error_code', $error_code);
+ $oTemplate->assign('error_text', $error_text);
+ $oTemplate->assign('guilty_party', $guilty_party);
$oTemplate->display('rpc_response_error.tpl');
*
* NOTE that this function exits and will never return
*
+ * @param string $rpc_action The RPC action that is being handled
+ * (OPTIONAL; default attempt to grab from GET/POST)
* @param int $result_code The result code (OPTIONAL; default 0)
* @param string $result_text Any result message (OPTIONAL; default
* empty string)
*
*/
-function sm_rpc_return_success($result_code=0, $result_text='') {
+function sm_rpc_return_success($rpc_action=NULL, $result_code=0, $result_text='') {
+
+ if (is_null($rpc_action)) sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM);
global $oTemplate;
+ $oTemplate->assign('rpc_action', $rpc_action);
$oTemplate->assign('result_code', $result_code);
$oTemplate->assign('result_text', $result_text);