<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="GSeekable">
<refmeta>
<refentrytitle role="top_of_page" id="GSeekable.top_of_page">GSeekable</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GIO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GSeekable</refname>
<refpurpose>Stream seeking interface</refpurpose>
</refnamediv>

<refsynopsisdiv id="GSeekable.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;gio/gio.h&gt;

                    <link linkend="GSeekable-struct">GSeekable</link>;
                    <link linkend="GSeekableIface">GSeekableIface</link>;
<link linkend="goffset">goffset</link>             <link linkend="g-seekable-tell">g_seekable_tell</link>                     (<link linkend="GSeekable">GSeekable</link> *seekable);
<link linkend="gboolean">gboolean</link>            <link linkend="g-seekable-can-seek">g_seekable_can_seek</link>                 (<link linkend="GSeekable">GSeekable</link> *seekable);
<link linkend="gboolean">gboolean</link>            <link linkend="g-seekable-seek">g_seekable_seek</link>                     (<link linkend="GSeekable">GSeekable</link> *seekable,
                                                         <link linkend="goffset">goffset</link> offset,
                                                         <link linkend="GSeekType">GSeekType</link> type,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="gboolean">gboolean</link>            <link linkend="g-seekable-can-truncate">g_seekable_can_truncate</link>             (<link linkend="GSeekable">GSeekable</link> *seekable);
<link linkend="gboolean">gboolean</link>            <link linkend="g-seekable-truncate">g_seekable_truncate</link>                 (<link linkend="GSeekable">GSeekable</link> *seekable,
                                                         <link linkend="goffset">goffset</link> offset,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GError">GError</link> **error);
</synopsis>
</refsynopsisdiv>

<refsect1 id="GSeekable.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GInterface">GInterface</link>
   +----GSeekable
</synopsis>
</refsect1>

<refsect1 id="GSeekable.prerequisites" role="prerequisites">
<title role="prerequisites.title">Prerequisites</title>
<para>
GSeekable requires
 <link linkend="GObject">GObject</link>.</para>
</refsect1>



<refsect1 id="GSeekable.implementations" role="implementations">
<title role="implementations.title">Known Implementations</title>
<para>
GSeekable is implemented by
 <link linkend="GFileOutputStream">GFileOutputStream</link>,  <link linkend="GMemoryOutputStream">GMemoryOutputStream</link>,  <link linkend="GFileIOStream">GFileIOStream</link>,  <link linkend="GMemoryInputStream">GMemoryInputStream</link> and  <link linkend="GFileInputStream">GFileInputStream</link>.</para>
</refsect1>




<refsect1 id="GSeekable.description" role="desc">
<title role="desc.title">Description</title>
<para>
<link linkend="GSeekable"><type>GSeekable</type></link> is implemented by streams (implementations of 
<link linkend="GInputStream"><type>GInputStream</type></link> or <link linkend="GOutputStream"><type>GOutputStream</type></link>) that support seeking.</para>
<para>
</para>
</refsect1>

<refsect1 id="GSeekable.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GSeekable-struct" role="struct">
<title>GSeekable</title>
<indexterm zone="GSeekable-struct"><primary sortas="Seekable">GSeekable</primary></indexterm><programlisting>typedef struct _GSeekable GSeekable;</programlisting>
<para>
Seek object for streaming operations.</para>
<para>
</para></refsect2>
<refsect2 id="GSeekableIface" role="struct">
<title>GSeekableIface</title>
<indexterm zone="GSeekableIface"><primary sortas="SeekableIface">GSeekableIface</primary></indexterm><programlisting>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;
</programlisting>
<para>
Provides an interface for implementing seekable functionality on I/O Streams.</para>
<para>
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="GTypeInterface">GTypeInterface</link>&#160;<structfield>g_iface</structfield>;</term>
<listitem><simpara> The parent interface.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>tell</structfield>&#160;()</term>
<listitem><simpara> Tells the current location within a stream.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>can_seek</structfield>&#160;()</term>
<listitem><simpara> Checks if seeking is supported by the stream.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>seek</structfield>&#160;()</term>
<listitem><simpara> Seeks to a location within a stream.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>can_truncate</structfield>&#160;()</term>
<listitem><simpara> Chekcs if truncation is suppored by the stream.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>truncate_fn</structfield>&#160;()</term>
<listitem><simpara> Truncates a stream.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="g-seekable-tell" role="function">
<title>g_seekable_tell ()</title>
<indexterm zone="g-seekable-tell"><primary sortas="seekable_tell">g_seekable_tell</primary></indexterm><programlisting><link linkend="goffset">goffset</link>             g_seekable_tell                     (<link linkend="GSeekable">GSeekable</link> *seekable);</programlisting>
<para>
Tells the current position within the stream.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>seekable</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSeekable"><type>GSeekable</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the offset from the beginning of the buffer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-seekable-can-seek" role="function">
<title>g_seekable_can_seek ()</title>
<indexterm zone="g-seekable-can-seek"><primary sortas="seekable_can_seek">g_seekable_can_seek</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_seekable_can_seek                 (<link linkend="GSeekable">GSeekable</link> *seekable);</programlisting>
<para>
Tests if the stream supports the <link linkend="GSeekableIface"><type>GSeekableIface</type></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>seekable</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSeekable"><type>GSeekable</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>seekable</parameter> can be seeked. <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-seekable-seek" role="function">
<title>g_seekable_seek ()</title>
<indexterm zone="g-seekable-seek"><primary sortas="seekable_seek">g_seekable_seek</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_seekable_seek                     (<link linkend="GSeekable">GSeekable</link> *seekable,
                                                         <link linkend="goffset">goffset</link> offset,
                                                         <link linkend="GSeekType">GSeekType</link> type,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Seeks in the stream by the given <parameter>offset</parameter>, modified by <parameter>type</parameter>.
</para>
<para>
If <parameter>cancellable</parameter> is not <link linkend="NULL--CAPS"><literal>NULL</literal></link>, then the operation can be cancelled by
triggering the cancellable object from another thread. If the operation
was cancelled, the error <link linkend="G-IO-ERROR-CANCELLED--CAPS"><literal>G_IO_ERROR_CANCELLED</literal></link> will be returned.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>seekable</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSeekable"><type>GSeekable</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="goffset"><type>goffset</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>type</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSeekType"><type>GSeekType</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
<listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore. 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GError"><type>GError</type></link> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to 
ignore.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if successful. If an error
    has occurred, this function will return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> and set <parameter>error</parameter>
    appropriately if present.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-seekable-can-truncate" role="function">
<title>g_seekable_can_truncate ()</title>
<indexterm zone="g-seekable-can-truncate"><primary sortas="seekable_can_truncate">g_seekable_can_truncate</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_seekable_can_truncate             (<link linkend="GSeekable">GSeekable</link> *seekable);</programlisting>
<para>
Tests if the stream can be truncated.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>seekable</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSeekable"><type>GSeekable</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the stream can be truncated, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-seekable-truncate" role="function">
<title>g_seekable_truncate ()</title>
<indexterm zone="g-seekable-truncate"><primary sortas="seekable_truncate">g_seekable_truncate</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_seekable_truncate                 (<link linkend="GSeekable">GSeekable</link> *seekable,
                                                         <link linkend="goffset">goffset</link> offset,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Truncates a stream with a given <link linkend="offset"><type>offset</type></link>. 
</para>
<para>
If <parameter>cancellable</parameter> is not <link linkend="NULL--CAPS"><literal>NULL</literal></link>, then the operation can be cancelled by
triggering the cancellable object from another thread. If the operation
was cancelled, the error <link linkend="G-IO-ERROR-CANCELLED--CAPS"><literal>G_IO_ERROR_CANCELLED</literal></link> will be returned. If an
operation was partially finished when the operation was cancelled the
partial result will be returned, without an error.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>seekable</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GSeekable"><type>GSeekable</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>offset</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="goffset"><type>goffset</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
<listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore. 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GError"><type>GError</type></link> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to 
ignore.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if successful. If an error
    has occurred, this function will return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> and set <parameter>error</parameter>
    appropriately if present. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>



<refsect1 id="GSeekable.see-also">
<title>See Also</title>
#GInputStream, <link linkend="GOutputStream"><type>GOutputStream</type></link>
</refsect1>

</refentry>
