SOAP-ify RPC responses. It's on my list to write a JavaScript lib for SM to read...
[squirrelmail.git] / src / squirrelmail_rpc.php
CommitLineData
482956f2 1<?php
2
3/**
85ae8774 4 * squirrelmail_rpc.php
482956f2 5 *
6 * This file contains the entry point to the "SquirrelMail API" -- the
7 * remote procedure call request receiver.
5083f41e 8 *
9 * RPC requests are currently understood as simple HTTP GET or POST
10 * requests. The SquirrelMail default_rpc template set responds in a
11 * SOAP (currently v1.2) compliant manner, but this interface does not
12 * (yet?) understand SOAP requests. The format of responses can be
13 * changed by creating a different RPC template set and pointing to it
14 * with $rpc_templateset in the main SquirrelMail configuration file.
482956f2 15 *
a49f857e 16 * @copyright &copy; 1999-2008 The SquirrelMail Project Team
482956f2 17 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
18 * @version $Id$
19 * @package squirrelmail
20 * @since 1.5.2
21 *
22 */
ebd2391c 23
24/** This is the squirrelmail_rpc page */
85ae8774 25define('PAGE_NAME', 'squirrelmail_rpc');
ebd2391c 26
482956f2 27//FIXME: If we decide to route ALL requests, even normal page
28// requests through this file, need to change page requests
29// to something like this
85ae8774 30//http://example.org/squirrelmail/src/squirrelmail_rpc.php?page=read_body&passed_id=47633...
482956f2 31// This file would then add ".php" to the "page" variable
32// and pass the request on to that page by simply require()ing
33// that page and exiting.
34// Does this present problems, security or otherwise? What
35// problems are created by the fact that the page request
36// is always the same thing (some parts of the code and some
37// plugins switch functionality based on $PHP_SELF and other
38// $_SERVER variables that look for specific page names -- those
39// can be fixed by looking at the "page" GET argument, but what
40// other issues are created)? What about plugins? How would
41// they work in this scheme? Would they be a lot more difficult
42// to develop?
43//NOTE: It is not entirely clear if doing the above is even desirable.
44// Initial conversations on the squirrelmail-devel list were
45// inconclusive. On one hand, doing so would give us one master
46// file that handles any and all incoming requests, no matter
47// where they came from or what format/type they are. On the
48// other, keeping page requests out of this file keeps this file
49// lean and specific to one technology: our RPC interface.
50
51
52/**
53 * Include the SquirrelMail initialization file.
54 */
55//FIXME: init.php assumes it is being called by a browser, so some error
56// conditions are handled by immediately calling error_box() or
57// otherwise trying to push something to the browser, which should
58// be avoided at all costs. This is also pervasive in the whole
59// core and must be cleaned up entirely before this can be a very
60// functional RPC interface
61require('../include/init.php');
62
63
64
a49f857e 65//FIXME: do we need to put this list somewhere else?
66//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)
67/**
68 * Known core error codes:
69 *
70 * 1 - No RPC action was given in request (please use "rpc_action")
71 * 2 - RPC action was not understood (perhaps a needed plugin is
72 * not installed and activated?)
73 *
74 * Known plugin error codes:
75 *
cd60d608 76 * 500 - Empty Folders plugin empty_folders_purge_trash action failed
77 * 501 - Empty Folders plugin empty_folders_purge_all action failed
78 * 502 - Empty Folders plugin empty_folders_delete_all action failed
5ca6518a 79 * 503 - Mark Read plugin mark_read_read_all action failed
80 * 504 - Mark Read plugin mark_read_unread_all action failed
a49f857e 81 *
82 */
83
84
85
482956f2 86/**
87 * Get RPC Action (can be in either GET or POST)
88 *
89 */
90if (!sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM)) {
5083f41e 91 sm_rpc_return_error('', 1, _("No RPC action given"), 'client', 400, 'Bad Request');
482956f2 92}
93
94
95
96/**
97 * No matter what our response is, the headers
98 * will not change.
99 *
100 */
101$oTemplate->header('Content-Type: text/xml');
102$oTemplate->header('Content-Type: application/xml'); // required by IE
103//FIXME: which anti-cache headers do we want to use?
104$oTemplate->header('Cache-Control: no-cache');
105// $oTemplate->header("Expires: Sat, 1 Jan 2000 00:00:00 GMT");
106// $oTemplate->header("Last-Modified: " . gmdate("D, d M Y H:i:s") . "GMT");
107// $oTemplate->header("Cache-Control: no-cache, must-revalidate");
108// $oTemplate->header("Pragma: no-cache");
109
110
111
112/**
113 * Allow plugins to add their own RPC action
114 * or modify behavior of SM core RPC actions...
115 *
116 * A plugin that handles a custom RPC action must
117 * return TRUE to the hook so that it knows that
118 * the action was handled and was not an unknown
119 * action. If the action was not handled, the plugin
120 * should return FALSE to the hook.
121 *
122 * Developer note: the $rpc_action parameter is passed
123 * in an array in case we can think of more parameters
124 * to add in the future.
125 *
a49f857e 126 * Known users of this hook:
127 * empty_folders
5ca6518a 128 * mark_read
a49f857e 129 *
482956f2 130 */
beb1a2f1 131$temp = array(&$rpc_action);
132$handled_by_plugin = boolean_hook_function('squirrelmail_rpc', $temp, 1);
482956f2 133
134
135
136/**
137 * Go take care of each RPC action (unless plugin already did)
138 *
139 */
140if (!$handled_by_plugin) switch (strtolower($rpc_action)) {
141
142 /**
143 * Delete Messages
144 *
145 */
146 case 'delete_messages':
147
148 require_once(SM_PATH . 'functions/mailbox_display.php');
149 require_once(SM_PATH . 'functions/imap.php');
150
151 if (!sqGetGlobalVar('delete_ids', $delete_ids, SQ_FORM)) {
5083f41e 152 sm_rpc_return_error($rpc_action, 99, _("No deletion ID given"), 'client', 400, 'Bad Request');
482956f2 153 }
154 $delete_ids = explode(',', $delete_ids);
155 if (!sqGetGlobalVar('mailbox', $mailbox, SQ_FORM)) {
5083f41e 156 sm_rpc_return_error($rpc_action, 99, _("No mailbox given"), 'client', 400, 'Bad Request');
482956f2 157 }
158 if (sqGetGlobalVar('startMessage', $startMessage, SQ_INORDER, 1)) {
159 $startMessage = (int) $startMessage;
160 }
161 sqGetGlobalVar('what', $what, SQ_FORM, 0);
162 if (sqGetGlobalVar('account', $iAccount, SQ_GET, 0)) {
163 $iAccount = (int) $iAccount;
164 }
165//FIXME: need to grab the bypass trash variable here too! probably other vars...
166
167/* FIXME: --- The following code was just experimental/proof-of-concept; the rest
168 of the implementation of this functionality still needs to be done "for real"
169 $oImapMessage = new IMAP_Message(0, $mailbox, $startMessage, $what, $iAccount);
170 foreach ($delete_ids as $id) {
171 $oImapMessage->setUid($id);
172 //FIXME: establish constants for $hide values (the 3 below indicates not to show errors, but to return any error string)
173 $result = $oImapMessage->deleteMessage(3);
174 if ($result !== TRUE) {
5083f41e 175 sm_rpc_return_error($rpc_action, 99, $result, 'server', 500, 'Server Error');
482956f2 176 }
177 }
178--- */
179
180 sm_rpc_return_success();
181 //FIXME: Just for testing the line above can be changed to something like this:
5083f41e 182 //sm_rpc_return_success($rpc_action, 0, 'Hooray! Message(s) deleted. Refresh your message list and make sure.');
482956f2 183 break;
184
185
186 /**
187 * Default: error out
188 *
189 */
190 default:
5083f41e 191 sm_rpc_return_error($rpc_action, 2, _("RPC action not understood"), 'client', 400, 'Bad Request');
482956f2 192 break;
193
194}
195
196
197
198/**
199 * Returns an error message to the RPC caller and exits
200 *
201 * NOTE that this function exits and will never return
202 *
5083f41e 203 * @param string $rpc_action The RPC action that is being handled
204 * (OPTIONAL; default attempt to grab from GET/POST)
205 * @param int $error_code The (application-level) error code for the current
206 * error condition
207 * @param string $error_text Any error message associated with the error
208 * condition (OPTIONAL; default empty string)
209 * @param string $guilty_party A string indicating the party who caused the
210 * error: either "client" or "server" (OPTIONAL;
211 * default unspecified)
212 * @param int $http_status_code When non-zero, this value will be sent to
213 * the browser in the HTTP headers as the request
214 * status code (OPTIONAL; default not used)
215 * @param string $http_status_text A string naming the HTTP status, usually the
216 * title of the corresponding status code as
217 * found on:
218 * http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
219 * (OPTIONAL; default not used; $http_status_code
220 * must also be provided).
482956f2 221 *
222 */
5083f41e 223function sm_rpc_return_error($rpc_action=NULL, $error_code,
224 $error_text='', $guilty_party='',
225 $http_status_code=0, $http_status_text='') {
482956f2 226
227 global $oTemplate;
5083f41e 228
229 if (is_null($rpc_action)) sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM);
230
231 if ($http_status_code) {
232 $oTemplate->header('HTTP/1.1 ' . $http_status_code . ' ' . $http_status_text);
233 $oTemplate->header('Status: ' . $http_status_code . ' ' . $http_status_text);
234 }
235
236 $oTemplate->assign('rpc_action', $rpc_action);
237 $oTemplate->assign('error_code', $error_code);
238 $oTemplate->assign('error_text', $error_text);
239 $oTemplate->assign('guilty_party', $guilty_party);
482956f2 240
241 $oTemplate->display('rpc_response_error.tpl');
242
243 exit;
244
245}
246
247
248
249/**
250 * Returns a standard success result to the RPC caller and exits
251 *
252 * NOTE that this function exits and will never return
253 *
5083f41e 254 * @param string $rpc_action The RPC action that is being handled
255 * (OPTIONAL; default attempt to grab from GET/POST)
482956f2 256 * @param int $result_code The result code (OPTIONAL; default 0)
257 * @param string $result_text Any result message (OPTIONAL; default
258 * empty string)
259 *
260 */
5083f41e 261function sm_rpc_return_success($rpc_action=NULL, $result_code=0, $result_text='') {
262
263 if (is_null($rpc_action)) sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM);
482956f2 264
265 global $oTemplate;
5083f41e 266 $oTemplate->assign('rpc_action', $rpc_action);
482956f2 267 $oTemplate->assign('result_code', $result_code);
268 $oTemplate->assign('result_text', $result_text);
269
270 $oTemplate->display('rpc_response_success.tpl');
271
272 exit;
273
274}
275
276
277