extlib/libomb/datastore.php

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