libs/glibmm2/gio/giomm/asyncresult.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GIOMM_ASYNCRESULT_H
   4 #define _GIOMM_ASYNCRESULT_H
   5
   6
   7 #include <glibmm.h>
   8
   9 // -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  10
  11 /* Copyright (C) 2007 The giomm Development Team
  12  *
  13  * This library is free software; you can redistribute it and/or
  14  * modify it under the terms of the GNU Library General Public
  15  * License as published by the Free Software Foundation; either
  16  * version 2 of the License, or (at your option) any later version.
  17  *
  18  * This library is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21  * Library General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU Library General Public
  24  * License along with this library; if not, write to the Free
  25  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  26  */
  27
  28 #include <glibmm/interface.h>
  29 #include <glibmm/object.h>
  30
  31
  32 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  33 typedef struct _GAsyncResultIface GAsyncResultIface;
  34 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  35
  36 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  37 typedef struct _GAsyncResult GAsyncResult;
  38 typedef struct _GAsyncResultClass GAsyncResultClass;
  39 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  40
  41
  42 namespace Gio
  43 { class AsyncResult_Class; } // namespace Gio
  44 namespace Gio
  45 {
  46
  47 class AsyncResult;
  48
  49 /** A function that will be called when an asynchronous operation within GIO has been completed.
  50  * @param result The asynchronous function's results.
  51  *
  52  * For instance,
  53  * @code
  54  * void on_async_ready(Glib::RefPtr<AsyncResult>& result);
  55  * @endcode
  56  *
  57  * @newin2p16
  58  */
  59 typedef sigc::slot<void, Glib::RefPtr<AsyncResult>& > SlotAsyncReady;
  60
  61 /** Provides a base class for implementing asynchronous function results.
  62  * Asynchronous operations are broken up into two separate operations which are chained together by a SlotAsyncReady.
  63  * To begin an asynchronous operation, provide a SlotAsyncReady to the asynchronous function. This callback will be triggered
  64  * when the operation has completed, and will be passed an AsyncResult instance filled with the details of the operation's success or
  65  * failure, the object the asynchronous function was started for and any error codes returned. The asynchronous callback function is then
  66  * expected to call the corresponding "_finish()" function with the object the function was called for, and the AsyncResult instance.
  67  *
  68  * The purpose of the "_finish()" function is to take the generic result of type AsyncResult and return the specific result that the operation
  69  * in question yields (e.g. a FileEnumerator for an "enumerate children" operation). If the result or error status of the operation is not needed,
  70  * there is no need to call the "_finish()" function and GIO will take care of cleaning up the result and error information after the
  71  * SlotAsyncReady returns. You may also store the AsyncResult and call "_finish()" later.
  72  *
  73  * Example of a typical asynchronous operation flow:
  74  * @code
  75  * void _theoretical_frobnitz_async(const Glib::RefPtr<Theoretical>& t,
  76  *                                  const SlotAsyncReady& slot);
  77  *
  78  * gboolean _theoretical_frobnitz_finish(const Glib::RefPtr<Theoretical>& t,
  79  *                                       const Glib::RefPtr<AsyncResult>& result);
  80  *
  81  * static void
  82  * on_frobnitz_result(Glib::RefPtr<AsyncResult>& result)
  83  * {
  84  *
  85  *   Glib::RefPtr<Glib::Object> source_object = result->get_source_object();
  86  *   bool success = _theoretical_frobnitz_finish(source_object, res);
  87  *
  88  *   if (success)
  89  *     std::cout << "Hurray" << std::endl;
  90  *   else
  91  *     std::cout << "Uh oh!" << std::endl;
  92  *
  93  *   ...
  94  * }
  95  *
  96  * int main (int argc, void *argv[])
  97  * {
  98  *    ...
  99  *
 100  *    _theoretical_frobnitz_async (theoretical_data,
 101  *                                 sigc::ptr_fun(&on_frobnitz_result) );
 102  *
 103  *    ...
 104  * }
 105  * @endcode
 106  *
 107  * The async function could also take an optional Glib::Cancellable object, allowing the calling function to cancel the asynchronous operation.
 108  *
 109  * The callback for an asynchronous operation is called only once, and is always called, even in the case of a cancelled operation.
 110  * On cancellation the result is a ERROR_CANCELLED error.
 111  *
 112  * Some ascynchronous operations are implemented using synchronous calls. These are run in a separate GThread, but otherwise they are sent
 113  * to the Main Event Loop and processed in an idle function. So, if you truly need asynchronous operations, make sure to initialize GThread.
 114  *
 115  * @newin2p16
 116  */
 117
 118 class AsyncResult : public Glib::Interface
 119 {
 120
 121 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 122
 123 public:
 124   typedef AsyncResult CppObjectType;
 125   typedef AsyncResult_Class CppClassType;
 126   typedef GAsyncResult BaseObjectType;
 127   typedef GAsyncResultIface BaseClassType;
 128
 129 private:
 130   friend class AsyncResult_Class;
 131   static CppClassType asyncresult_class_;
 132
 133   // noncopyable
 134   AsyncResult(const AsyncResult&);
 135   AsyncResult& operator=(const AsyncResult&);
 136
 137 protected:
 138   AsyncResult(); // you must derive from this class
 139
 140   /** Called by constructors of derived classes. Provide the result of
 141    * the Class init() function to ensure that it is properly
 142    * initialized.
 143    *
 144    * @param interface_class The Class object for the derived type.
 145    */
 146   explicit AsyncResult(const Glib::Interface_Class& interface_class);
 147
 148 public:
 149   // This is public so that C++ wrapper instances can be
 150   // created for C instances of unwrapped types.
 151   // For instance, if an unexpected C type implements the C interface.
 152   explicit AsyncResult(GAsyncResult* castitem);
 153
 154 protected:
 155 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 156
 157 public:
 158   virtual ~AsyncResult();
 159
 160   static void add_interface(GType gtype_implementer);
 161
 162 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 163   static GType get_type()      G_GNUC_CONST;
 164   static GType get_base_type() G_GNUC_CONST;
 165 #endif
 166
 167   ///Provides access to the underlying C GObject.
 168   GAsyncResult*       gobj()       { return reinterpret_cast<GAsyncResult*>(gobject_); }
 169
 170   ///Provides access to the underlying C GObject.
 171   const GAsyncResult* gobj() const { return reinterpret_cast<GAsyncResult*>(gobject_); }
 172
 173 private:
 174
 175
 176 public:
 177
 178
 179   //Note that this returns a reference, unlike most GTK+ get_*() functions,
 180   //so we don't need to use refreturn.
 181
 182   /** Gets the source object from a AsyncResult.
 183    * @return The source object for the @a res.
 184    */
 185   Glib::RefPtr<Glib::Object> get_source_object();
 186
 187   /** Gets the source object from a AsyncResult.
 188    * @return The source object for the @a res.
 189    */
 190   Glib::RefPtr<const Glib::Object> get_source_object() const;
 191
 192   #ifdef GLIBMM_VFUNCS_ENABLED
 193   virtual Glib::RefPtr<Glib::Object> get_source_object_vfunc();
 194 #endif //GLIBMM_VFUNCS_ENABLED
 195
 196
 197 public:
 198
 199 public:
 200   //C++ methods used to invoke GTK+ virtual functions:
 201 #ifdef GLIBMM_VFUNCS_ENABLED
 202 #endif //GLIBMM_VFUNCS_ENABLED
 203
 204 protected:
 205   //GTK+ Virtual Functions (override these to change behaviour):
 206 #ifdef GLIBMM_VFUNCS_ENABLED
 207 #endif //GLIBMM_VFUNCS_ENABLED
 208
 209   //Default Signal Handlers::
 210 #ifdef GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 211 #endif //GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 212
 213
 214 };
 215
 216 } // namespace Gio
 217
 218
 219 namespace Glib
 220 {
 221   /** A Glib::wrap() method for this object.
 222    *
 223    * @param object The C instance.
 224    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 225    * @result A C++ instance that wraps this C instance.
 226    *
 227    * @relates Gio::AsyncResult
 228    */
 229   Glib::RefPtr<Gio::AsyncResult> wrap(GAsyncResult* object, bool take_copy = false);
 230
 231 } // namespace Glib
 232
 233
 234 #endif /* _GIOMM_ASYNCRESULT_H */
 235