X-Git-Url: http://git.polytechnique.org/?a=blobdiff_plain;f=classes%2Fplmodule.php;h=4f30acd4ff67605c04c55d82f1563c330d607cb2;hb=fa7ffd661d77b24cdb385aca7bdb04c938214061;hp=55de69f15af7c817105a20594d4bd208608ebcda;hpb=46ca2746b59162c026f67271c5583fa2f20f5c4c;p=platal.git

diff --git a/classes/plmodule.php b/classes/plmodule.php
index 55de69f..4f30acd 100644
--- a/classes/plmodule.php
+++ b/classes/plmodule.php
@@ -1,6 +1,6 @@
 <?php
 /***************************************************************************
- *  Copyright (C) 2003-2010 Polytechnique.org                              *
+ *  Copyright (C) 2003-2011 Polytechnique.org                              *
  *  http://opensource.polytechnique.org/                                   *
  *                                                                         *
  *  This program is free software; you can redistribute it and/or modify   *
@@ -34,24 +34,71 @@ abstract class PLModule
     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 new PlStdHook(array($this, 'handler_' . $fun),
-                             $auth, $perms, $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.
@@ -75,7 +122,7 @@ abstract class PLModule
     {
         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;
         }
@@ -94,5 +141,5 @@ abstract class PLModule
     }
 }
 
-// vim:set et sw=4 sts=4 sws=4 foldmethod=marker enc=utf-8:
+// vim:set et sw=4 sts=4 sws=4 foldmethod=marker fenc=utf-8:
 ?>