*
* 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-2008 The SquirrelMail Project Team
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/
if (!sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM)) {
- sm_rpc_return_error(1, _("No RPC action given"));
+ sm_rpc_return_error('', 1, _("No RPC action given"), 'client', 400, 'Bad Request');
}
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(2, _("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);
/**
* rpc_response_error.tpl
*
- * Template for constructing an error response to a remote
- * procedure call.
+ * Template for constructing a standard (SOAP-compliant)
+ * response to an errant remote procedure call.
*
* The following variables are available in this template:
- * + $error_code - The numeric error code associated with the
+ *
+ * string $rpc_action The RPC action being handled
+ * int $error_code The numeric error code associated with the
* current error condition
- * + $error_text - Any error message associated with the current
- * error condition (optional; may not be present)
+ * string $error_text Any error message associated with the
+ * current error condition (optional; may not be
+ * present)
+ * string $guilty_party A string indicating the party who caused the
+ * error: either "client" or "server" (optional;
+ * may not be present)
*
- * @copyright © 1999-2007 The SquirrelMail Project Team
+ * @copyright © 1999-2008 The SquirrelMail Project Team
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
- * @version $Id: rpc_response_error.tpl 12111 2007-01-11 08:05:51Z pdontthink $
+ * @version $Id$
* @package squirrelmail
* @subpackage templates
*/
extract($t);
-/*echo '<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>';*/
-echo '<?xml version="1.0" ?>';
-?>
-<response>
- <status>ERROR</status>
- <result_code><?php echo $error_code; ?></result_code>
- <result_text><?php echo $error_text; ?></result_text>
-</response>
+echo '<?xml version="1.0" ?>'; ?>
+<soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:sm="http://squirrelmail.org/rpc" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:soap-enc="http://www.w3.org/2003/05/soap-encoding" soap:encodingstyle="http://www.w3.org/2003/05/soap-encoding">
+ <soap:header>
+ <sm:result_code><?php echo $error_code; ?></sm:result_code>
+ <sm:result_text><?php echo $error_text; ?></sm:result_text>
+ </soap:header>
+ <soap:body>
+ <soap:fault>
+ <faultcode>soap:<?php echo ucfirst(strtolower($guilty_party)); ?></faultcode>
+ <faultstring><?php echo $error_text; ?></faultstring>
+ <detail>
+ <sm:result_code><?php echo $error_code; ?></sm:result_code>
+ <sm:result_text><?php echo $error_text; ?></sm:result_text>
+ </detail>
+ </soap:fault>
+ </soap:body>
+</soap:envelope>
/**
* rpc_response_success.tpl
*
- * Template for constructing a standard response to a remote
- * procedure call.
+ * Template for constructing a standard (SOAP-compliant)
+ * response to a remote procedure call.
*
* The following variables are available in this template:
- * + $result_code - The result code (optional; if not given
- * must default to 0 (zero))
- * + $result_text - Any result message (optional; may not be
- * present)
*
- * @copyright © 1999-2007 The SquirrelMail Project Team
+ * string $rpc_action The RPC action being handled
+ * int $result_code The result code
+ * string $result_text Any result message (optional; may not be present)
+ *
+ * @copyright © 1999-2008 The SquirrelMail Project Team
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
- * @version $Id: rpc_response_success.tpl 12111 2007-01-11 08:05:51Z pdontthink $
+ * @version $Id$
* @package squirrelmail
* @subpackage templates
*/
extract($t);
-/*echo '<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>';*/
-echo '<?xml version="1.0" ?>';
-?>
-<response>
- <status>OK</status>
- <result_code><?php echo $result_code; ?></result_code>
- <result_text><?php echo $result_text; ?></result_text>
-</response>
+echo '<?xml version="1.0" ?>'; ?>
+<soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:sm="http://squirrelmail.org/rpc" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:soap-enc="http://www.w3.org/2003/05/soap-encoding" soap:encodingstyle="http://www.w3.org/2003/05/soap-encoding">
+ <soap:header>
+ <sm:result_code><?php echo $result_code; ?></sm:result_code>
+ <sm:result_text><?php echo $result_text; ?></sm:result_text>
+ </soap:header>
+ <soap:body>
+ <sm:<?php echo $rpc_action; ?>Response><?php
+/* TODO/FIXME: when data is returned to the client, it goes here.... */
+ ?></sm:<?php echo $rpc_action; ?>Response>
+ </soap:body>
+</soap:envelope>
projects / squirrelmail.git / commitdiff