1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2006-2007 Red Hat, Inc.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: Alexander Larsson <alexl@redhat.com>
24 #include "gseekable.h"
30 * @short_description: Stream seeking interface
32 * @see_also: #GInputStream, #GOutputStream
34 * #GSeekable is implemented by streams (implementations of
35 * #GInputStream or #GOutputStream) that support seeking.
37 * Seekable streams largely fall into two categories: resizable and
40 * #GSeekable on fixed-sized streams is approximately the same as POSIX
41 * lseek() on a block device (for example: attmepting to seek past the
42 * end of the device is an error). Fixed streams typically cannot be
45 * #GSeekable on resizable streams is approximately the same as POSIX
46 * lseek() on a normal file. Seeking past the end and writing data will
47 * usually cause the stream to resize by introducing zero bytes.
50 typedef GSeekableIface GSeekableInterface;
51 G_DEFINE_INTERFACE (GSeekable, g_seekable, G_TYPE_OBJECT)
54 g_seekable_default_init (GSeekableInterface *iface)
60 * @seekable: a #GSeekable.
62 * Tells the current position within the stream.
64 * Returns: the offset from the beginning of the buffer.
67 g_seekable_tell (GSeekable *seekable)
69 GSeekableIface *iface;
71 g_return_val_if_fail (G_IS_SEEKABLE (seekable), 0);
73 iface = G_SEEKABLE_GET_IFACE (seekable);
75 return (* iface->tell) (seekable);
79 * g_seekable_can_seek:
80 * @seekable: a #GSeekable.
82 * Tests if the stream supports the #GSeekableIface.
84 * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
87 g_seekable_can_seek (GSeekable *seekable)
89 GSeekableIface *iface;
91 g_return_val_if_fail (G_IS_SEEKABLE (seekable), FALSE);
93 iface = G_SEEKABLE_GET_IFACE (seekable);
95 return (* iface->can_seek) (seekable);
100 * @seekable: a #GSeekable.
101 * @offset: a #goffset.
102 * @type: a #GSeekType.
103 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
104 * @error: a #GError location to store the error occurring, or %NULL to
107 * Seeks in the stream by the given @offset, modified by @type.
109 * Attempting to seek past the end of the stream will have different
110 * results depending on if the stream is fixed-sized or resizable. If
111 * the stream is resizable then seeking past the end and then writing
112 * will result in zeros filling the empty space. Seeking past the end
113 * of a resizable stream and reading will result in EOF. Seeking past
114 * the end of a fixed-sized stream will fail.
116 * Any operation that would result in a negative offset will fail.
118 * If @cancellable is not %NULL, then the operation can be cancelled by
119 * triggering the cancellable object from another thread. If the operation
120 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
122 * Returns: %TRUE if successful. If an error
123 * has occurred, this function will return %FALSE and set @error
124 * appropriately if present.
127 g_seekable_seek (GSeekable *seekable,
130 GCancellable *cancellable,
133 GSeekableIface *iface;
135 g_return_val_if_fail (G_IS_SEEKABLE (seekable), FALSE);
137 iface = G_SEEKABLE_GET_IFACE (seekable);
139 return (* iface->seek) (seekable, offset, type, cancellable, error);
143 * g_seekable_can_truncate:
144 * @seekable: a #GSeekable.
146 * Tests if the stream can be truncated.
148 * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
151 g_seekable_can_truncate (GSeekable *seekable)
153 GSeekableIface *iface;
155 g_return_val_if_fail (G_IS_SEEKABLE (seekable), FALSE);
157 iface = G_SEEKABLE_GET_IFACE (seekable);
159 return (* iface->can_truncate) (seekable);
163 * g_seekable_truncate:
164 * @seekable: a #GSeekable.
165 * @offset: a #goffset.
166 * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
167 * @error: a #GError location to store the error occurring, or %NULL to
170 * Truncates a stream with a given #offset.
172 * If @cancellable is not %NULL, then the operation can be cancelled by
173 * triggering the cancellable object from another thread. If the operation
174 * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
175 * operation was partially finished when the operation was cancelled the
176 * partial result will be returned, without an error.
178 * Virtual: truncate_fn
179 * Returns: %TRUE if successful. If an error
180 * has occurred, this function will return %FALSE and set @error
181 * appropriately if present.
184 g_seekable_truncate (GSeekable *seekable,
186 GCancellable *cancellable,
189 GSeekableIface *iface;
191 g_return_val_if_fail (G_IS_SEEKABLE (seekable), FALSE);
193 iface = G_SEEKABLE_GET_IFACE (seekable);
195 return (* iface->truncate_fn) (seekable, offset, cancellable, error);