gpollableutils

gpollableutils — GPollableInputStream / GPollableOutputStream utilities

Synopsis

#include <gio/gio.h>

gboolean            (*GPollableSourceFunc)              (GObject *pollable_stream,
                                                         gpointer user_data);
GSource *           g_pollable_source_new               (GObject *pollable_stream);
GSource *           g_pollable_source_new_full          (gpointer pollable_stream,
                                                         GSource *child_source,
                                                         GCancellable *cancellable);

gssize              g_pollable_stream_read              (GInputStream *stream,
                                                         void *buffer,
                                                         gsize count,
                                                         gboolean blocking,
                                                         GCancellable *cancellable,
                                                         GError **error);
gssize              g_pollable_stream_write             (GOutputStream *stream,
                                                         const void *buffer,
                                                         gsize count,
                                                         gboolean blocking,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            g_pollable_stream_write_all         (GOutputStream *stream,
                                                         const void *buffer,
                                                         gsize count,
                                                         gboolean blocking,
                                                         gsize *bytes_written,
                                                         GCancellable *cancellable,
                                                         GError **error);

Description

Utility functions for GPollableInputStream and GPollableOutputStream implementations.

Details

GPollableSourceFunc ()

gboolean            (*GPollableSourceFunc)              (GObject *pollable_stream,
                                                         gpointer user_data);

This is the function type of the callback used for the GSource returned by g_pollable_input_stream_create_source() and g_pollable_output_stream_create_source().

pollable_stream :

the GPollableInputStream or GPollableOutputStream

user_data :

data passed in by the user.

Returns :

it should return FALSE if the source should be removed.

Since 2.28


g_pollable_source_new ()

GSource *           g_pollable_source_new               (GObject *pollable_stream);

Utility method for GPollableInputStream and GPollableOutputStream implementations. Creates a new GSource that expects a callback of type GPollableSourceFunc. The new source does not actually do anything on its own; use g_source_add_child_source() to add other sources to it to cause it to trigger.

pollable_stream :

the stream associated with the new source

Returns :

the new GSource. [transfer full]

Since 2.28


g_pollable_source_new_full ()

GSource *           g_pollable_source_new_full          (gpointer pollable_stream,
                                                         GSource *child_source,
                                                         GCancellable *cancellable);

Utility method for GPollableInputStream and GPollableOutputStream implementations. Creates a new GSource, as with g_pollable_source_new(), but also attaching child_source (with a dummy callback), and cancellable, if they are non-NULL.

pollable_stream :

the stream associated with the new source. [type GObject]

child_source :

optional child source to attach. [allow-none]

cancellable :

optional GCancellable to attach. [allow-none]

Returns :

the new GSource. [transfer full]

Since 2.34


g_pollable_stream_read ()

gssize              g_pollable_stream_read              (GInputStream *stream,
                                                         void *buffer,
                                                         gsize count,
                                                         gboolean blocking,
                                                         GCancellable *cancellable,
                                                         GError **error);

Tries to read from stream, as with g_input_stream_read() (if blocking is TRUE) or g_pollable_input_stream_read_nonblocking() (if blocking is FALSE). This can be used to more easily share code between blocking and non-blocking implementations of a method.

If blocking is FALSE, then stream must be a GPollableInputStream for which g_pollable_input_stream_can_poll() returns TRUE, or else the behavior is undefined. If blocking is TRUE, then stream does not need to be a GPollableInputStream.

stream :

a GInputStream

buffer :

a buffer to read data into

count :

the number of bytes to read

blocking :

whether to do blocking I/O

cancellable :

optional GCancellable object, NULL to ignore. [allow-none]

error :

location to store the error occurring, or NULL to ignore

Returns :

the number of bytes read, or -1 on error.

Since 2.34


g_pollable_stream_write ()

gssize              g_pollable_stream_write             (GOutputStream *stream,
                                                         const void *buffer,
                                                         gsize count,
                                                         gboolean blocking,
                                                         GCancellable *cancellable,
                                                         GError **error);

Tries to write to stream, as with g_output_stream_write() (if blocking is TRUE) or g_pollable_output_stream_write_nonblocking() (if blocking is FALSE). This can be used to more easily share code between blocking and non-blocking implementations of a method.

If blocking is FALSE, then stream must be a GPollableOutputStream for which g_pollable_output_stream_can_poll() returns TRUE or else the behavior is undefined. If blocking is TRUE, then stream does not need to be a GPollableOutputStream.

stream :

a GOutputStream.

buffer :

the buffer containing the data to write. [array length=count][element-type guint8]

count :

the number of bytes to write

blocking :

whether to do blocking I/O

cancellable :

optional GCancellable object, NULL to ignore. [allow-none]

error :

location to store the error occurring, or NULL to ignore

Returns :

the number of bytes written, or -1 on error.

Since 2.34


g_pollable_stream_write_all ()

gboolean            g_pollable_stream_write_all         (GOutputStream *stream,
                                                         const void *buffer,
                                                         gsize count,
                                                         gboolean blocking,
                                                         gsize *bytes_written,
                                                         GCancellable *cancellable,
                                                         GError **error);

Tries to write count bytes to stream, as with g_output_stream_write_all(), but using g_pollable_stream_write() rather than g_output_stream_write().

On a successful write of count bytes, TRUE is returned, and bytes_written is set to count.

If there is an error during the operation (including G_IO_ERROR_WOULD_BLOCK in the non-blocking case), FALSE is returned and error is set to indicate the error status, bytes_written is updated to contain the number of bytes written into the stream before the error occurred.

As with g_pollable_stream_write(), if blocking is FALSE, then stream must be a GPollableOutputStream for which g_pollable_output_stream_can_poll() returns TRUE or else the behavior is undefined. If blocking is TRUE, then stream does not need to be a GPollableOutputStream.

stream :

a GOutputStream.

buffer :

the buffer containing the data to write. [array length=count][element-type guint8]

count :

the number of bytes to write

blocking :

whether to do blocking I/O

bytes_written :

location to store the number of bytes that was written to the stream. [out]

cancellable :

optional GCancellable object, NULL to ignore. [allow-none]

error :

location to store the error occurring, or NULL to ignore

Returns :

TRUE on success, FALSE if there was an error

Since 2.34