// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*- /* Copyright (C) 2007 The giomm Development Team * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ #include #include #include _DEFS(giomm,gio) _PINCLUDE(glibmm/private/object_p.h) namespace Gio { //TODO: Implement operator << and >> for streams? /** Base class for implementing streaming input. * * @ingroup Streams * * @newin2p16 */ class InputStream : public Glib::Object { _CLASS_GOBJECT(InputStream, GInputStream, G_INPUT_STREAM, Glib::Object, GObject) public: _WRAP_METHOD(gssize read(void* buffer, gsize count, const Glib::RefPtr& cancellable), g_input_stream_read, errthrow) /** Tries to read @a count bytes from the stream into the buffer starting at * @a buffer. Will block during this read. * * If count is zero returns zero and does nothing. A value of @a count * larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown. * * On success, the number of bytes read into the buffer is returned. * It is not an error if this is not the same as the requested size, as it * can happen e.g. near the end of a file. Zero is returned on end of file * (or if @a count is zero), but never otherwise. * * On error -1 is returned. * @param buffer A buffer to read data into (which should be at least count bytes long). * @param count The number of bytes that will be read from the stream. * @return Number of bytes read, or -1 on error. */ #ifdef GLIBMM_EXCEPTIONS_ENABLED gssize read(void* buffer, gsize count); #else gssize read(void* buffer, gsize count, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED //TODO: for glibmm 2.17/18, we should decide whether to provide a read() // function as below, which would presumably read until EOL, or one with // an additional size parameter, at the same time taking into account // what operators >> and << (for OutputStream) will do. //TODO: gssize read(std::string& buffer, const Glib::RefPtr& cancellable); //TODO: gssize read(std::string& buffer); _WRAP_METHOD(bool read_all(void* buffer, gsize count, gsize& bytes_read, const Glib::RefPtr& cancellable), g_input_stream_read_all, errthrow) /** Tries to read @a count bytes from the stream into the buffer starting at * @a buffer. Will block during this read. * * This function is similar to read(), except it tries to * read as many bytes as requested, only stopping on an error or end of stream. * * On a successful read of @a count bytes, or if we reached the end of the * stream, true is returned, and @a bytes_read is set to the number of bytes * read into @a buffer . * * If there is an error during the operation false is returned and a Gio::Error * is thrown to indicate the error status, @a bytes_read is updated to contain * the number of bytes read into @a buffer before the error occured. * @param buffer A buffer to read data into (which should be at least count bytes long). * @param count The number of bytes that will be read from the stream. * @param bytes_read Location to store the number of bytes that was read from the stream. * @return true on success, false if there was an error. */ #ifdef GLIBMM_EXCEPTIONS_ENABLED bool read_all(void* buffer, gsize count, gsize& bytes_read); #else bool read_all(void* buffer, gsize count, gsize& bytes_read, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED //TODO: bool read_all(std::string& buffer, gsize count, gsize& bytes_read, const Glib::RefPtr& cancellable); //TODO: bool read_all(std::string& buffer, gsize count, gsize& bytes_read) _WRAP_METHOD(gssize skip(gsize count, const Glib::RefPtr& cancellable), g_input_stream_skip, errthrow) /** Tries to skip @a count bytes from the stream. Will block during the operation. * * This is identical to read(), from a behaviour standpoint, * but the bytes that are skipped are not returned to the user. Some * streams have an implementation that is more efficient than reading the data. * * This function is optional for inherited classes, as the default implementation * emulates it using read. * * @param count The number of bytes that will be skipped from the stream. * @return Number of bytes skipped, or -1 on error. */ #ifdef GLIBMM_EXCEPTIONS_ENABLED gssize skip(gsize count); #else gssize skip(gsize count, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED _WRAP_METHOD(bool close(const Glib::RefPtr& cancellable), g_input_stream_close, errthrow) /** Closes the stream, releasing resources related to it. * * Once the stream is closed, all other operations will throw a Gio::Error with CLOSED. * Closing a stream multiple times will not return an error. * * Streams will be automatically closed when the last reference * is dropped, but you might want to call this make sure resources * are released as early as possible. * * Some streams might keep the backing store of the stream (e.g. a file descriptor) * open after the stream is closed. See the documentation for the individual * stream for details. * * On failure the first error that happened will be reported, but the close * operation will finish as much as possible. A stream that failed to * close will still throw a Gio::Error with CLOSED for all operations. Still, it * is important to check and report the error to the user. * * @return true on success, false on failure. */ #ifdef GLIBMM_EXCEPTIONS_ENABLED bool close(); #else bool close(std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED /** Request an asynchronous read of @a count bytes from the stream into the buffer * starting at @a buffer. When the operation is finished @a slot will be called. * You can then call read_finish() to get the result of the * operation. * * During an async request no other sync and async calls are allowed, and will * result in Gio::Error with PENDING being thrown. * * A value of @a count larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown. * * On success, the number of bytes read into the buffer will be passed to the * @a slot callback. It is not an error if this is not the same as the requested size, as it * can happen e.g. near the end of a file, but generally we try to read * as many bytes as requested. Zero is returned on end of file * (or if @a count is zero), but never otherwise. * * Any outstanding i/o request with higher priority (lower numerical value) will * be executed before an outstanding request with lower priority. Default * priority is PRIORITY_DEFAULT. * * The asyncronous methods have a default fallback that uses threads to implement * asynchronicity, so they are optional for inheriting classes. However, if you * override one you must override all. * * @param buffer A buffer to read data into (which should be at least count bytes long). * @param count The number of bytes that will be read from the stream. * @param slot Callback to call when the request is satisfied. * @param cancellable A Cancellable object. * @param io_priority The I/O priority of the request. */ void read_async(void* buffer, gsize count, const SlotAsyncReady& slot, const Glib::RefPtr& cancellable, int io_priority = Glib::PRIORITY_DEFAULT); /** Request an asynchronous read of @a count bytes from the stream into the buffer * starting at @a buffer. When the operation is finished @a slot will be called. * You can then call read_finish() to get the result of the * operation. * * During an async request no other sync and async calls are allowed, and will * result in a Gio::Error with PENDING being thrown. * * A value of @a count larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown. * * On success, the number of bytes read into the buffer will be passed to the * @a slot callback. It is not an error if this is not the same as the requested size, as it * can happen e.g. near the end of a file, but generally we try to read * as many bytes as requested. Zero is returned on end of file * (or if @a count is zero), but never otherwise. * * Any outstanding i/o request with higher priority (lower numerical value) will * be executed before an outstanding request with lower priority. Default * priority is PRIORITY_DEFAULT. * * The asyncronous methods have a default fallback that uses threads to implement * asynchronicity, so they are optional for inheriting classes. However, if you * override one you must override all. * * @param buffer A buffer to read data into (which should be at least count bytes long). * @param count The number of bytes that will be read from the stream. * @param slot Callback to call when the request is satisfied. * @param io_priority The I/O priority of the request. */ void read_async(void* buffer, gsize count, const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT); _IGNORE(g_input_stream_read_async) _WRAP_METHOD(gssize read_finish(const Glib::RefPtr& result), g_input_stream_read_finish, errthrow) //TODO: Use std::size_type instead of gsize? /** Request an asynchronous skip of @a count bytes from the stream into the buffer * starting at @a buffer. When the operation is finished @a slot will be called. * You can then call skip_finish() to get the result of the operation. * * During an async request no other sync and async calls are allowed, and will * result in Gio::Error with PENDING being thrown. * * A value of @a count larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown. * * On success, the number of bytes skipped will be passed to the * callback. It is not an error if this is not the same as the requested size, as it * can happen e.g. near the end of a file, but generally we try to skip * as many bytes as requested. Zero is returned on end of file * (or if @a count is zero), but never otherwise. * * Any outstanding i/o request with higher priority (lower numerical value) will * be executed before an outstanding request with lower priority. Default * priority is PRIORITY_DEFAULT. * * The asyncronous methods have a default fallback that uses threads to implement * asynchronicity, so they are optional for inheriting classes. However, if you * override one you must override all. * * @param count The number of bytes that will be skipped from the stream. * @param slot Callback to call when the request is satisfied. * @param cancellable A Cancellable object. * @param io_priority The I/O priority of the request. */ void skip_async(gsize count, const SlotAsyncReady& slot, const Glib::RefPtr& cancellable, int io_priority = Glib::PRIORITY_DEFAULT); /** Request an asynchronous skip of @a count bytes from the stream into the buffer * starting at @a buffer. When the operation is finished @a slot will be called. * You can then call skip_finish() to get the result of the operation. * * During an async request no other sync and async calls are allowed, and will * result in Gio::Error with PENDING being thrown. * * A value of @a count larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown. * * On success, the number of bytes skipped will be passed to the * callback. It is not an error if this is not the same as the requested size, as it * can happen e.g. near the end of a file, but generally we try to skip * as many bytes as requested. Zero is returned on end of file * (or if @a count is zero), but never otherwise. * * Any outstanding i/o request with higher priority (lower numerical value) will * be executed before an outstanding request with lower priority. Default * priority is PRIORITY_DEFAULT. * * The asyncronous methods have a default fallback that uses threads to implement * asynchronicity, so they are optional for inheriting classes. However, if you * override one you must override all. * * @param count The number of bytes that will be skipped from the stream. * @param slot Callback to call when the request is satisfied. * @param io_priority The I/O priority of the request. */ void skip_async(gsize count, const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT); _IGNORE(g_input_stream_skip_async) _WRAP_METHOD(gssize skip_finish(const Glib::RefPtr& result), g_input_stream_skip_finish, errthrow) /** Requests an asynchronous closes of the stream, releasing resources related to it. * When the operation is finished @a slot will be called. * You can then call close_finish() to get the result of the * operation. * * For behaviour details see close(). * * The asyncronous methods have a default fallback that uses threads to implement * asynchronicity, so they are optional for inheriting classes. However, if you * override one you must override all. * * @param slot Callback to call when the request is satisfied. * @param cancellable A Cancellable object. * @param io_priority The I/O priority of the request. */ void close_async(const SlotAsyncReady& slot, const Glib::RefPtr& cancellable, int io_priority = Glib::PRIORITY_DEFAULT); /** Requests an asynchronous closes of the stream, releasing resources related to it. * When the operation is finished @a slot will be called. * You can then call close_finish() to get the result of the * operation. * * For behaviour details see close(). * * The asyncronous methods have a default fallback that uses threads to implement * asynchronicity, so they are optional for inheriting classes. However, if you * override one you must override all. * * @param slot Callback to call when the request is satisfied. * @param io_priority The I/O priority of the request. */ void close_async(const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT); _IGNORE(g_input_stream_close_async) _WRAP_METHOD(gboolean close_finish(const Glib::RefPtr& result), g_input_stream_close_finish, errthrow) // These are private inside the module (for implementations) _IGNORE(g_input_stream_has_pending, g_input_stream_is_closed, g_input_stream_set_pending, g_input_stream_clear_pending) }; } // namespace Gio