Added method overloads and documentation.

2008-01-21  Murray Cumming  <murrayc@murrayc.com>

* gio/src/inputstream.ccg:
* gio/src/inputstream.hg: Added method overloads and documentation.

svn path=/trunk/; revision=532

3 files changed, 384 insertions, 5 deletions

diff --git a/ChangeLog b/ChangeLog
index 09ac89a3..fa8075e2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2008-01-21  Murray Cumming  <murrayc@murrayc.com>
+
+	* gio/src/inputstream.ccg:
+	* gio/src/inputstream.hg: Added method overloads and documentation.
+
 2008-01-20  Murray Cumming  <murrayc@murrayc.com>
 
 	* gio/src/fileinputstream.ccg:
diff --git a/gio/src/inputstream.ccg b/gio/src/inputstream.ccg
index e25f3cc1..d9e016ef 100644
--- a/gio/src/inputstream.ccg
+++ b/gio/src/inputstream.ccg
@@ -20,7 +20,8 @@
 #include <gio/gio.h>
 #include <giomm/asyncresult.h>
 
-namespace {
+namespace
+{
 
 static void
 SignalProxy_input_stream_async_callback(GObject*, GAsyncResult* res, void* data)
@@ -46,7 +47,86 @@ SignalProxy_input_stream_async_callback(GObject*, GAsyncResult* res, void* data)
 
 } // anonymous namespace
 
-namespace Gio {
+
+namespace Gio
+{
+
+#ifdef GLIBMM_EXCEPTIONS_ENABLED
+gssize InputStream::read(void* buffer, gsize count)
+#else
+gssize InputStream::read(void* buffer, gsize count, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  gssize retvalue = g_input_stream_read(gobj(), buffer, count, 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;
+}
+
+
+#ifdef GLIBMM_EXCEPTIONS_ENABLED
+bool InputStream::read_all(void* buffer, gsize count, gsize& bytes_read)
+#else
+bool InputStream::read_all(void* buffer, gsize count, gsize& bytes_read, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  bool retvalue = g_input_stream_read_all(gobj(), buffer, count, &(bytes_read), 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;
+}
+
+#ifdef GLIBMM_EXCEPTIONS_ENABLED
+gssize InputStream::skip(gsize count)
+#else
+gssize InputStream::skip(gsize count, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  gssize retvalue = g_input_stream_skip(gobj(), count, 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;
+}
+
+#ifdef GLIBMM_EXCEPTIONS_ENABLED
+bool InputStream::close()
+#else
+bool InputStream::close(std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  bool retvalue = g_input_stream_close(gobj(), 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;
+}
 
 void
 InputStream::read_async(void* buffer, gsize count, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority)
@@ -66,6 +146,24 @@ InputStream::read_async(void* buffer, gsize count, const SlotAsyncReady& slot, c
 }
 
 void
+InputStream::read_async(void* buffer, gsize count, const SlotAsyncReady& slot, int io_priority)
+{
+  // 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_input_stream_read_async(gobj(),
+                            buffer,
+                            count,
+                            io_priority,
+                            NULL,
+                            &SignalProxy_input_stream_async_callback,
+                            slot_copy);
+}
+
+
+void
 InputStream::skip_async(gsize count, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority)
 {
   // Create a copy of the slot.
@@ -82,6 +180,22 @@ InputStream::skip_async(gsize count, const SlotAsyncReady& slot, const Glib::Ref
 }
 
 void
+InputStream::skip_async(gsize count, const SlotAsyncReady& slot, int io_priority)
+{
+  // 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_input_stream_skip_async(gobj(),
+                            count,
+                            io_priority,
+                            NULL,
+                            &SignalProxy_input_stream_async_callback,
+                            slot_copy);
+}
+
+void
 InputStream::close_async(const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority)
 {
   // Create a copy of the slot.
@@ -96,4 +210,20 @@ InputStream::close_async(const SlotAsyncReady& slot, const Glib::RefPtr<Cancella
                              slot_copy);
 }
 
+void
+InputStream::close_async(const SlotAsyncReady& slot, int io_priority)
+{
+  // 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_input_stream_close_async(gobj(),
+                             io_priority,
+                             NULL,
+                             &SignalProxy_input_stream_async_callback,
+                             slot_copy);
+}
+
+
 } // namespace Gio
diff --git a/gio/src/inputstream.hg b/gio/src/inputstream.hg
index c1e3ad23..064d4d50 100644
--- a/gio/src/inputstream.hg
+++ b/gio/src/inputstream.hg
@@ -30,6 +30,8 @@ _PINCLUDE(glibmm/private/object_p.h)
 namespace Gio
 {
 
+//TODO: Implement operator << and >> for streams?
+
 /** Base class for implementing streaming input.
  *
  * @newin2p16
@@ -39,26 +41,180 @@ class InputStream : public Glib::Object
   _CLASS_GOBJECT(InputStream, GInputStream, G_INPUT_STREAM, Glib::Object, GObject)
 
 public:
-  //TODO: Add overloads with no cancellable.
   _WRAP_METHOD(gssize read(void* buffer, gsize count, const Glib::RefPtr<Cancellable>& cancellable),
                g_input_stream_read,
                errthrow)
 
+  /** Tries to read @a count bytes from the stream into the buffer starting at
+   *  @a buffer. Will block during this read.
+   * 
+   * If count is zero returns zero and does nothing. A value of @a count 
+   * larger than MAXSSIZE will cause an IO_ERROR_INVALID_ARGUMENT error.
+   * 
+   * On success, the number of bytes read into the buffer is returned.
+   * It is not an error if this is not the same as the requested size, as it
+   * can happen e.g. near the end of a file. Zero is returned on end of file
+   * (or if @a count is zero), but never otherwise.
+   * 
+   * On error -1 is returned and @a error is set accordingly.
+   * @param buffer A buffer to read data into (which should be at least count bytes long).
+   * @param count The number of bytes that will be read from the stream.
+   * @return Number of bytes read, or -1 on error.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  gssize read(void* buffer, gsize count);
+  #else
+  gssize read(void* buffer, gsize count, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+
+  //TODO: gssize read(std::string& buffer, const Glib::RefPtr<Cancellable>& cancellable);
+  //TODO: gssize read(std::string& buffer);
+
   _WRAP_METHOD(bool read_all(void* buffer, gsize count, gsize& bytes_read, const Glib::RefPtr<Cancellable>& cancellable),
                g_input_stream_read_all,
                errthrow)
 
+  /** Tries to read @a count bytes from the stream into the buffer starting at
+   *  @a buffer. Will block during this read.
+   * 
+   * This function is similar to read(), except it tries to
+   * read as many bytes as requested, only stopping on an error or end of stream.
+   * 
+   * On a successful read of @a count bytes, or if we reached the end of the
+   * stream, <tt>true</tt> is returned, and @a bytes_read is set to the number of bytes
+   * read into @a buffer .
+   * 
+   * If there is an error during the operation <tt>false</tt> is returned and @a error 
+   * is set to indicate the error status, @a bytes_read is updated to contain
+   * the number of bytes read into @a buffer before the error occured.
+   * @param buffer A buffer to read data into (which should be at least count bytes long).
+   * @param count The number of bytes that will be read from the stream.
+   * @param bytes_read Location to store the number of bytes that was read from the stream.
+   * @return <tt>true</tt> on success, <tt>false</tt> if there was an error.
+   */  
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  bool read_all(void* buffer, gsize count, gsize& bytes_read);
+  #else
+  bool read_all(void* buffer, gsize count, gsize& bytes_read, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+
+  //TODO: bool read_all(std::string& buffer, gsize count, gsize& bytes_read, const Glib::RefPtr<Cancellable>& cancellable);
+  //TODO: bool read_all(std::string& buffer, gsize count, gsize& bytes_read)
+
   _WRAP_METHOD(gssize skip(gsize count, const Glib::RefPtr<Cancellable>& cancellable),
                g_input_stream_skip,
                errthrow)
 
+  /** Tries to skip @a count bytes from the stream. Will block during the operation.
+   * 
+   * This is identical to read(), from a behaviour standpoint,
+   * but the bytes that are skipped are not returned to the user. Some
+   * streams have an implementation that is more efficient than reading the data.
+   * 
+   * This function is optional for inherited classes, as the default implementation
+   * emulates it using read.
+   * 
+   * @param count The number of bytes that will be skipped from the stream.
+   * @return Number of bytes skipped, or -1 on error.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  gssize skip(gsize count);
+  #else
+  gssize skip(gsize count, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+
   _WRAP_METHOD(bool close(const Glib::RefPtr<Cancellable>& cancellable),
                g_input_stream_close,
                errthrow)
 
+  /** Closes the stream, releasing resources related to it.
+   * 
+   * Once the stream is closed, all other operations will return IO_ERROR_CLOSED.
+   * Closing a stream multiple times will not return an error.
+   * 
+   * Streams will be automatically closed when the last reference
+   * is dropped, but you might want to call this make sure resources
+   * are released as early as possible.
+   * 
+   * Some streams might keep the backing store of the stream (e.g. a file descriptor)
+   * open after the stream is closed. See the documentation for the individual
+   * stream for details.
+   * 
+   * On failure the first error that happened will be reported, but the close
+   * operation will finish as much as possible. A stream that failed to
+   * close will still return IO_ERROR_CLOSED all operations. Still, it
+   * is important to check and report the error to the user.
+   * 
+   * @return <tt>true</tt> on success, <tt>false</tt> on failure.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  bool close();
+  #else
+  bool close(std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
 
-  //TODO: Documentation.
+  /** Request an asynchronous read of @a count bytes from the stream into the buffer
+   * starting at @a buffer. When the operation is finished @a slot will be called. 
+   * You can then call read_finish() to get the result of the 
+   * operation.
+   *
+   * During an async request no other sync and async calls are allowed, and will
+   * result in IO_ERROR_PENDING errors. 
+   *
+   * A value of @a count larger than MAXSSIZE will cause an IO_ERROR_INVALID_ARGUMENT error.
+   *
+   * On success, the number of bytes read into the buffer will be passed to the
+   * @a slot callback. It is not an error if this is not the same as the requested size, as it
+   * can happen e.g. near the end of a file, but generally we try to read
+   * as many bytes as requested. Zero is returned on end of file
+   * (or if @a count is zero), but never otherwise.
+   *
+   * Any outstanding i/o request with higher priority (lower numerical value) will
+   * be executed before an outstanding request with lower priority. Default
+   * priority is PRIORITY_DEFAULT.
+   *
+   * The asyncronous methods have a default fallback that uses threads to implement
+   * asynchronicity, so they are optional for inheriting classes. However, if you
+   * override one you must override all.
+   *
+   * @param buffer A buffer to read data into (which should be at least count bytes long).
+   * @param count The number of bytes that will be read from the stream.
+   * @param slot Callback to call when the request is satisfied.
+   * @param cancellable A Cancellable object.
+   * @param io_priority The I/O priority of the request. 
+   */
   void read_async(void* buffer, gsize count, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = G_PRIORITY_DEFAULT);
+
+  /** Request an asynchronous read of @a count bytes from the stream into the buffer
+   * starting at @a buffer. When the operation is finished @a slot will be called. 
+   * You can then call read_finish() to get the result of the 
+   * operation.
+   *
+   * During an async request no other sync and async calls are allowed, and will
+   * result in IO_ERROR_PENDING errors. 
+   *
+   * A value of @a count larger than MAXSSIZE will cause an IO_ERROR_INVALID_ARGUMENT error.
+   *
+   * On success, the number of bytes read into the buffer will be passed to the
+   * @a slot callback. It is not an error if this is not the same as the requested size, as it
+   * can happen e.g. near the end of a file, but generally we try to read
+   * as many bytes as requested. Zero is returned on end of file
+   * (or if @a count is zero), but never otherwise.
+   *
+   * Any outstanding i/o request with higher priority (lower numerical value) will
+   * be executed before an outstanding request with lower priority. Default
+   * priority is PRIORITY_DEFAULT.
+   *
+   * The asyncronous methods have a default fallback that uses threads to implement
+   * asynchronicity, so they are optional for inheriting classes. However, if you
+   * override one you must override all.
+   *
+   * @param buffer A buffer to read data into (which should be at least count bytes long).
+   * @param count The number of bytes that will be read from the stream.
+   * @param slot Callback to call when the request is satisfied.
+   * @param io_priority The I/O priority of the request. 
+   */
+  void read_async(void* buffer, gsize count, const SlotAsyncReady& slot, int io_priority = G_PRIORITY_DEFAULT);
   _IGNORE(g_input_stream_read_async)
 
   _WRAP_METHOD(gssize read_finish(const Glib::RefPtr<AsyncResult>& result),
@@ -66,15 +222,103 @@ public:
                errthrow)
 
   //TODO: Use std::size_type instead of gsize?
+
+  /** Request an asynchronous skip of @a count bytes from the stream into the buffer
+   * starting at @a buffer. When the operation is finished @a slot will be called. 
+   * You can then call skip_finish() to get the result of the operation.
+   *
+   * During an async request no other sync and async calls are allowed, and will
+   * result in IO_ERROR_PENDING errors. 
+   *
+   * A value of @a count larger than MAXSSIZE will cause an IO_ERROR_INVALID_ARGUMENT error.
+   *
+   * On success, the number of bytes skipped will be passed to the
+   * callback. It is not an error if this is not the same as the requested size, as it
+   * can happen e.g. near the end of a file, but generally we try to skip
+   * as many bytes as requested. Zero is returned on end of file
+   * (or if @a count is zero), but never otherwise.
+   *
+   * Any outstanding i/o request with higher priority (lower numerical value) will
+   * be executed before an outstanding request with lower priority. Default
+   * priority is PRIORITY_DEFAULT.
+   *
+   * The asyncronous methods have a default fallback that uses threads to implement
+   * asynchronicity, so they are optional for inheriting classes. However, if you
+   * override one you must override all.
+   *
+   * @param count The number of bytes that will be skipped from the stream.
+   * @param slot Callback to call when the request is satisfied.
+   * @param cancellable A Cancellable object.
+   * @param io_priority The I/O priority of the request. 
+   */
   void skip_async(gsize count, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = G_PRIORITY_DEFAULT);
+
+  /** Request an asynchronous skip of @a count bytes from the stream into the buffer
+   * starting at @a buffer. When the operation is finished @a slot will be called. 
+   * You can then call skip_finish() to get the result of the operation.
+   *
+   * During an async request no other sync and async calls are allowed, and will
+   * result in IO_ERROR_PENDING errors. 
+   *
+   * A value of @a count larger than MAXSSIZE will cause an IO_ERROR_INVALID_ARGUMENT error.
+   *
+   * On success, the number of bytes skipped will be passed to the
+   * callback. It is not an error if this is not the same as the requested size, as it
+   * can happen e.g. near the end of a file, but generally we try to skip
+   * as many bytes as requested. Zero is returned on end of file
+   * (or if @a count is zero), but never otherwise.
+   *
+   * Any outstanding i/o request with higher priority (lower numerical value) will
+   * be executed before an outstanding request with lower priority. Default
+   * priority is PRIORITY_DEFAULT.
+   *
+   * The asyncronous methods have a default fallback that uses threads to implement
+   * asynchronicity, so they are optional for inheriting classes. However, if you
+   * override one you must override all.
+   *
+   * @param count The number of bytes that will be skipped from the stream.
+   * @param slot Callback to call when the request is satisfied.
+   * @param io_priority The I/O priority of the request. 
+   */
+  void skip_async(gsize count, const SlotAsyncReady& slot, int io_priority = G_PRIORITY_DEFAULT);
   _IGNORE(g_input_stream_skip_async)
 
   _WRAP_METHOD(gssize skip_finish(const Glib::RefPtr<AsyncResult>& result),
                g_input_stream_skip_finish,
                errthrow)
 
-  //TODO: Can Cancellable be NULL?
+  /** Requests an asynchronous closes of the stream, releasing resources related to it.
+   * When the operation is finished @a slot will be called. 
+   * You can then call close_finish() to get the result of the 
+   * operation.
+   *
+   * For behaviour details see close().
+   *
+   * The asyncronous methods have a default fallback that uses threads to implement
+   * asynchronicity, so they are optional for inheriting classes. However, if you
+   * override one you must override all.
+   *
+   * @param slot Callback to call when the request is satisfied.
+   * @param cancellable A Cancellable object.
+   * @param io_priority The I/O priority of the request. 
+   */
   void close_async(const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = G_PRIORITY_DEFAULT);
+
+  /** Requests an asynchronous closes of the stream, releasing resources related to it.
+   * When the operation is finished @a slot will be called. 
+   * You can then call close_finish() to get the result of the 
+   * operation.
+   *
+   * For behaviour details see close().
+   *
+   * The asyncronous methods have a default fallback that uses threads to implement
+   * asynchronicity, so they are optional for inheriting classes. However, if you
+   * override one you must override all.
+   *
+   * @param slot Callback to call when the request is satisfied.
+   * @param io_priority The I/O priority of the request. 
+   */
+  void close_async(const SlotAsyncReady& slot, int io_priority = G_PRIORITY_DEFAULT);
   _IGNORE(g_input_stream_close_async)
 
   _WRAP_METHOD(gboolean close_finish(const Glib::RefPtr<AsyncResult>& result),