SOAP-ify RPC responses. It's on my list to write a JavaScript lib for SM to read...
authorpdontthink <pdontthink@7612ce4b-ef26-0410-bec9-ea0150e637f0>
Thu, 11 Sep 2008 00:49:51 +0000 (00:49 +0000)
committerpdontthink <pdontthink@7612ce4b-ef26-0410-bec9-ea0150e637f0>
Thu, 11 Sep 2008 00:49:51 +0000 (00:49 +0000)
git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@13275 7612ce4b-ef26-0410-bec9-ea0150e637f0

src/squirrelmail_rpc.php
templates/default_rpc/config.php
templates/default_rpc/rpc_response_error.tpl
templates/default_rpc/rpc_response_success.tpl

index 5f55f09..836dcc6 100644 (file)
@@ -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 &copy; 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);
 
index 6e09872..793eadb 100644 (file)
@@ -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';
 
index a7b5b55..09beb8a 100644 (file)
@@ -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 &copy; 1999-2007 The SquirrelMail Project Team
+  * @copyright &copy; 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>
index fa53d02..36fb6dd 100644 (file)
@@ -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 &copy; 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 &copy; 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>