GSeekable
3
GIO Library

# GSeekable

Stream seeking interface

## Synopsis

    #include <gio/gio.h>

                        GSeekable;
                        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 GFileOutputStream, GMemoryInputStream, GMemoryOutputStream and GFileInputStream.

## Description

GSeekable is implemented by streams (implementations of GInputStream or GOutputStream) that support seeking.

## Details

### GSeekable

    typedef struct _GSeekable GSeekable;

Seek object for streaming operations.

### GSeekableIface

    typedef struct {
      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 */
    } GSeekableIface;

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

  Chekcs if truncation is suppored 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`.

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.

`error` :

  a GError location to store the error occuring, 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.

`seekable` :

  a GSeekable.

`offset` :

  a goffset.

`cancellable` :

  optional GCancellable object, `NULL` to ignore.

`error` :

  a GError location to store the error occuring, 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