<?php
/***************************************************************************
- * Copyright (C) 2003-2009 Polytechnique.org *
+ * Copyright (C) 2003-2011 Polytechnique.org *
* http://opensource.polytechnique.org/ *
* *
* This program is free software; you can redistribute it and/or modify *
abstract public function handlers();
/** Register a hook
- * @param fun name of the handler (the exact name will be handler_$fun)
- * @param auth authentification level of needed to run this handler
+ * @param fun name of the handler (the exact name will be handler_$fun); the
+ * handler will be invoked with the PlPage object, and the unmatched path
+ * components
+ * @param auth authentification level required to run this handler
* @param perms permission required to run this handler
* @param type additionnal flags
*
* Perms syntax is the following:
- * perms = rights(,rights)*
- * rights = right(:right)*
+ * perms = rights(,rights)*
+ * rights = right(:right)*
* right is an atomic right permission (like 'admin', 'user', 'groupadmin', 'groupmember'...)
*
- * If type is set to NO_AUTH, the system will return 403 instead of asking auth data
- * this is useful for Ajax handler
- * If type is not set to NO_SKIN, the system will consider redirecting the user to https
+ * If type is set to NO_AUTH, the system will return 403 instead of asking
+ * auth data; this is useful for Ajax handler. If type is not set to
+ * NO_SKIN, the system will consider redirecting the user to https.
*/
public function make_hook($fun, $auth, $perms = 'user', $type = DO_AUTH)
{
- return array('hook' => array($this, 'handler_'.$fun),
- 'auth' => $auth,
- 'perms' => $perms,
- 'type' => $type);
+ return new PlStdHook(array($this, 'handler_' . $fun), $auth, $perms, $type);
+ }
+
+ /** Register an API hook.
+ * @param fun name of the handler (the exact name will be handler_$fun); the
+ * handler will be invoked with a PlPage, the authenticated PlUser, the
+ * JSON-decoded payload (if any), and the unmatched path components
+ * @param auth authentification level required, when not API-authenticated
+ * @param perms permission required to run this handler
+ * @param type additionnal flags (only NO_HTTPS is supported at the moment)
+ *
+ * See {@link make_hook} above for details on permissions.
+ *
+ * WARNING: It is expected that the API authentication mechanism will not be
+ * protected against short-term replay of requests (for instance replay of a
+ * given request within 5-10 seconds).
+ *
+ * You are explicitly advised to make any API request idempotent (eg. use
+ * "DELETE /api/email/foo@example.com" instead of "DELETE /api/email/0" to
+ * delete the first email in a list).
+ */
+ public function make_api_hook($fun, $auth, $perms = 'user', $type = NO_AUTH)
+ {
+ return new PlApiHook(array($this, 'handler_' . $fun), $auth, $perms, $type);
+ }
+
+ /** Register a token-authentified hook (rss, csv, ical, ...)
+ * @param fun name of the handler (the exact name will be handler_$fun); the
+ * handler will be invoked with the PlPage object, the PlUser of the
+ * request, and the unmatched path components
+ * @param auth authentification level required, when not token-authentified
+ * @param perms permission required to run this handler
+ * @param type additionnal flags
+ *
+ * See {@link make_hook} above for details on permissions and additional
+ * flags. Note that DO_AUTH has no effect here, as the request will always
+ * be passively identified.
+ *
+ * This hook requires that the first two unmatched path components form a
+ * valid (user, token) pair; if not, a session-based authentification will
+ * be attempted, in which case $auth will be honored.
+ * Note that because token-based authentication is weak, it should only be
+ * used for readonly handlers normally served in AUTH_COOKIE.
+ */
+ public function make_token_hook($fun, $auth, $perms = 'user', $type = NO_HTTPS)
+ {
+ return new PlTokenHook(array($this, 'handler_' . $fun), $auth, $perms, $type);
+ }
+
+ /** Register a hook that points to a wiki page.
+ */
+ public function make_wiki_hook($auth = AUTH_PUBLIC, $perms = 'user', $type = DO_AUTH)
+ {
+ return new PlWikiHook($auth, $perms, $type);
}
/** Include a 'module-specific' file.
{
global $globals;
if ($modname == 'core') {
- $mod_path = $globals->spoolroot . '/core/modules/' . $modname;
+ $mod_path = $globals->coreroot . '/modules/' . $modname;
} else {
$mod_path = $globals->spoolroot . '/modules/' . $modname;
}