SOAP-ify RPC responses. It's on my list to write a JavaScript lib for SM to read...
[squirrelmail.git] / src / squirrelmail_rpc.php
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 © 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);