libpurple/queuedoutputstream.h

   1 /*
   2  *
   3  * purple
   4  *
   5  * Purple is the legal property of its developers, whose names are too numerous
   6  * to list here.  Please refer to the COPYRIGHT file distributed with this
   7  * source distribution.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  22  */
  23
  24 #ifndef PURPLE_QUEUED_OUTPUT_STREAM_H
  25 #define PURPLE_QUEUED_OUTPUT_STREAM_H
  26 /**
  27  * SECTION:queuedoutputstream
  28  * @section_id: libpurple-queuedoutputstream
  29  * @short_description: GOutputStream for queuing data to output
  30  * @title: GOutputStream class
  31  *
  32  * A #PurpleQueuedOutputStream is a #GOutputStream which allows data to be
  33  * queued for outputting. It differs from a #GBufferedOutputStream in that
  34  * it allows for data to be queued while other operations are in progress.
  35  */
  36
  37 #include <gio/gio.h>
  38
  39 G_BEGIN_DECLS
  40
  41 #define PURPLE_TYPE_QUEUED_OUTPUT_STREAM  purple_queued_output_stream_get_type()
  42
  43 G_DECLARE_FINAL_TYPE(PurpleQueuedOutputStream,
  44                 purple_queued_output_stream, PURPLE,
  45                 QUEUED_OUTPUT_STREAM, GFilterOutputStream)
  46
  47 /*
  48  * purple_queued_output_stream_new
  49  * @base_stream: Base output stream to wrap with the queued stream
  50  *
  51  * Creates a new queued output stream for a base stream.
  52  */
  53 PurpleQueuedOutputStream *purple_queued_output_stream_new(
  54                 GOutputStream *base_stream);
  55
  56 /*
  57  * purple_queued_output_stream_push_bytes_async
  58  * @stream: #PurpleQueuedOutputStream to push bytes to
  59  * @bytes: Bytes to queue
  60  * @priority: IO priority of the request
  61  * @cancellable: (allow-none): Optional #GCancellable object, NULL to ignore
  62  * @callback: (scope async): Callback to call when the request is finished
  63  * @user_data: (closure): Data to pass to the callback function
  64  *
  65  * Asynchronously queues and then writes data to the output stream.
  66  * Once the data has been written, or an error occurs, the callback
  67  * will be called.
  68  *
  69  * Be careful such that if there's a fatal stream error, all remaining queued
  70  * operations will likely return this error. Use
  71  * #purple_queued_output_stream_clear_queue() to clear the queue on such
  72  * an error to only report it a single time.
  73  */
  74 void purple_queued_output_stream_push_bytes_async(
  75                 PurpleQueuedOutputStream *stream, GBytes *bytes,
  76                 int io_priority, GCancellable *cancellable,
  77                 GAsyncReadyCallback callback, gpointer user_data);
  78
  79 /*
  80  * purple_queued_output_stream_push_bytes_finish
  81  * @stream: #PurpleQueuedOutputStream bytes were pushed to
  82  * @result: The #GAsyncResult of this operation
  83  * @error: A GError location to store the error, or NULL to ignore
  84  *
  85  * Finishes pushing bytes asynchronously.
  86  *
  87  * Returns: %TRUE on success, %FALSE if there was an error
  88  */
  89 gboolean purple_queued_output_stream_push_bytes_finish(
  90                 PurpleQueuedOutputStream *stream,
  91                 GAsyncResult *result, GError **error);
  92
  93 /*
  94  * purple_queued_output_stream_clear_queue
  95  * @stream: #PurpleQueuedOutputStream to clear
  96  *
  97  * Clears the queue of any pending bytes. However, any bytes that are
  98  * in the process of being sent will finish their operation.
  99  *
 100  * This function is useful for clearing the queue in case of an IO error.
 101  * Call this in the async callback in order to clear the queue and avoid
 102  * having all #purple_queue_output_stream_push_bytes_async() calls on
 103  * this queue return errors if there's a fatal stream error.
 104  */
 105 void purple_queued_output_stream_clear_queue(PurpleQueuedOutputStream *stream);
 106
 107 G_END_DECLS
 108
 109 #endif /* PURPLE_QUEUED_OUTPUT_STREAM_H */