From ed6b06315c17441b41c001d38537c904b8fe18de Mon Sep 17 00:00:00 2001 From: Gian Mario Tagliaretti Date: Sat, 9 May 2009 00:02:33 +0200 Subject: Add docs for the gio.InputStream class --- docs/reference/pygio-classes.xml | 1 + docs/reference/pygio-inputstream.xml | 730 +++++++++++++++++++++++++++++++++++ 2 files changed, 731 insertions(+) create mode 100644 docs/reference/pygio-inputstream.xml (limited to 'docs/reference') diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml index c4722b3..58c3994 100644 --- a/docs/reference/pygio-classes.xml +++ b/docs/reference/pygio-classes.xml @@ -19,6 +19,7 @@ + diff --git a/docs/reference/pygio-inputstream.xml b/docs/reference/pygio-inputstream.xml new file mode 100644 index 0000000..b1807e5 --- /dev/null +++ b/docs/reference/pygio-inputstream.xml @@ -0,0 +1,730 @@ + + + + + + gio.InputStream + Base class for implementing streaming input + + + + Synopsis + + + gio.InputStream + gobject.GObject + + + clear_pending + + + + close + cancellableNone + + + close_async + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + close_finish + result + + + has_pending + + + + is_closed + + + + read + count-1 + cancellableNone + + + read_async + count + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + read_finish + result + + + read_part + count-1 + cancellableNone + + + set_pending + + + + skip + count + cancellableNone + + + skip_async + count + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + skip_finish + result + + + + + + + + Ancestry + ++-- gobject.GObject + +-- gio.InputStream + + + + + + Description + + + gio.InputStream + has functions to read from a stream ( + gio.InputStream.read() + ), to close a stream ( + gio.InputStream.close() + ) and to skip some content ( + gio.InputStream.skip() + ). + + + To copy the content of an input stream to an output stream without manually + handling the reads and writes, use + gio.OutputStream.splice(). + + + All of these functions have async variants too. + + + + + Methods + + + gio.InputStream.clear_pending + + + clear_pending + + + + + + + + The clear_pending() method clears the pending flag on stream. + + + + + gio.InputStream.close + + + close + cancellableNone + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + + Returns : + True on success + False on failure. + + + + + + The close() method closes the stream, releasing + resources related to it. + + + Once the stream is closed, all other operations will return gio.IO_ERROR_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 function to 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 return + gio.IO_ERROR_CLOSED for all operations. Still, it is important to check and report + the error to the user. + + + If cancellable is not None, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave + the stream closed, but some streams can use a faster close that doesn't block to e.g. + check errors. + + + + + gio.InputStream.close_async + + + close_async + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + + + callback : + a GAsyncReadyCallback to call when the request is satisfied. + + + + io_priority : + the + + of the request. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to callback function. + + + + + + The close_async() method asynchronously requests an + asynchronous closes of the stream, releasing resources related to it. + + + For more details, see + gio.InputStream.close() + which is the synchronous version of this call. + + + When the operation is finished, callback will be called. You can then call + gio.InputStream.close_finish() + to get the result of the operation. + + + + + gio.InputStream.close_finish + + + close_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + True if the stream was closed successfully. + + + + + + The close_finish() method finishes an asynchronous + file append operation started with + gio.InputStream.close_async(). + + + + + gio.InputStream.has_pending + + + has_pending + + + + + + Returns : + True if stream has pending actions. + + + + + + The has_pending() method checks if an input stream has pending actions. + + + + + gio.InputStream.is_closed + + + is_closed + + + + + + Returns : + True if the stream is closed. + + + + + + The is_closed() method checks if an input stream is closed. + + + + + gio.InputStream.read + + + read + count-1 + cancellableNone + + + + + count : + optionally the number of bytes that will be read from the stream. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + + Returns : + The number of bytes read, or -1 on error. + + + + + + The read() method tries to read count bytes from + the stream into the buffer starting at buffer. Will block during this read. + + + This function is similar to + gio.InputStream.read_part(), + except it tries to read as many bytes as requested, only stopping on an error or end of stream. + + + On a successful read of count bytes, or if we reached the end of the stream, + True is returned, and bytes_read is set to the number of bytes read into buffer. + + + If cancellable is not None, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave + the stream closed, but some streams can use a faster close that doesn't block to e.g. + check errors. + + + If there is an error during the operation False is returned and error + is set to indicate the error status, bytes_read is updated to contain the number of + bytes read into buffer before the error occurred. + + + + + gio.InputStream.read_async + + + read_async + count + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + + + count : + the number of bytes that will be read from the stream. + + + + callback : + a GAsyncReadyCallback to call when the request is satisfied. + + + + io_priority : + the + + of the request. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to callback function. + + + + + + The read_async() method requests an asynchronous read + of count bytes from the stream into the buffer. + + + For more details, see + gio.InputStream.read() + which is the synchronous version of this call. + + + When the operation is finished, callback will be called. You can then call + gio.InputStream.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.IO_ERROR_PENDING errors. + + + A value of count larger than G_MAXSSIZE will cause a gio.IO_ERROR_INVALID_ARGUMENT error. + + + On success, the number of bytes read into the buffer 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 read as many bytes as requested. Zero + is returned on end of file (or if 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 glib.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. + + + + + gio.InputStream.read_finish + + + read_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + The number of bytes read in, or -1 on error. + + + + + + The read_finish() method finishes an asynchronous + stream read operation started by + gio.InputStream.read_async(). + + + + + gio.InputStream.read_part + + + read_part + count-1 + cancellableNone + + + + + count : + optionally the number of bytes that will be read from the stream. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + + Returns : + The number of bytes read, or -1 on error. + + + + + + The read_part() method tries to read count bytes from + the stream into the buffer starting at buffer. Will block during this read. + + + If count is zero returns zero and does nothing. A value of count larger than + G_MAXSSIZE will cause a gio.IO_ERROR_INVALID_ARGUMENT error. + + + 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 count is zero), but never otherwise. + + + If cancellable is not None, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave + the stream closed, but some streams can use a faster close that doesn't block to e.g. + check errors. + + + On error -1 is returned and error is set accordingly. + + + This method roughly corresponds to C GIO g_input_stream_read. + + + + + gio.InputStream.set_pending + + + set_pending + + + + + + Returns : + True if pending was previously + unset and is now set. + + + + + + The set_pending() method sets stream to have actions pending. + If the pending flag is already set or stream is closed, + it will return False and set error. + + + + + gio.InputStream.skip + + + skip + count + cancellableNone + + + + + count : + the number of bytes that will be skipped from the stream. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + + Returns : + The number of bytes skipped, or -1 on error + + + + + + The skip() method tries to skip 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. + + + If cancellable is not None, then the operation can be cancelled by + triggering the cancellable object from another thskip. If the operation was cancelled, + the error gio.IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave + the stream closed, but some streams can use a faster close that doesn't block to e.g. + check errors. + + + + + gio.InputStream.skip_async + + + skip_async + count + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + + + count : + the number of bytes that will be skipped from the stream. + + + + callback : + a GAsyncskipyCallback to call when the request is satisfied. + + + + io_priority : + the + + of the request. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to callback function. + + + + + + The skip_async() method request an asynchronous + skip of count bytes from the stream. + + + For more details, see + gio.InputStream.skip() + which is the synchronous version of this call. + + + When the operation is finished, callback will be called. You can then call + gio.InputStream.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.IO_ERROR_PENDING errors. + + + A value of count larger than G_MAXSSIZE will cause a gio.IO_ERROR_INVALID_ARGUMENT error. + + + 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 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 glib.PRIORITY_DEFAULT. + + + The asyncronous methods have a default fallback that uses thskips to implement asynchronicity, so + they are optional for inheriting classes. However, if you override one you must override all. + + + + + gio.InputStream.skip_finish + + + skip_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + The number of bytes skipped in, or -1 on error. + + + + + + The skip_finish() method finishes an asynchronous + stream skip operation started by + gio.InputStream.skip_async(). + + + + -- cgit