folks/backend.vala

   1 /*
   2  * Copyright (C) 2010 Collabora Ltd.
   3  *
   4  * This library is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License as published by
   6  * the Free Software Foundation, either version 2.1 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public License
  15  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  16  *
  17  * Authors:
  18  *       Travis Reitter <travis.reitter@collabora.co.uk>
  19  */
  20
  21 using GLib;
  22 using Gee;
  23
  24 /**
  25  * A single backend to libfolks, such as Telepathy or evolution-data-server.
  26  * Each backend provides {@link Persona}s which are aggregated to form
  27  * {@link Individual}s.
  28  *
  29  * After creating a Backend instance, you must connect to the
  30  * {@link Backend.persona_store_added} and
  31  * {@link Backend.persona_store_removed} signals, //then// call
  32  * {@link Backend.prepare}, otherwise a race condition may occur between
  33  * emission of {@link Backend.persona_store_added} and your code connecting to
  34  * it.
  35  */
  36 public abstract class Folks.Backend : Object
  37 {
  38   construct
  39     {
  40       debug ("Constructing Backend ‘%s’ (%p)", this.name, this);
  41     }
  42
  43   ~Backend ()
  44     {
  45       debug ("Destroying Backend ‘%s’ (%p)", this.name, this);
  46     }
  47
  48   /**
  49    * Whether {@link Backend.prepare} has successfully completed for this
  50    * backend.
  51    *
  52    * @since 0.3.0
  53    */
  54   public abstract bool is_prepared { get; default = false; }
  55
  56   /**
  57    * Whether the backend has reached a quiescent state. This will happen at some
  58    * point after {@link Backend.prepare} has successfully completed for the
  59    * backend. A backend is in a quiescent state when all the
  60    * {@link PersonaStore}s that it originally knows about have been loaded.
  61    *
  62    * It's guaranteed that this property's value will only ever change after
  63    * {@link Backend.is_prepared} has changed to `true`.
  64    *
  65    * When {@link Backend.unprepare} is called, this will be reset to `false`.
  66    *
  67    * @since 0.6.2
  68    */
  69   public abstract bool is_quiescent { get; default = false; }
  70
  71   /**
  72    * A unique name for the backend.
  73    *
  74    * This will be used to identify the backend, and should also be used as the
  75    * {@link PersonaStore.type_id} of the {@link PersonaStore}s used by the
  76    * backend.
  77    *
  78    * This is guaranteed to always be available; even before
  79    * {@link Backend.prepare} is called.
  80    */
  81   public abstract string name { get; }
  82
  83   /**
  84    * The {@link PersonaStore}s in use by the backend.
  85    *
  86    * A backend may expose {@link Persona}s from multiple servers or accounts
  87    * (for example), so may have a {@link PersonaStore} for each.
  88    *
  89    * @since 0.5.1
  90    */
  91   public abstract Map<string, PersonaStore> persona_stores { get; }
  92
  93   /**
  94    * Emitted when a {@link PersonaStore} is added to the backend.
  95    *
  96    * This will not be emitted until after {@link Backend.prepare} has been
  97    * called.
  98    *
  99    * @param store the {@link PersonaStore}
 100    */
 101   public abstract signal void persona_store_added (PersonaStore store);
 102
 103   /**
 104    * Emitted when a {@link PersonaStore} is removed from the backend.
 105    *
 106    * This will not be emitted until after {@link Backend.prepare} has been
 107    * called.
 108    *
 109    * @param store the {@link PersonaStore}
 110    */
 111   public abstract signal void persona_store_removed (PersonaStore store);
 112
 113   /**
 114    * Prepare the Backend for use.
 115    *
 116    * This connects the Backend to whichever backend-specific services it
 117    * requires, and causes it to create its {@link PersonaStore}s. This should be
 118    * called //after// connecting to the {@link Backend.persona_store_added} and
 119    * {@link Backend.persona_store_removed} signals, or a race condition could
 120    * occur, with the signals being emitted before your code has connected to
 121    * them, and {@link PersonaStore}s getting "lost" as a result.
 122    *
 123    * This is normally handled transparently by the {@link IndividualAggregator}.
 124    *
 125    * If this function throws an error, the Backend will not be functional.
 126    *
 127    * This function is guaranteed to be idempotent (since version 0.3.0).
 128    *
 129    * Concurrent calls to this function from different threads will block until
 130    * preparation has completed. However, concurrent calls to this function from
 131    * a single thread might not, i.e. the first call will block but subsequent
 132    * calls might return before the first one. (Though they will be safe in every
 133    * other respect.)
 134    *
 135    * @since 0.1.11
 136    */
 137   public abstract async void prepare () throws GLib.Error;
 138
 139   /**
 140    * Revert the Backend to its pre-prepared state.
 141    *
 142    * This will disconnect this Backend and its dependencies from their
 143    * respective services and the Backend will issue
 144    * {@link Backend.persona_store_removed} for each of its
 145    * {@link PersonaStore}s.
 146    *
 147    * Most users won't need to use this function.
 148    *
 149    * If this function throws an error, the Backend will not be functional.
 150    *
 151    * Concurrent calls to this function from different threads will block until
 152    * preparation has completed. However, concurrent calls to this function from
 153    * a single thread might not, i.e. the first call will block but subsequent
 154    * calls might return before the first one. (Though they will be safe in every
 155    * other respect.)
 156    *
 157    * @since 0.3.2
 158    */
 159   public abstract async void unprepare () throws GLib.Error;
 160 }