GNOME.org
 

glibmm r504 - in trunk: . gio/src

Author: murrayc
Date: Fri Jan 11 02:15:46 2008
New Revision: 504
URL: http://svn.gnome.org/viewvc/glibmm?rev=504&view=rev

Log:
2008-01-11  Murray Cumming  <murrayc murrayc com>

* gio/src/Makefile_list_of_hg.am_fragment:
* gio/src/seekable.ccg:
* gio/src/seekable.hg: Added the Seekable interface, though it 
has not methods yet.
* gio/src/fileinputstream.hg:
* gio/src/fileoutputstream.hg: Derive/implement Seekable.
* gio/src/icon.hg:
* gio/src/inputstream.hg:
* gio/src/loadableicon.hg:
* gio/src/mountoperation.hg:
* gio/src/outputstream.hg:
* gio/src/simpleasyncresult.hg:
* gio/src/volume.hg: Added class documentation, based on the C 
documentation.

Added:
   trunk/gio/src/seekable.ccg
      - copied, changed from r503, /trunk/gio/src/fileinputstream.ccg
   trunk/gio/src/seekable.hg
      - copied, changed from r503, /trunk/gio/src/fileinputstream.hg
Modified:
   trunk/ChangeLog
   trunk/gio/src/Makefile_list_of_hg.am_fragment
   trunk/gio/src/fileinputstream.hg
   trunk/gio/src/fileoutputstream.hg
   trunk/gio/src/icon.hg
   trunk/gio/src/inputstream.hg
   trunk/gio/src/loadableicon.hg
   trunk/gio/src/mountoperation.hg
   trunk/gio/src/outputstream.hg
   trunk/gio/src/simpleasyncresult.hg
   trunk/gio/src/volume.hg

Modified: trunk/gio/src/Makefile_list_of_hg.am_fragment
==============================================================================
--- trunk/gio/src/Makefile_list_of_hg.am_fragment	(original)
+++ trunk/gio/src/Makefile_list_of_hg.am_fragment	Fri Jan 11 02:15:46 2008
@@ -5,7 +5,7 @@
 
 files_posix_hg =
 files_win32_hg =
-files_general_hg = appinfo.hg asyncresult.hg cancellable.hg drive.hg file.hg fileattribute.hg fileenumerator.hg fileicon.hg fileinfo.hg fileinputstream.hg fileoutputstream.hg icon.hg inputstream.hg loadableicon.hg mountoperation.hg outputstream.hg simpleasyncresult.hg volume.hg
+files_general_hg = appinfo.hg asyncresult.hg cancellable.hg drive.hg file.hg fileattribute.hg fileenumerator.hg fileicon.hg fileinfo.hg fileinputstream.hg fileoutputstream.hg icon.hg inputstream.hg loadableicon.hg mountoperation.hg outputstream.hg seekable.hg simpleasyncresult.hg volume.hg
 
 include $(top_srcdir)/build_shared/Makefile_build_gensrc.am_fragment
 

Modified: trunk/gio/src/fileinputstream.hg
==============================================================================
--- trunk/gio/src/fileinputstream.hg	(original)
+++ trunk/gio/src/fileinputstream.hg	Fri Jan 11 02:15:46 2008
@@ -19,10 +19,11 @@
 
 #include <gio/gio.h>
 
-#include <glibmm/iochannel.h>
-#include <glibmm/object.h>
 #include <giomm/fileinfo.h>
 #include <giomm/inputstream.h>
+#include <giomm/seekable.h>
+#include <glibmm/iochannel.h>
+#include <glibmm/object.h>
 
 _DEFS(giomm,gio)
 _PINCLUDE(giomm/private/inputstream_p.h)
@@ -39,9 +40,12 @@
  * for seeking and positioning. To find the position of a file input stream, use tell(). To find out if a file input stream supports 
  * seeking, use can_seek(). To position a file input stream, use seek().
  */
