GSeekable

GSeekable — Stream seeking interface

Synopsis

#include <gio/gio.h>

                    GSeekable;
struct              GSeekableIface;
goffset             g_seekable_tell                     (GSeekable *seekable);
gboolean            g_seekable_can_seek                 (GSeekable *seekable);
gboolean            g_seekable_seek                     (GSeekable *seekable,
                                                         goffset offset,
                                                         GSeekType type,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            g_seekable_can_truncate             (GSeekable *seekable);
gboolean            g_seekable_truncate                 (GSeekable *seekable,
                                                         goffset offset,
                                                         GCancellable *cancellable,
                                                         GError **error);

Object Hierarchy

  GInterface
   +----GSeekable

Prerequisites

GSeekable requires GObject.

Known Implementations

GSeekable is implemented by GBufferedInputStream, GBufferedOutputStream, GDataInputStream, GDataOutputStream, GFileIOStream, GFileInputStream, GFileOutputStream, GMemoryInputStream and GMemoryOutputStream.

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: attmepting 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.

Details

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.

GTypeInterface g_iface;

The parent interface.

tell ()

Tells the current location within a stream.

can_seek ()

Checks if seeking is supported by the stream.

seek ()

Seeks to a location within a stream.

can_truncate ()

Checks if truncation is supported by the stream.

truncate_fn ()

Truncates a stream.

g_seekable_tell ()

goffset             g_seekable_tell                     (GSeekable *seekable);

Tells the current position within the stream.

seekable :

a GSeekable.

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.

seekable :

a GSeekable.

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.

seekable :

a GSeekable.

offset :

a goffset.

type :

a GSeekType.

cancellable :

optional GCancellable object, NULL to ignore. [allow-none]

error :

a GError location to store the error occurring, or NULL to ignore.

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 stream can be truncated.

seekable :

a GSeekable.

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);

Truncates a stream with a given offset.

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

seekable :

a GSeekable.

offset :

a goffset.

cancellable :

optional GCancellable object, NULL to ignore. [allow-none]

error :

a GError location to store the error occurring, or NULL to ignore.

Returns :

TRUE if successful. If an error has occurred, this function will return FALSE and set error appropriately if present.

See Also

GInputStream, GOutputStream