glibmm r531 - in trunk: . gio/src

[murrayc svn gnome org]

Author: murrayc
Date: Sun Jan 20 21:54:24 2008
New Revision: 531
URL: http://svn.gnome.org/viewvc/glibmm?rev=531&view=rev

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

* gio/src/fileinputstream.ccg:
* gio/src/fileinputstream.hg:
* gio/src/fileoutputstream.ccg:
* gio/src/fileoutputstream.hg: Ignore functions that are just 
duplicates of the ones in Seekable, and mention Seekable more in 
the documentation.
* gio/src/seekable.hg: Expand the class documentation.
* gio/src/outputstream.ccg:
* gio/src/outputstream.hg: Added method overloads and documentation.

Modified:
   trunk/ChangeLog
   trunk/gio/src/fileinputstream.ccg
   trunk/gio/src/fileinputstream.hg
   trunk/gio/src/fileoutputstream.hg
   trunk/gio/src/outputstream.ccg
   trunk/gio/src/outputstream.hg
   trunk/gio/src/seekable.hg

Modified: trunk/gio/src/fileinputstream.ccg
==============================================================================
--- trunk/gio/src/fileinputstream.ccg	(original)
+++ trunk/gio/src/fileinputstream.ccg	Sun Jan 20 21:54:24 2008
@@ -81,24 +81,4 @@
                                        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

Modified: trunk/gio/src/fileinputstream.hg
==============================================================================
--- trunk/gio/src/fileinputstream.hg	(original)
+++ trunk/gio/src/fileinputstream.hg	Sun Jan 20 21:54:24 2008
@@ -31,14 +31,11 @@
 namespace Gio
 {
 
-//TODO: Remove (ignore) functions that just call the base Seekable class? See http://bugzilla.gnome.org/show_bug.cgi?id=509990
-
 /** 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().
+ * provided the file system of the file allows it.
+ * Use the methods of the Seekable base class for seeking and positioning.
  *
  * @newin2p16
  */
@@ -84,24 +81,14 @@
                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
+  //These seem to be just C convenience functions - they are already in the Seekable base class:
+  //See http://bugzilla.gnome.org/show_bug.cgi?id=509990
+  _IGNORE(g_file_input_stream_tell, g_file_input_stream_can_seek, g_file_input_stream_seek)
+//  _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)
 };
 
 } // namespace Gio

Modified: trunk/gio/src/fileoutputstream.hg
==============================================================================
--- trunk/gio/src/fileoutputstream.hg	(original)
+++ trunk/gio/src/fileoutputstream.hg	Sun Jan 20 21:54:24 2008
@@ -32,19 +32,14 @@
 namespace Gio
 {
 
-//TODO: Remove (ignore) functions that just call the base Seekable class? See http://bugzilla.gnome.org/show_bug.cgi?id=509990
 
 /** 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().
+ * file system of the file supports these operations.
+ * Use the methods of the Seekable base class for seeking and positioning. 
+ * 
  *
  * @newin2p16
  */
@@ -74,22 +69,20 @@
                refreturn, errthrow)
 
   _WRAP_METHOD(std::string get_etag() const, g_file_output_stream_get_etag)
-  _WRAP_METHOD(goffset tell() const, g_file_output_stream_tell)
-  _WRAP_METHOD(bool can_seek() const, g_file_output_stream_can_seek)
-
-  //TODO: Add a default value for the seek type?
-  _WRAP_METHOD(bool seek(goffset offset, Glib::SeekType type, const Glib::RefPtr<Cancellable>& cancellable),
-               g_file_output_stream_seek,
-               errthrow)
-  //TODO: cancellable can probably be NULL.
-
-  _WRAP_METHOD(bool can_truncate() const, g_file_output_stream_can_truncate)
-
-  _WRAP_METHOD(bool truncate(goffset size, const Glib::RefPtr<Cancellable>& cancellable),
-               g_file_output_stream_truncate,
-               errthrow)
-  //TODO: cancellable can probalby be NULL.
 
