GSeekable
GSeekable — Stream seeking interface
|
|
Object Hierarchy
GInterface
╰── GSeekable
Prerequisites
GSeekable requires
GObject.
Includes
#include <gio/gio.h>
Description
GSeekable is implemented by streams (implementations of
GInputStream or GOutputStream) that support seeking.
Seekable streams largely fall into two categories: resizable and
fixed-size.
GSeekable on fixed-sized streams is approximately the same as POSIX
lseek() on a block device (for example: attempting to seek past the
end of the device is an error). Fixed streams typically cannot be
truncated.
GSeekable on resizable streams is approximately the same as POSIX
lseek() on a normal file. Seeking past the end and writing data will
usually cause the stream to resize by introducing zero bytes.
Functions
g_seekable_tell ()
goffset
g_seekable_tell (GSeekable *seekable);
Tells the current position within the stream.
Returns
the offset from the beginning of the buffer.
g_seekable_can_seek ()
gboolean
g_seekable_can_seek (GSeekable *seekable);
Tests if the stream supports the GSeekableIface.
Returns
TRUE if seekable
can be seeked. FALSE otherwise.
g_seekable_seek ()
gboolean
g_seekable_seek (GSeekable *seekable,
goffset offset,
GSeekType type,
GCancellable *cancellable,
GError **error);
Seeks in the stream by the given offset
, modified by type
.
Attempting to seek past the end of the stream will have different
results depending on if the stream is fixed-sized or resizable. If
the stream is resizable then seeking past the end and then writing
will result in zeros filling the empty space. Seeking past the end
of a resizable stream and reading will result in EOF. Seeking past
the end of a fixed-sized stream will fail.
Any operation that would result in a negative offset will fail.
If cancellable
is not NULL, 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.
Returns
TRUE if successful. If an error
has occurred, this function will return FALSE and set error
appropriately if present.
g_seekable_can_truncate ()
gboolean
g_seekable_can_truncate (GSeekable *seekable);
Tests if the length of the stream can be adjusted with
g_seekable_truncate().
Returns
TRUE if the stream can be truncated, FALSE otherwise.
g_seekable_truncate ()
gboolean
g_seekable_truncate (GSeekable *seekable,
goffset offset,
GCancellable *cancellable,
GError **error);
Sets the length of the stream to offset
. If the stream was previously
larger than offset
, the extra data is discarded. If the stream was
previouly shorter than offset
, it is extended with NUL ('\0') bytes.
If cancellable
is not NULL, 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. If an
operation was partially finished when the operation was cancelled the
partial result will be returned, without an error.
[virtual truncate_fn]
Returns
TRUE if successful. If an error
has occurred, this function will return FALSE and set error
appropriately if present.
Types and Values
GSeekable
typedef struct _GSeekable GSeekable;
Seek object for streaming operations.
struct GSeekableIface
struct GSeekableIface {
GTypeInterface g_iface;
/* Virtual Table */
goffset (* tell) (GSeekable *seekable);
gboolean (* can_seek) (GSeekable *seekable);
gboolean (* seek) (GSeekable *seekable,
goffset offset,
GSeekType type,
GCancellable *cancellable,
GError **error);
gboolean (* can_truncate) (GSeekable *seekable);
gboolean (* truncate_fn) (GSeekable *seekable,
goffset offset,
GCancellable *cancellable,
GError **error);
/* TODO: Async seek/truncate */
};
Provides an interface for implementing seekable functionality on I/O Streams.