<?php
/***************************************************************************
 *  Copyright (C) 2003-2011 Polytechnique.org                              *
 *  http://opensource.polytechnique.org/                                   *
 *                                                                         *
 *  This program is free software; you can redistribute it and/or modify   *
 *  it under the terms of the GNU General Public License as published by   *
 *  the Free Software Foundation; either version 2 of the License, or      *
 *  (at your option) any later version.                                    *
 *                                                                         *
 *  This program is distributed in the hope that it will be useful,        *
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of         *
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
 *  GNU General Public License for more details.                           *
 *                                                                         *
 *  You should have received a copy of the GNU General Public License      *
 *  along with this program; if not, write to the Free Software            *
 *  Foundation, Inc.,                                                      *
 *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA                *
 ***************************************************************************/

abstract class PLModule
{
    /** Path of the includes of the module
     * Internal use only.
     */
    private $modIncludePath;

    /** Return an array associating pathes to the corresponding hook.
     * array( '/my/path' => make_hook(...),
     *        ...);
     * @ref make_hook
     */
    abstract public function handlers();

    /** Register a hook
     * @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)*
     * 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.
     */
    public function make_hook($fun, $auth, $perms = 'user', $type = DO_AUTH)
    {
        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.
     * Module specific includes must be in the in the path modules/{modulename}.
     */
    public function load($file)
    {
        require_once $this->modIncludePath . $file;
    }

    /* static functions */

    public static function path($modname)
    {
        global $globals;
        if ($modname == 'core') {
            $mod_path = $globals->coreroot  . '/modules/' . $modname;
        } else {
            $mod_path = $globals->spoolroot . '/modules/' . $modname;
        }
        return $mod_path;
    }

    public static function factory($modname)
    {
        $mod_path = self::path($modname);
        $class    = ucfirst($modname) . 'Module';

        require_once $mod_path . '.php';
        $module = new $class();
        $module->modIncludePath = $mod_path . '/';
        return $module;
    }
}

// vim:set et sw=4 sts=4 sws=4 foldmethod=marker fenc=utf-8:
?>