From 5083f41e9e6afbb7d7eae33a159abc5ab112e124 Mon Sep 17 00:00:00 2001 From: pdontthink Date: Thu, 11 Sep 2008 00:49:51 +0000 Subject: [PATCH] SOAP-ify RPC responses. It's on my list to write a JavaScript lib for SM to read these after which AJAX requests in 1.5.2 will be fully enabled (but proof-of-concept has already been achieved). Note to self to make the JavaScript tolerant enough when SM core returns HTML without the expected XML structure, which happens in many error situations because the SM core is largely designed to just push an error to the browser when it happens instead of more mature error handling when the caller can indicate that it wants to handle the error differently. Note to self that the real solution is to redesign the SM core. git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@13275 7612ce4b-ef26-0410-bec9-ea0150e637f0 --- src/squirrelmail_rpc.php | 65 +++++++++++++++---- templates/default_rpc/config.php | 2 +- templates/default_rpc/rpc_response_error.tpl | 45 ++++++++----- .../default_rpc/rpc_response_success.tpl | 36 +++++----- 4 files changed, 103 insertions(+), 45 deletions(-) diff --git a/src/squirrelmail_rpc.php b/src/squirrelmail_rpc.php index 5f55f09f..836dcc64 100644 --- a/src/squirrelmail_rpc.php +++ b/src/squirrelmail_rpc.php @@ -5,6 +5,13 @@ * * 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 @@ -81,7 +88,7 @@ require('../include/init.php'); * */ 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'); } @@ -142,11 +149,11 @@ if (!$handled_by_plugin) switch (strtolower($rpc_action)) { 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; @@ -165,14 +172,14 @@ if (!$handled_by_plugin) switch (strtolower($rpc_action)) { //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; @@ -181,7 +188,7 @@ if (!$handled_by_plugin) switch (strtolower($rpc_action)) { * */ 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; } @@ -193,16 +200,43 @@ if (!$handled_by_plugin) switch (strtolower($rpc_action)) { * * 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'); @@ -217,14 +251,19 @@ function sm_rpc_return_error($error_code, $error_text='') { * * 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); diff --git a/templates/default_rpc/config.php b/templates/default_rpc/config.php index 6e09872b..793eadb8 100644 --- a/templates/default_rpc/config.php +++ b/templates/default_rpc/config.php @@ -20,7 +20,7 @@ $template_engine = SQ_PHP_TEMPLATE; /** * Indicates what the content type is for this template set. */ -//FIXME - what is the proper content-type? (TODO: possibly make default RPC templates SOAP-compliant) +//TODO - what is the proper content-type? (most recommend text/xml for SOAP messages, but some such as w3schools.com recommend application/soap+xml) //$content_type = 'application/soap+xml'; $content_type = 'text/xml'; diff --git a/templates/default_rpc/rpc_response_error.tpl b/templates/default_rpc/rpc_response_error.tpl index a7b5b551..09beb8a2 100644 --- a/templates/default_rpc/rpc_response_error.tpl +++ b/templates/default_rpc/rpc_response_error.tpl @@ -3,18 +3,24 @@ /** * 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 */ @@ -25,11 +31,20 @@ extract($t); -/*echo '';*/ -echo ''; -?> - - ERROR - - - +echo ''; ?> + + + + + + + + soap: + + + + + + + + diff --git a/templates/default_rpc/rpc_response_success.tpl b/templates/default_rpc/rpc_response_success.tpl index fa53d025..36fb6dde 100644 --- a/templates/default_rpc/rpc_response_success.tpl +++ b/templates/default_rpc/rpc_response_success.tpl @@ -3,18 +3,18 @@ /** * 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 */ @@ -25,11 +25,15 @@ extract($t); -/*echo '';*/ -echo ''; -?> - - OK - - - +echo ''; ?> + + + + + + + Response>Response> + + -- 2.25.1