GNOME Bugzilla – Bug 509990
GSeekable documentation unclear
Last modified: 2008-01-21 15:12:04 UTC
GFileInputStream and GFileOutputStream have this text in their documenation "In addition to the generic g_seekable_ API, GFileOutputStream has its own API for seeking and positioning.": http://library.gnome.org/devel/gio/unstable/GFileOutputStream.html#id3117095 But it doesn't say when I should use the GSeekable API and when I should use the specific API, or why there is a specific one. Also, the functions can set a GError, but don't say what GError domains might be set. See, for instance, g_convert() to see how other functions document this: http://library.gnome.org/devel/glib/stable/glib-Character-Set-Conversion.html#g-convert
> But it doesn't say when I should use the GSeekable API and when I should use > the specific API, or why there is a specific one. Honestly no idea. I really don't see any point in the file stream specific api, and would be happier if it went away. Alex, why is that there ? > Also, the functions can set a GError, but don't say what GError domains might > be set. Yeah, we are not very good at documenting that. I'd accept a patch to improve it, but any such documentation would at best be considered advisory, not mandatory. Any switch statement over the error domain should always have a default case for handling other errors.
GFileInputStream is an input stream for files, and as such generally support seeking (and other file operations like the fstat() equivalent). It does this by implementing GSeekable in its vtable so that child classes can easily implement it. I also added direct calls to the seekable ops in the g_file_input_stream_ namespace. We could remove these if we wanted I guess. I merely added them for ease of use.
Thanks. I don't think there is much precedent for having these convenience functions. It's a bit like having gtk_button_show() as well as just gtk_widget_show(). I'd prefer to remove them. If not, we need to document them as being purely convenience functions / syntactic sugar.
removed.