+  //These seem to be just C convenience functions - they are already in the Seekable base class:
+  //See http://bugzilla.gnome.org/show_bug.cgi?id=509990
+  _IGNORE(g_file_output_stream_tell, g_file_output_stream_can_seek, g_file_output_stream_seek, 
+          g_file_output_stream_can_truncate, g_file_output_stream_truncate)
+//  _WRAP_METHOD(goffset tell() const, g_file_output_stream_tell)
+//  _WRAP_METHOD(bool can_seek() const, g_file_output_stream_can_seek)
+//  _WRAP_METHOD(bool seek(goffset offset, Glib::SeekType type, const Glib::RefPtr<Cancellable>& cancellable),
+//               g_file_output_stream_seek,
+//               errthrow)
+//  _WRAP_METHOD(bool can_truncate() const, g_file_output_stream_can_truncate)
+//  _WRAP_METHOD(bool truncate(goffset size, const Glib::RefPtr<Cancellable>& cancellable),
+//               g_file_output_stream_truncate,
+//               errthrow)
 };
 
 } // namespace Gio

Modified: trunk/gio/src/outputstream.ccg
==============================================================================
--- trunk/gio/src/outputstream.ccg	(original)
+++ trunk/gio/src/outputstream.ccg	Sun Jan 20 21:54:24 2008
@@ -127,7 +127,22 @@
 
   g_output_stream_flush_async(gobj(),
                               io_priority,
-                              cancellable->gobj(),
+                              const_cast<GCancellable*>(Glib::unwrap(cancellable)),
+                              &SignalProxy_async_callback,
+                              slot_copy);
+}
+
+void
+OutputStream::flush_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_output_stream_flush_async(gobj(),
+                              io_priority,
+                              NULL,
                               &SignalProxy_async_callback,
                               slot_copy);
 }
@@ -142,9 +157,215 @@
 
   g_output_stream_close_async(gobj(),
                               io_priority,
-                              cancellable->gobj(),
+                              const_cast<GCancellable*>(Glib::unwrap(cancellable)),
+                              &SignalProxy_async_callback,
+                              slot_copy);
+}
+
+void
+OutputStream::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_output_stream_close_async(gobj(),
+                              io_priority,
+                              NULL,
                               &SignalProxy_async_callback,
                               slot_copy);
 }
 
