plugins/OMB/extlib/libomb/datastore.php

   1 <?php
   2 /**
   3  * This file is part of libomb
   4  *
   5  * PHP version 5
   6  *
   7  * LICENSE: This program is free software: you can redistribute it and/or modify
   8  * it under the terms of the GNU Affero General Public License as published by
   9  * the Free Software Foundation, either version 3 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU Affero General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Affero General Public License
  18  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  19  *
  20  * @package OMB
  21  * @author  Adrian Lang <mail@adrianlang.de>
  22  * @license http://www.gnu.org/licenses/agpl.html GNU AGPL 3.0
  23  * @version 0.1a-20090828
  24  * @link    http://adrianlang.de/libomb
  25  */
  26
  27 require_once 'OAuth.php';
  28
  29 /**
  30  * Data access interface
  31  *
  32  * This interface specifies data access methods libomb needs. It should be
  33  * implemented by libomb users. OMB_Datastore is libomb’s main interface to the
  34  * application’s data. Objects corresponding to this interface are used in
  35  * OMB_Service_Provider and OMB_Service_Consumer.
  36  *
  37  * Note that it’s implemented as a class since OAuthDataStore is as well a
  38  * class, though only declaring methods.
  39  *
  40  * OMB_Datastore extends OAuthDataStore with two OAuth-related methods for token
  41  * revoking and authorizing and all OMB-related methods.
  42  * Refer to OAuth.php for a complete specification of OAuth-related methods.
  43  *
  44  * It is the user’s duty to signal and handle errors. libomb does not check
  45  * return values nor handle exceptions. It is suggested to use exceptions.
  46  * Note that lookup_token and getProfile return null if the requested object
  47  * is not available. This is NOT an error and should not raise an exception.
  48  * Same applies for lookup_nonce which returns a boolean value. These methods
  49  * may nevertheless throw an exception, for example in case of a storage errors.
  50  *
  51  * Most of the parameters passed to these methods are unescaped and unverified
  52  * user input. Therefore they should be handled with extra care to avoid
  53  * security problems like SQL injections.
  54  */
  55 class OMB_Datastore extends OAuthDataStore
  56 {
  57
  58     /*********
  59      * OAUTH *
  60      *********/
  61
  62     /**
  63      * Revoke specified OAuth token
  64      *
  65      * Revokes the authorization token specified by $token_key.
  66      * Throws exceptions in case of error.
  67      *
  68      * @param string $token_key The key of the token to be revoked
  69      *
  70      * @access public
  71      */
  72     public function revoke_token($token_key)
  73     {
  74         throw new Exception();
  75     }
  76
  77     /**
  78      * Authorize specified OAuth token
  79      *
  80      * Authorizes the authorization token specified by $token_key.
  81      * Throws exceptions in case of error.
  82      *
  83      * @param string $token_key The key of the token to be authorized
  84      *
  85      * @access public
  86      */
  87     public function authorize_token($token_key)
  88     {
  89         throw new Exception();
  90     }
  91
  92     /*********
  93      *  OMB  *
  94      *********/
  95
  96     /**
  97      * Get profile by identifying URI
  98      *
  99      * Returns an OMB_Profile object representing the OMB profile identified by
 100      * $identifier_uri.
 101      * Returns null if there is no such OMB profile.
 102      * Throws exceptions in case of other error.
 103      *
 104      * @param string $identifier_uri The OMB identifier URI specifying the
 105      *                               requested profile
 106      *
 107      * @access public
 108      *
 109      * @return OMB_Profile The corresponding profile
 110      */
 111     public function getProfile($identifier_uri)
 112     {
 113         throw new Exception();
 114     }
 115
 116     /**
 117      * Save passed profile
 118      *
 119      * Stores the OMB profile $profile. Overwrites an existing entry.
 120      * Throws exceptions in case of error.
 121      *
 122      * @param OMB_Profile $profile The OMB profile which should be saved
 123      *
 124      * @access public
 125      */
 126     public function saveProfile($profile)
 127     {
 128         throw new Exception();
 129     }
 130
 131     /**
 132      * Save passed notice
 133      *
 134      * Stores the OMB notice $notice. The datastore may change the passed
 135      * notice. This might by necessary for URIs depending on a database key.
 136      * Note that it is the user’s duty to present a mechanism for his
 137      * OMB_Datastore to appropriately change his OMB_Notice.
 138      * Throws exceptions in case of error.
 139      *
 140      * @param OMB_Notice &$notice The OMB notice which should be saved
 141      *
 142      * @access public
 143      */
 144     public function saveNotice(&$notice)
 145     {
 146         throw new Exception();
 147     }
 148
 149     /**
 150      * Get subscriptions of a given profile
 151      *
 152      * Returns an array containing subscription informations for the specified
 153      * profile. Every array entry should in turn be an array with keys
 154      *   'uri´: The identifier URI of the subscriber
 155      *   'token´: The subscribe token
 156      *   'secret´: The secret token
 157      * Throws exceptions in case of error.
 158      *
 159      * @param string $subscribed_user_uri The OMB identifier URI specifying the
 160      *                                    subscribed profile
 161      *
 162      * @access public
 163      *
 164      * @return mixed An array containing the subscriptions or 0 if no
 165      *               subscription has been found.
 166      */
 167     public function getSubscriptions($subscribed_user_uri)
 168     {
 169         throw new Exception();
 170     }
 171
 172     /**
 173      * Delete a subscription
 174      *
 175      * Deletes the subscription from $subscriber_uri to $subscribed_user_uri.
 176      * Throws exceptions in case of error.
 177      *
 178      * @param string $subscriber_uri      The OMB identifier URI specifying the
 179      *                                    subscribing profile
 180      *
 181      * @param string $subscribed_user_uri The OMB identifier URI specifying the
 182      *                                    subscribed profile
 183      *
 184      * @access public
 185      */
 186     public function deleteSubscription($subscriber_uri, $subscribed_user_uri)
 187     {
 188         throw new Exception();
 189     }
 190
 191     /**
 192      * Save a subscription
 193      *
 194      * Saves the subscription from $subscriber_uri to $subscribed_user_uri.
 195      * Throws exceptions in case of error.
 196      *
 197      * @param string     $subscriber_uri      The OMB identifier URI specifying
 198      *                                            the subscribing profile
 199      *
 200      * @param string     $subscribed_user_uri The OMB identifier URI specifying
 201      *                                            the subscribed profile
 202      * @param OAuthToken $token               The access token
 203      *
 204      * @access public
 205      */
 206     public function saveSubscription($subscriber_uri, $subscribed_user_uri,
 207                                      $token)
 208     {
 209         throw new Exception();
 210     }
 211 }
 212 ?>