Happy New Year
[squirrelmail.git] / src / squirrelmail_rpc.php
1 <?php
2
3 /**
4 * squirrelmail_rpc.php
5 *
6 * This file contains the entry point to the "SquirrelMail API" -- the
7 * remote procedure call request receiver.
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.
15 *
16 * @copyright 1999-2018 The SquirrelMail Project Team
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 */
23
24 /** This is the squirrelmail_rpc page */
25 define('PAGE_NAME', 'squirrelmail_rpc');
26
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
30 //http://example.org/squirrelmail/src/squirrelmail_rpc.php?page=read_body&passed_id=47633...
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
61 require('../include/init.php');
62
63
64
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 *
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
79 * 503 - Mark Read plugin mark_read_read_all action failed
80 * 504 - Mark Read plugin mark_read_unread_all action failed
81 *
82 */
83
84
85
86 /**
87 * Get RPC Action (can be in either GET or POST)
88 *
89 */
90 if (!sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM)) {
91 sm_rpc_return_error('', 1, _("No RPC action given"), 'client', 400, 'Bad Request');
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 $oTemplate->header('Pragma: no-cache');
104 $oTemplate->header('Cache-Control: no-cache, no-store, must-revalidate, max-age=0');
105 $oTemplate->header('Expires: Sat, 1 Jan 2000 00:00:00 GMT');
106 //TODO: is this needed? $oTemplate->header('Last-Modified: ' . gmdate('D, d M Y H:i:s') . 'GMT');
107
108
109
110 /**
111 * Allow plugins to add their own RPC action
112 * or modify behavior of SM core RPC actions...
113 *
114 * A plugin that handles a custom RPC action must
115 * return TRUE to the hook so that it knows that
116 * the action was handled and was not an unknown
117 * action. If the action was not handled, the plugin
118 * should return FALSE to the hook.
119 *
120 * Developer note: the $rpc_action parameter is passed
121 * in an array in case we can think of more parameters
122 * to add in the future.
123 *
124 * Known users of this hook:
125 * empty_folders
126 * mark_read
127 *
128 */
129 $temp = array(&$rpc_action);
130 $handled_by_plugin = boolean_hook_function('squirrelmail_rpc', $temp, 1);
131
132
133
134 /**
135 * Go take care of each RPC action (unless plugin already did)
136 *
137 */
138 if (!$handled_by_plugin) switch (strtolower($rpc_action)) {
139
140 /**
141 * Delete Messages
142 *
143 */
144 case 'delete_messages':
145
146 require_once(SM_PATH . 'functions/mailbox_display.php');
147 require_once(SM_PATH . 'functions/imap.php');
148
149 if (!sqGetGlobalVar('delete_ids', $delete_ids, SQ_FORM)) {
150 sm_rpc_return_error($rpc_action, 99, _("No deletion ID given"), 'client', 400, 'Bad Request');
151 }
152 $delete_ids = explode(',', $delete_ids);
153 if (!sqGetGlobalVar('mailbox', $mailbox, SQ_FORM)) {
154 sm_rpc_return_error($rpc_action, 99, _("No mailbox given"), 'client', 400, 'Bad Request');
155 }
156 if (sqGetGlobalVar('startMessage', $startMessage, SQ_INORDER, 1)) {
157 $startMessage = (int) $startMessage;
158 }
159 sqGetGlobalVar('what', $what, SQ_FORM, 0);
160 if (sqGetGlobalVar('account', $iAccount, SQ_GET, 0)) {
161 $iAccount = (int) $iAccount;
162 }
163 //FIXME: need to grab the bypass trash variable here too! probably other vars...
164
165 /* FIXME: --- The following code was just experimental/proof-of-concept; the rest
166 of the implementation of this functionality still needs to be done "for real"
167 $oImapMessage = new IMAP_Message(0, $mailbox, $startMessage, $what, $iAccount);
168 foreach ($delete_ids as $id) {
169 $oImapMessage->setUid($id);
170 //FIXME: establish constants for $hide values (the 3 below indicates not to show errors, but to return any error string)
171 $result = $oImapMessage->deleteMessage(3);
172 if ($result !== TRUE) {
173 sm_rpc_return_error($rpc_action, 99, $result, 'server', 500, 'Server Error');
174 }
175 }
176 --- */
177
178 sm_rpc_return_success();
179 //FIXME: Just for testing the line above can be changed to something like this:
180 //sm_rpc_return_success($rpc_action, 0, 'Hooray! Message(s) deleted. Refresh your message list and make sure.');
181 break;
182
183
184 /**
185 * Default: error out
186 *
187 */
188 default:
189 sm_rpc_return_error($rpc_action, 2, _("RPC action not understood"), 'client', 400, 'Bad Request');
190 break;
191
192 }
193
194
195
196 /**
197 * Returns an error message to the RPC caller and exits
198 *
199 * NOTE that this function exits and will never return
200 *
201 * @param string $rpc_action The RPC action that is being handled
202 * (OPTIONAL; default attempt to grab from GET/POST)
203 * @param int $error_code The (application-level) error code for the current
204 * error condition
205 * @param string $error_text Any error message associated with the error
206 * condition (OPTIONAL; default empty string)
207 * @param string $guilty_party A string indicating the party who caused the
208 * error: either "client" or "server" (OPTIONAL;
209 * default unspecified)
210 * @param int $http_status_code When non-zero, this value will be sent to
211 * the browser in the HTTP headers as the request
212 * status code (OPTIONAL; default not used)
213 * @param string $http_status_text A string naming the HTTP status, usually the
214 * title of the corresponding status code as
215 * found on:
216 * http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
217 * (OPTIONAL; default not used; $http_status_code
218 * must also be provided).
219 *
220 */
221 function sm_rpc_return_error($rpc_action=NULL, $error_code,
222 $error_text='', $guilty_party='',
223 $http_status_code=0, $http_status_text='') {
224
225 global $oTemplate;
226
227 if (is_null($rpc_action)) sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM);
228
229 if ($http_status_code) {
230 $oTemplate->header('HTTP/1.1 ' . $http_status_code . ' ' . $http_status_text);
231 $oTemplate->header('Status: ' . $http_status_code . ' ' . $http_status_text);
232 }
233
234 $oTemplate->assign('rpc_action', $rpc_action);
235 $oTemplate->assign('error_code', $error_code);
236 $oTemplate->assign('error_text', $error_text);
237 $oTemplate->assign('guilty_party', $guilty_party);
238
239 $oTemplate->display('rpc_response_error.tpl');
240
241 exit;
242
243 }
244
245
246
247 /**
248 * Returns a standard success result to the RPC caller and exits
249 *
250 * NOTE that this function exits and will never return
251 *
252 * @param string $rpc_action The RPC action that is being handled
253 * (OPTIONAL; default attempt to grab from GET/POST)
254 * @param int $result_code The result code (OPTIONAL; default 0)
255 * @param string $result_text Any result message (OPTIONAL; default
256 * empty string)
257 *
258 */
259 function sm_rpc_return_success($rpc_action=NULL, $result_code=0, $result_text='') {
260
261 if (is_null($rpc_action)) sqGetGlobalVar('rpc_action', $rpc_action, SQ_FORM);
262
263 global $oTemplate;
264 $oTemplate->assign('rpc_action', $rpc_action);
265 $oTemplate->assign('result_code', $result_code);
266 $oTemplate->assign('result_text', $result_text);
267
268 $oTemplate->display('rpc_response_success.tpl');
269
270 exit;
271
272 }
273
274
275