+
+#ifdef GLIBMM_EXCEPTIONS_ENABLED
+gssize OutputStream::write(const void* buffer, gsize count)
+#else
+gssize OutputStream::write(const void* buffer, gsize count, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  gssize retvalue = g_output_stream_write(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
+gssize OutputStream::write(const std::string& buffer, const Glib::RefPtr<Cancellable>& cancellable)
+#else
+gssize OutputStream::write(const std::string&, const Glib::RefPtr<Cancellable>& cancellable, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  gssize retvalue = g_output_stream_write(gobj(), buffer.c_str(), buffer.size(), const_cast<GCancellable*>(Glib::unwrap(cancellable)), &(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 OutputStream::write(const std::string& buffer)
+#else
+gssize OutputStream::write(const std::string&, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  gssize retvalue = g_output_stream_write(gobj(), buffer.c_str(), buffer.size(), 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 OutputStream::write_all(const void* buffer, gsize count, gsize& bytes_written)
+#else
+bool OutputStream::write_all(const void* buffer, gsize count, gsize& bytes_written, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  bool retvalue = g_output_stream_write_all(gobj(), buffer, count, &(bytes_written), 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 OutputStream::write_all(const std::string& buffer, gsize& bytes_written, const Glib::RefPtr<Cancellable>& cancellable)
+#else
+bool OutputStream::write_all(const std::string& buffer, gsize& bytes_written, const Glib::RefPtr<Cancellable>& cancellable, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  bool retvalue = g_output_stream_write_all(gobj(), buffer.c_str(), buffer.size(), &(bytes_written), const_cast<GCancellable*>(Glib::unwrap(cancellable)), &(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 OutputStream::write_all(const std::string& buffer, gsize& bytes_written)
+#else
+bool OutputStream::write_all(const std::string& buffer, gsize& bytes_written, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  bool retvalue = g_output_stream_write_all(gobj(), buffer.c_str(), buffer.size(), &(bytes_written), 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 OutputStream::splice(const Glib::RefPtr<InputStream>& source, const Glib::RefPtr<Cancellable>& cancellable, OutputStreamSpliceFlags flags)
+#else
+gssize OutputStream::splice(const Glib::RefPtr<InputStream>& source, const Glib::RefPtr<Cancellable>& cancellable, OutputStreamSpliceFlags flags, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  gssize retvalue = g_output_stream_splice(gobj(), const_cast<GInputStream*>(Glib::unwrap(source)), ((GOutputStreamSpliceFlags)(flags)), const_cast<GCancellable*>(Glib::unwrap(cancellable)), &(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 OutputStream::splice(const Glib::RefPtr<InputStream>& source, OutputStreamSpliceFlags flags)
+#else
+gssize OutputStream::splice(const Glib::RefPtr<InputStream>& source, OutputStreamSpliceFlags flags, std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  gssize retvalue = g_output_stream_splice(gobj(), const_cast<GInputStream*>(Glib::unwrap(source)), ((GOutputStreamSpliceFlags)(flags)), 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 OutputStream::flush()
+#else
+bool OutputStream::flush(std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  bool retvalue = g_output_stream_flush(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;
+}
+
+#ifdef GLIBMM_EXCEPTIONS_ENABLED
+bool OutputStream::close()
+#else
+bool OutputStream::close(std::auto_ptr<Glib::Error>& error)
+#endif //GLIBMM_EXCEPTIONS_ENABLED
+{
+  GError* gerror = 0;
+  bool retvalue = g_output_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;
+}
+
 } // namespace Gio

Modified: trunk/gio/src/outputstream.hg
==============================================================================
--- trunk/gio/src/outputstream.hg	(original)
+++ trunk/gio/src/outputstream.hg	Sun Jan 20 21:54:24 2008
@@ -41,28 +41,314 @@
   _CLASS_GOBJECT(OutputStream, GOutputStream, G_OUTPUT_STREAM, Glib::Object, GObject)
 
 public:
-  //TODO: Add overloads with no cancellable.
+
   _WRAP_METHOD(gssize write(const void* buffer, gsize count, const Glib::RefPtr<Cancellable>& cancellable),
                g_output_stream_write,
                errthrow)
 
+  /** Tries to write @a count  bytes from @a buffer  into the stream. Will block
+   * during the operation.
+   * 
+   * If count is zero returns zero and does nothing. A value of @a count 
+   * larger than G::MAXSSIZE will cause a G::IO_ERROR_INVALID_ARGUMENT error.
+   * 
+   * On success, the number of bytes written to the stream is returned.
+   * It is not an error if this is not the same as the requested size, as it
+   * can happen e.g. on a partial i/o error, or if the there is not enough
+   * storage in the stream. All writes either block until at least one byte
+   * is written, so zero is never returned (unless @a count  is zero).
+   * 
+   * On error -1 is returned and @a error  is set accordingly.
+   * @param buffer The buffer containing the data to write.
+   * @param count The number of bytes to write.
+   * @return Number of bytes written, or -1 on error.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  gssize write(const void* buffer, gsize count);
+  #else
+  gssize write(const void* buffer, gsize count, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+
+  /** Tries to write @a count  bytes from @a buffer  into the stream. Will block
+   * during the operation.
+   * 
+   * If count is zero returns zero and does nothing. A value of @a count 
+   * larger than G::MAXSSIZE will cause a G::IO_ERROR_INVALID_ARGUMENT error.
+   * 
+   * On success, the number of bytes written to the stream is returned.
+   * It is not an error if this is not the same as the requested size, as it
+   * can happen e.g. on a partial i/o error, or if the there is not enough
+   * storage in the stream. All writes either block until at least one byte
+   * is written, so zero is never returned (unless @a count  is zero).
+   * 
+   * On error -1 is returned and @a error  is set accordingly.
+   * @param buffer The buffer containing the data to write.
+   * @cancellable Cancellable object.
+   * @return Number of bytes written, or -1 on error.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  gssize write(const std::string& buffer, const Glib::RefPtr<Cancellable>& cancellable);
+  #else
+  gssize write(const std::string& buffer, const Glib::RefPtr<Cancellable>& cancellable, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+
+  /** Tries to write @a count  bytes from @a buffer  into the stream. Will block
+   * during the operation.
+   * 
+   * If string that is larger than MAXSSIZE bytes will cause a an IO_ERROR_INVALID_ARGUMENT error.
+   * 
+   * On success, the number of bytes written to the stream is returned.
+   * It is not an error if this is not the same as the requested size, as it
+   * can happen e.g. on a partial i/o error, or if the there is not enough
+   * storage in the stream. All writes either block until at least one byte
+   * is written, so zero is never returned (unless @a count  is zero).
+   * 
+   * On error -1 is returned and @a error  is set accordingly.
+   * @param buffer The buffer containing the data to write.
+   * @return Number of bytes written, or -1 on error.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  gssize write(const std::string& buffer);
+  #else
+  gssize write(const std::string& buffer, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+
+
   _WRAP_METHOD(bool write_all(const void* buffer, gsize count, gsize& bytes_written, const Glib::RefPtr<Cancellable>& cancellable),
                g_output_stream_write_all,
                errthrow)
 
-  _WRAP_METHOD(gssize splice(const Glib::RefPtr<InputStream>& source, OutputStreamSpliceFlags flags, const Glib::RefPtr<Cancellable>& cancellable),
-               g_output_stream_splice,
-               errthrow)
+  /** Tries to write @a count  bytes from @a buffer into the stream. Will block
+   * during the operation.
+   * 
+   * This function is similar to write(), except it tries to
+   * write as many bytes as requested, only stopping on an error.
+   * 
+   * On a successful write of @a count  bytes, <tt>true</tt> is returned, and @a bytes_written 
+   * is set to @a count .
+   * 
+   * 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_written  is updated to contain
+   * the number of bytes written into the stream before the error occured.
+   * @param buffer The buffer containing the data to write.
+   * @param count The number of bytes to write.
+   * @param bytes_written Location to store the number of bytes that was 
+   * written to the stream.
+   * @return <tt>true</tt> on success, <tt>false</tt> if there was an error.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  bool write_all(const void* buffer, gsize count, gsize& bytes_written);
+  #else
+  bool write_all(const void* buffer, gsize count, gsize& bytes_written, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+
+  /** Tries to write @a count  bytes from @a buffer into the stream. Will block
+   * during the operation.
+   * 
+   * This function is similar to write(), except it tries to
+   * write as many bytes as requested, only stopping on an error.
+   * 
+   * On a successful write of @a count  bytes, <tt>true</tt> is returned, and @a bytes_written 
+   * is set to @a count .
+   * 
+   * 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_written  is updated to contain
+   * the number of bytes written into the stream before the error occured.
+   * @param buffer The buffer containing the data to write.
+   * @param bytes_written Location to store the number of bytes that was 
+   * written to the stream.
+   * @param cancellable Cancellable object.
+   * @return <tt>true</tt> on success, <tt>false</tt> if there was an error.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  bool write_all(const std::string& buffer, gsize& bytes_written, const Glib::RefPtr<Cancellable>& cancellable);
+  #else
+  bool write_all(const std::string& buffer, gsize& bytes_written, const Glib::RefPtr<Cancellable>& cancellable, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+
+  /** Tries to write @a count  bytes from @a buffer into the stream. Will block
+   * during the operation.
+   * 
+   * This function is similar to write(), except it tries to
+   * write as many bytes as requested, only stopping on an error.
+   * 
+   * On a successful write of @a count  bytes, <tt>true</tt> is returned, and @a bytes_written 
+   * is set to @a count .
+   * 
+   * 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_written  is updated to contain
+   * the number of bytes written into the stream before the error occured.
+   * @param buffer The buffer containing the data to write.
+   * @param bytes_written Location to store the number of bytes that was 
+   * written to the stream.
+   * @return <tt>true</tt> on success, <tt>false</tt> if there was an error.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  bool write_all(const std::string& buffer, gsize& bytes_written);
+  #else
+  bool write_all(const std::string& buffer, gsize& bytes_written, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+   
+  /** Splices an input stream into an output stream.
+   *
+   * @param source An InputStream.
+   * @param flags A set of OutputStreamSpliceFlags.
+   * @param cancellable A Cancellable object.
+   * ignore.
+   * @return A #gssize containing the size of the data spliced.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  gssize splice(const Glib::RefPtr<InputStream>& source, const Glib::RefPtr<Cancellable>& cancellable, OutputStreamSpliceFlags flags = OUTPUT_STREAM_SPLICE_NONE);
+  #else
+  gssize splice(const Glib::RefPtr<InputStream>& source, const Glib::RefPtr<Cancellable>& cancellable, OutputStreamSpliceFlags flags, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+
+  /** Splices an input stream into an output stream.
+   *
+   * @param source An InputStream.
+   * @param flags A set of OutputStreamSpliceFlags.
+   * ignore.
+   * @return A #gssize containing the size of the data spliced.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  gssize splice(const Glib::RefPtr<InputStream>& source, OutputStreamSpliceFlags flags = OUTPUT_STREAM_SPLICE_NONE);
+  #else
+  gssize splice(const Glib::RefPtr<InputStream>& source, OutputStreamSpliceFlags flags, std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+  _IGNORE(g_output_stream_splice)
 
   _WRAP_METHOD(bool flush(const Glib::RefPtr<Cancellable>& cancellable),
                g_output_stream_flush,
                errthrow)
 
+  /** Flushed any outstanding buffers in the stream. Will block during 
+   * the operation. Closing the stream will implicitly cause a flush.
+   * 
+   * This function is optional for inherited classes.
+   * 
+   * If @a cancellable  is not <tt>0</tt>, then the operation can be cancelled by
+   * triggering the cancellable object from another thread. If the operation
+   * was cancelled, the error G::IO_ERROR_CANCELLED will be returned.
+   * @param cancellable Optional cancellable object.
+   * @param error Location to store the error occuring, or <tt>0</tt> to ignore.
+   * @return <tt>true</tt> on success, <tt>false</tt> on error.
+   */
+  #ifdef GLIBMM_EXCEPTIONS_ENABLED
+  bool flush();
+  #else
+  bool flush(std::auto_ptr<Glib::Error>& error);
+  #endif //GLIBMM_EXCEPTIONS_ENABLED
+
   _WRAP_METHOD(bool close(const Glib::RefPtr<Cancellable>& cancellable),
                g_output_stream_close,
                errthrow)
 
+  /** Closes the stream, releasing resources related to it.
+   * 
+   * Once the stream is closed, all other operations will return G::IO_ERROR_CLOSED.
+   * Closing a stream multiple times will not return an error.
+   * 
+   * Closing a stream will automatically flush any outstanding buffers in the
+   * stream.
+   * 
+   * Streams will be automatically closed when the last reference
+   * is dropped, but you might want to call 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 G::IO_ERROR_CLOSED all operations. Still, it
+   * is important to check and report the error to the user, otherwise
+   * there might be a loss of data as all data might not be written.
+   * 
+   * If @a cancellable  is not <tt>0</tt>, then the operation can be cancelled by
+   * triggering the cancellable object from another thread. If the operation
+   * was cancelled, the error G::IO_ERROR_CANCELLED will be returned.
+   * Cancelling a close will still leave the stream closed, but there some streams
+   * can use a faster close that doesn't block to e.g. check errors. On
+   * cancellation (as with any error) there is no guarantee that all written
+   * data will reach the target.
+   * @param cancellable Optional cancellable object.
+   * @param error Location to store the error occuring, or <tt>0</tt> to ignore.
+   * @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
+
+  /** Request an asynchronous write of @a count bytes from @a buffer into 
+   * the stream. When the operation is finished @a slot will be called. 
+   * You can then call write_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 written will be passed to the
+   * callback @a slot. It is not an error if this is not the same as the 
+   * requested size, as it can happen e.g. on a partial I/O error, 
+   * but generally we try to write as many bytes as requested. 
+   *
+   * Any outstanding I/O request with higher priority (lower numerical 
+   * value) will be executed before an outstanding request with lower 
+   * priority. Default priority is G_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.
+   *
+   * For the synchronous, blocking version of this function, see 
+   * write().
+   *
+   * @param buffer The buffer containing the data to write. 
+   * @param count The number of bytes to write
+   * @param slot Callback slot to call when the request is satisfied.
+   * @param cancellable Cancellable object.
+   * @param io_priority The io priority of the request.
+   */
   void write_async(const void* buffer, gsize count, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = G_PRIORITY_DEFAULT);
+
+  /** Request an asynchronous write of @a count bytes from @a buffer into 
+   * the stream. When the operation is finished @a slot will be called. 
+   * You can then call write_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 written will be passed to the
+   * callback @a slot. It is not an error if this is not the same as the 
+   * requested size, as it can happen e.g. on a partial I/O error, 
+   * but generally we try to write as many bytes as requested. 
+   *
+   * Any outstanding I/O request with higher priority (lower numerical 
+   * value) will be executed before an outstanding request with lower 
+   * priority. Default priority is G_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.
+   *
+   * For the synchronous, blocking version of this function, see 
+   * write().
+   *
+   * @param buffer The buffer containing the data to write. 
+   * @param count The number of bytes to write
+   * @param slot Callback slot to call when the request is satisfied.
+   * @param io_priority The io priority of the request.
+   */
   void write_async(const void* buffer, gsize count, const SlotAsyncReady& slot, int io_priority = G_PRIORITY_DEFAULT);
   _IGNORE(g_output_stream_write_async)
 
@@ -70,8 +356,33 @@
                g_output_stream_write_finish,
                errthrow)
 
+  /** Splices a stream asynchronously.
+   *  When the operation is finished @a slot will be called. 
+   * You can then call splice_finish() to get the result of the 
+   * operation.
+   *
+   * For the synchronous, blocking version of this function, see 
+   * splice().
+   *
+   * @param source An InputStream.
+   * @param slot Callback slot to call when the request is satisfied.
+   * @param cancellable Cancellable object.
+   * @param io_priority The io priority of the request.
+   */
   void splice_async(const Glib::RefPtr<InputStream>& source, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, OutputStreamSpliceFlags flags = OUTPUT_STREAM_SPLICE_NONE, int io_priority = G_PRIORITY_DEFAULT);
 
+  /** Splices a stream asynchronously.
+   *  When the operation is finished @a slot will be called. 
+   * You can then call splice_finish() to get the result of the 
+   * operation.
+   *
+   * For the synchronous, blocking version of this function, see 
+   * splice().
+   *
+   * @param source An InputStream.
+   * @param slot Callback slot to call when the request is satisfied.
+   * @param io_priority The io priority of the request.
+   */
   void splice_async(const Glib::RefPtr<InputStream>& source, const SlotAsyncReady& slot, OutputStreamSpliceFlags flags = OUTPUT_STREAM_SPLICE_NONE, int io_priority = G_PRIORITY_DEFAULT);
 
   _IGNORE(g_output_stream_splice_async)
@@ -80,16 +391,58 @@
                g_output_stream_splice_finish,
                errthrow)
 
-  //TODO: Can Cancellable be NULL?
+  /** Flushes a stream asynchronously.
+   * When the operation is finished the @a slot will be called, giving the results.
+   * You can then call flush_finish() to get the result of the operation.
+   * For behaviour details see flush().
+   *
+   * @param slot Callback slot to call when the request is satisfied.
+   * @param cancellable Cancellable object.
+   * @param io_priority The io priority of the request.
+   */
   void flush_async(const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = G_PRIORITY_DEFAULT);
+
+  /** Flushes a stream asynchronously.
+   * When the operation is finished the @a slot will be called, giving the results.
+   * You can then call flush_finish() to get the result of the operation.
+   * For behaviour details see flush().
+   *
+   * @param slot Callback slot to call when the request is satisfied.
+   * @param io_priority The io priority of the request.
+   */
+  void flush_async(const SlotAsyncReady& slot, int io_priority = G_PRIORITY_DEFAULT);
   _IGNORE(g_output_stream_flush_async)
 
   _WRAP_METHOD(bool flush_finish(const Glib::RefPtr<AsyncResult>& result),
                g_output_stream_flush_finish,
                errthrow)
 
-  //TODO: Can Cancellable be NULL?
+  /** Requests an asynchronous close of the stream, releasing resources related to it. 
+   * When the operation is finished the @a slot will be called, giving the results.
+   * 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 slot to call when the request is satisfied.
+   * @param cancellable Cancellable object.
+   * @param io_priority The io priority of the request.
+   */
   void close_async(const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = G_PRIORITY_DEFAULT);
+
+  /** Requests an asynchronous close of the stream, releasing resources related to it. 
+   * When the operation is finished the @a slot will be called, giving the results. 
+   * 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 slot to call when the request is satisfied.
+   * @param io_priority The io priority of the request.
+   */
+  void close_async(const SlotAsyncReady& slot, int io_priority = G_PRIORITY_DEFAULT);
   _IGNORE(g_output_stream_close_async)
 
   _WRAP_METHOD(bool close_finish(const Glib::RefPtr<AsyncResult>& result),

Modified: trunk/gio/src/seekable.hg
==============================================================================
--- trunk/gio/src/seekable.hg	(original)
+++ trunk/gio/src/seekable.hg	Sun Jan 20 21:54:24 2008
@@ -29,6 +29,11 @@
 
 /** Stream seeking interface.
  * Seekable is implemented by streams (implementations of InputStream or OutputStream) that support seeking.
+ * To find the position of a stream, use tell(). To find 
+ * out if a stream supports seeking, use can_seek(). To position a 
+ * stream, use seek(). To find out if a stream supports 
+ * truncating, use can_truncate(). To truncate a stream, use 
+ * truncate().
  *
  * @newin2p16
  */
@@ -75,12 +80,12 @@
 
 //TODO: Write the .defs for these:
   _WRAP_VFUNC(goffset tell() const, tell)
-  _WRAP_VFUNC(goffset can_seek(), can_seek)
+  _WRAP_VFUNC(goffset can_seek() const, can_seek)
   _WRAP_VFUNC(goffset seek(goffset offset, Glib::SeekType type, const Glib::RefPtr<Cancellable>& cancellable, GError** error), seek)
-  _WRAP_VFUNC(goffset can_truncate(), can_truncate)
+  _WRAP_VFUNC(goffset can_truncate() const, can_truncate)
 
-  //TODO: Rename to truncate()?
-  _WRAP_VFUNC(goffset truncate_fn(goffset offset, const Glib::RefPtr<Cancellable>& cancellable, GError** error), truncate_fn)
+  //Renamed to truncate() - we don't know why it's called truncate_fn in C.
+  _WRAP_VFUNC(goffset truncate(goffset offset, const Glib::RefPtr<Cancellable>& cancellable, GError** error), truncate_fn)
 
   //There are no properties or signals.
 };