-class FileInputStream : public InputStream
+class FileInputStream 
+: public Gio::InputStream, 
+  public Seekable
 {
   _CLASS_GOBJECT(FileInputStream, GFileInputStream, G_FILE_INPUT_STREAM, Gio::InputStream, GInputStream)
+  _IMPLEMENTS_INTERFACE(Seekable)
 
 public:
   _WRAP_METHOD(Glib::RefPtr<FileInfo> query_info(const std::string& attributes, const Glib::RefPtr<Cancellable>& cancellable),

Modified: trunk/gio/src/fileoutputstream.hg
==============================================================================
--- trunk/gio/src/fileoutputstream.hg	(original)
+++ trunk/gio/src/fileoutputstream.hg	Fri Jan 11 02:15:46 2008
@@ -19,10 +19,12 @@
 
 #include <gio/gio.h>
 
-#include <glibmm/object.h>
+#include <giomm/outputstream.h>
+#include <giomm/seekable.h>
 #include <giomm/fileinfo.h>
+#include <glibmm/object.h>
 #include <glibmm/iochannel.h>
-#include <giomm/outputstream.h>
+
 
 _DEFS(giomm,gio)
 _PINCLUDE(giomm/private/outputstream_p.h)
@@ -30,9 +32,24 @@
 namespace Gio
 {
 
-class FileOutputStream : public OutputStream
+/** FileOutputStream provides output streams that write their content to a file.
+ *
+ * FileOutputStream implements Seekable, which allows the output stream to jump 
+ * to arbitrary positions in the file and to truncate the file, provided the 
+ * filesystem of the file supports these operations. In addition to the generic 
+ * Seekable API, FileOutputStream has its own API for seeking and positioning. 
+ * To find the position of a file output stream, use stream_tell(). To find 
+ * out if a file output stream supports seeking, use can_seek(). To position a 
+ * file output stream, use seek(). To find out if a file output stream supports 
+ * truncating, use can_truncate(). To truncate a file output stream, use 
+ * truncate().
+ */
+class FileOutputStream
+: public OutputStream,
+  public Seekable
 {
   _CLASS_GOBJECT(FileOutputStream, GFileOutputStream, G_FILE_OUTPUT_STREAM, Gio::OutputStream, GOutputStream)
+  _IMPLEMENTS_INTERFACE(Seekable)
 
 public:
   //TODO: vfuncs and overloads without Cancellable
@@ -43,7 +60,7 @@
 
   _IGNORE(g_file_input_stream_query_info_async)
   void query_info_async(const std::string& attributes, int io_priority, Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
-  //TODO: cancellable can probalby be NULL.
+  //TODO: cancellable can probably be NULL.
 
   _WRAP_METHOD(Glib::RefPtr<FileInfo> query_info_finish(const Glib::RefPtr<AsyncResult>& result),
                g_file_output_stream_query_info_finish,

Modified: trunk/gio/src/icon.hg
==============================================================================
--- trunk/gio/src/icon.hg	(original)
+++ trunk/gio/src/icon.hg	Fri Jan 11 02:15:46 2008
@@ -27,6 +27,14 @@
 namespace Gio
 {
 
+/** This is a very minimal interface for icons. It provides functions for checking the equality of two icons and hashing of icons.
+ * Glib::Icon does not provide the actual pixmap for the icon as this is out of GIO's scope. However implementations of Icon may contain the name of an 
+ * icon (see ThemedIcon), or the path to an icon (see LoadableIcon).
+ *
+ * To obtain a hash of an Icon instance, see hash().
+ *
+ * To check if two Icon instances are equal, see equal().
+ */
 class Icon : public Glib::Interface
 {
   _CLASS_INTERFACE(Icon, GIcon, G_ICON, GIconIface)
@@ -46,6 +54,11 @@
   // to have it generally...
 };
 
+//TODO: I'm not very happy about these operator==. 
+//RefPtr already has operator== that just checks the pointers for equality, 
+//and this would be adding an implicit change of behaviour to those.
+//murrayc.
+
 /** @relates Gio::Icon */
 inline bool operator==(const Glib::RefPtr<Icon>& lhs,
                        const Glib::RefPtr<Icon>& rhs)

Modified: trunk/gio/src/inputstream.hg
==============================================================================
--- trunk/gio/src/inputstream.hg	(original)
+++ trunk/gio/src/inputstream.hg	Fri Jan 11 02:15:46 2008
@@ -30,6 +30,8 @@
 namespace Gio
 {
 
+/** Base class for implementing streaming input.
+ */
 class InputStream : public Glib::Object
 {
   _CLASS_GOBJECT(InputStream, GInputStream, G_INPUT_STREAM, Glib::Object, GObject)

Modified: trunk/gio/src/loadableicon.hg
==============================================================================
--- trunk/gio/src/loadableicon.hg	(original)
+++ trunk/gio/src/loadableicon.hg	Fri Jan 11 02:15:46 2008
@@ -27,6 +27,10 @@
 namespace Gio
 {
 
+//TODO: Derive from Icon?
+
+/** Extends the Icon interface and adds the ability to load icons from streams.
+ */
 class LoadableIcon : public Glib::Interface
 {
   _CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIface)

Modified: trunk/gio/src/mountoperation.hg
==============================================================================
--- trunk/gio/src/mountoperation.hg	(original)
+++ trunk/gio/src/mountoperation.hg	Fri Jan 11 02:15:46 2008
@@ -31,6 +31,16 @@
 _WRAP_ENUM(PasswordSave, GPasswordSave, NO_GTYPE)
 _WRAP_ENUM(MountOperationResult, GMountOperationResult, NO_GTYPE)
 
+/** Authentication methods for mountable locations.
+ *
+ * MountOperation provides a mechanism for authenticating mountable operations, such as loop mounting files, hard drive partitions or server locations.
+ * 
+ * Mounting operations are handed a MountOperation that they can use if they require any privileges or authentication for their volumes to be mounted (e.g. 
+ * a hard disk partition or an encrypted filesystem), or if they are implementing a remote server protocol which requires user credentials such as FTP or 
+ * WebDAV.
+ *
+ * Developers should instantiate a subclass of this that implements all the various callbacks to show the required dialogs.
+ */
 class MountOperation : public Glib::Object
 {
   _CLASS_GOBJECT(MountOperation, GMountOperation, G_MOUNT_OPERATION, Glib::Object, GObject)

Modified: trunk/gio/src/outputstream.hg
==============================================================================
--- trunk/gio/src/outputstream.hg	(original)
+++ trunk/gio/src/outputstream.hg	Fri Jan 11 02:15:46 2008
@@ -32,6 +32,8 @@
 
 _WRAP_ENUM(OutputStreamSpliceFlags, GOutputStreamSpliceFlags, NO_GTYPE)
 
+/** Base class for implementing streaming output.
+ */
 class OutputStream : public Glib::Object
 {
   _CLASS_GOBJECT(OutputStream, GOutputStream, G_OUTPUT_STREAM, Glib::Object, GObject)

Copied: trunk/gio/src/seekable.ccg (from r503, /trunk/gio/src/fileinputstream.ccg)
==============================================================================
--- /trunk/gio/src/fileinputstream.ccg	(original)
+++ trunk/gio/src/seekable.ccg	Fri Jan 11 02:15:46 2008
@@ -18,75 +18,4 @@
  */
 
 #include <gio/gio.h>
-#include <glibmm/exceptionhandler.h>
 
-namespace {
-
-static void
-SignalProxy_query_async_callback(GObject*, GAsyncResult* res, void* data)
-{
-  Gio::SlotAsyncReady* the_slot = static_cast<Gio::SlotAsyncReady*>(data);
-
-  #ifdef GLIBMM_EXCEPTIONS_ENABLED
-  try
-  {
-  #endif //GLIBMM_EXCEPTIONS_ENABLED
-    Glib::RefPtr<Gio::AsyncResult> result = Glib::wrap(res, true /* take copy */);
-    (*the_slot)(result);
-  #ifdef GLIBMM_EXCEPTIONS_ENABLED
-  }
-  catch(...)
-  {
-    Glib::exception_handlers_invoke();
-  }
-  #endif //GLIBMM_EXCEPTIONS_ENABLED
-
-  delete the_slot;
-}
-
-} // anonymous namespace
-
-namespace Gio
-{
-
-void
-FileInputStream::query_info_async(const std::string& attributes,
-                                  int io_priority,
-                                  Glib::RefPtr<Cancellable>& cancellable,
-                                  const SlotAsyncReady& slot)
-{
-  // Create a copy of the slot.
-  // A pointer to it will be passed through the callback's data parameter
-  // and deleted in the callback.
-  SlotAsyncReady* slot_copy = new SlotAsyncReady(slot);
-
-  g_file_input_stream_query_info_async(gobj(),
-                                       const_cast<char*>(attributes.c_str()),
-                                       io_priority,
-                                       cancellable->gobj(),
-                                       &SignalProxy_query_async_callback,
-                                       slot_copy);
-}
-
-#ifdef GLIBMM_EXCEPTIONS_ENABLED
-bool FileInputStream::seek(goffset offset, Glib::SeekType type)
-#else
-bool FileInputStream::seek(goffset offset, Glib::SeekType type, std::auto_ptr<Glib::Error>& error)
-#endif //GLIBMM_EXCEPTIONS_ENABLED
-{
-  GError* gerror = 0;
-  bool retvalue = g_file_input_stream_seek(gobj(), offset, ((GSeekType)(type)), NULL, &(gerror));
-#ifdef GLIBMM_EXCEPTIONS_ENABLED
-  if(gerror)
-    ::Glib::Error::throw_exception(gerror);
-#else
-  if(gerror)
-    error = ::Glib::Error::throw_exception(gerror);
-#endif //GLIBMM_EXCEPTIONS_ENABLED
-
-  return retvalue;
-
-}
-
-
-} // namespace Gio

Copied: trunk/gio/src/seekable.hg (from r503, /trunk/gio/src/fileinputstream.hg)
==============================================================================
--- /trunk/gio/src/fileinputstream.hg	(original)
+++ trunk/gio/src/seekable.hg	Fri Jan 11 02:15:46 2008
@@ -19,76 +19,23 @@
 
 #include <gio/gio.h>
 
-#include <glibmm/iochannel.h>
-#include <glibmm/object.h>
-#include <giomm/fileinfo.h>
-#include <giomm/inputstream.h>
+#include <glibmm/interface.h>
 
 _DEFS(giomm,gio)
-_PINCLUDE(giomm/private/inputstream_p.h)
+_PINCLUDE(glibmm/private/interface_p.h)
 
 namespace Gio
 {
 
-//TODO: This implements Seekable.
-
-/** FileInputStream provides input streams that take their content from a file.
- *
- * FileInputStream implements Seekable, which allows the input stream to jump to arbitrary positions in the file, 
- * provided the filesystem of the file allows it. In addition to the generic Seekable API, FileInputStream has its own API 
- * for seeking and positioning. To find the position of a file input stream, use tell(). To find out if a file input stream supports 
- * seeking, use can_seek(). To position a file input stream, use seek().
+/** Stream seeking interface.
+ * Seekable is implemented by streams (implementations of InputStream or OutputStream) that support seeking.
  */
-class FileInputStream : public InputStream
+class Seekable : public Glib::Interface
 {
-  _CLASS_GOBJECT(FileInputStream, GFileInputStream, G_FILE_INPUT_STREAM, Gio::InputStream, GInputStream)
+  _CLASS_INTERFACE(Seekable, GFSeekable, G_Seekable, GSeekableIface)
 
 public:
-  _WRAP_METHOD(Glib::RefPtr<FileInfo> query_info(const std::string& attributes, const Glib::RefPtr<Cancellable>& cancellable),
-               g_file_input_stream_query_info,
-               errthrow)
-
-
-  /** Queries the stream information asynchronously. For the synchronous version of this function, see query_info().
-   *
-   * The operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error 
-   * IO_ERROR_CANCELLED will be set.
-   *
-   * When the operation is finished, @a slot will be called. You can then call query_info_finish() to get the result of the operation.
-   *
-   * @param attributes A file attribute query string.
-   * @param io_priority The I/O priority of the request.
-   * @param cancellable A Cancellable object which can be used to cancel the operation.
-   * @param slot A callback slot which will be called when the request is satisfied.
-   */
-  void query_info_async(const std::string& attributes,
-                        int io_priority,
-                        Glib::RefPtr<Cancellable>& cancellable,
-                        const SlotAsyncReady& slot);
-  _IGNORE(g_file_input_stream_query_info_async)
-
-  _WRAP_METHOD(Glib::RefPtr<FileInfo> query_info_finish(const Glib::RefPtr<AsyncResult>& result),
-               g_file_input_stream_query_info_finish,
-               errthrow)
-
-  _WRAP_METHOD(goffset tell() const, g_file_input_stream_tell)
-  _WRAP_METHOD(bool can_seek() const, g_file_input_stream_can_seek)
-
-  _WRAP_METHOD(bool seek(goffset offset, Glib::SeekType type, const Glib::RefPtr<Cancellable>& cancellable),
-               g_file_input_stream_seek,
-               errthrow)
-
-  /** Seeks in the file input stream.
-   * 
-   * @param offset An offset to seek.
-   * @param type A SeekType.
-   * @result true if the stream was successfully seeked to the position. false on error. 
-   */
-  #ifdef GLIBMM_EXCEPTIONS_ENABLED
-  bool seek(goffset offset, Glib::SeekType type);
-  #else
-  bool seek(goffset offset, Glib::SeekType type, std::auto_ptr<Glib::Error>& error);
-  #endif //GLIBMM_EXCEPTIONS_ENABLED
+  //TODO: methods, properties, vfuncs, signals.
 };
 
 } // namespace Gio

Modified: trunk/gio/src/simpleasyncresult.hg
==============================================================================
--- trunk/gio/src/simpleasyncresult.hg	(original)
+++ trunk/gio/src/simpleasyncresult.hg	Fri Jan 11 02:15:46 2008
@@ -28,6 +28,39 @@
 namespace Gio
 {
 
+//TODO: Is this used in the rest of the API at all? If not, it seems like semi-private API that we should not wrap for now. Murray.
+
+/** Implements AsyncResult for simple cases. Most of the time, this will be all an application needs, and will be used transparently. Because of this, 
+ * SimpleAsyncResult is used throughout GIO for handling asynchronous functions.
+ *
+ * Most of the time, an application will not need to know of the details of this API; it is handled transparently, and any necessary operations are handled 
+ * by AsyncResult's interface. However, if implementing a new GIO module, for writing language bindings, or for complex applications that need better 
+ * control of how asynchronous operations are completed, it is important to understand this functionality.
+ * 
+ * SimpleAsyncResult handles SlotAsyncReady, error reporting, operation cancellation and the final state of an operation, completely transparent to 
+ * the application. Results can be returned as a pointer e.g. for functions that return data that is collected asynchronously, a boolean value for checking 
+ * the success or failure of an operation, or a gssize for operations which return the number of bytes modified by the operation; all of the simple return 
+ * cases are covered.
+ * 
+ * SimpleAsyncResults are tagged with the calling function to ensure that asynchronous functions and their finishing functions are used together correctly.
+ * 
+ * To create a new SimpleAsyncResult, call create(). If the result needs to be created for a GError, use 
+ * create_from_error(). If a GError is not available (e.g. the asynchronous operation's doesn't take a GError argument), but the result 
+ * still needs to be created for an error condition, use g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() if your application or 
+ * binding requires passing a variable argument list directly), and the error can then be propegated through the use of 
+ * g_simple_async_result_propagate_error().
+ * 
+ * An asynchronous operation can be made to ignore a cancellation event by calling set_handle_cancellation() with false.
+ * 
+ * SimpleAsyncResult can integrate into GLib's event loop, GMainLoop, or it can use GThreads if available. complete() will finish an 
+ * I/O task directly within the main event loop. complete_in_idle() will integrate the I/O task into the main event loop as an idle 
+ * function and run_in_thread() will run the job in a separate thread.
+ * 
+ * To set the results of an asynchronous function, set_op_res() methods are provided, setting the operation's result to a gpointer, bool, or gssize,.
+ * 
+ * Likewise, to get the result of an asynchronous function, get_op_res_gpointer(), get_op_res_bool(), and 
+ * get_op_res_gssize() are provided, getting the operation's result as a gpointer, bool, and gssize, respectively.
+ */
 class SimpleAsyncResult : public Glib::Object, public AsyncResult
 {
   _CLASS_GOBJECT(SimpleAsyncResult, GSimpleAsyncResult, G_SIMPLE_ASYNC_RESULT, Glib::Object, GObject)

Modified: trunk/gio/src/volume.hg
==============================================================================
--- trunk/gio/src/volume.hg	(original)
+++ trunk/gio/src/volume.hg	Fri Jan 11 02:15:46 2008
@@ -36,6 +36,18 @@
 // file.hg already includes volume.h.
 class File;
 
+/** The Volume interface represents user-visible objects that can be mounted.
+ * 
+ * Mounting a Volume instance is an asynchronous operation. For more information about asynchronous operations, see AsyncReady and SimpleAsyncReady. To 
+ * mount a GVolume, first call mount(), optionally providing a MountOperation object and a SlotAsyncReady callback.
+ * 
+ * Typically, you will not want to provide a MountOperation if automounting all volumes when a desktop session starts since it's not desirable to 
+ * put up a lot of dialogs asking for credentials.
+ * 
+ * The callback will be fired when the operation has resolved (either with success or failure), and a AsyncReady structure will be passed to the callback. 
+ * That callback should then call g_volume_mount_finish() with the GVolume instance and the GAsyncReady data to see if the operation was completed 
+ * successfully. If an error is present when finish() is called, then it will be filled with any error information.
+ */
 class Volume : public Glib::Interface
 {
   _CLASS_INTERFACE(Volume, GVolume, G_DRIVE, GVolumeIface)
@@ -60,10 +72,12 @@
   _WRAP_METHOD(bool can_mount() const, g_volume_can_mount)
   _WRAP_METHOD(bool can_eject() const, g_volume_can_eject)
 
-  _IGNORE(g_volume_mount)
+  //TODO: Documentation.
+
   void mount(const Glib::RefPtr<MountOperation>& mount_operation, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
 
   void mount(const Glib::RefPtr<MountOperation>& mount_operation, const SlotAsyncReady& slot);
+  _IGNORE(g_volume_mount)
 
   _WRAP_METHOD(bool mount_finish(const Glib::RefPtr<AsyncResult>& result),
                g_volume_mount_finish,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]