Merge remote branch 'gvdb/master'
[platform/upstream/glib.git] / gio / gdatainputstream.c
1 /* GIO - GLib Input, Output and Streaming Library
2  * 
3  * Copyright (C) 2006-2007 Red Hat, Inc.
4  * Copyright (C) 2007 Jürg Billeter
5  * Copyright © 2009 Codethink Limited
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General
18  * Public License along with this library; if not, write to the
19  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
20  * Boston, MA 02111-1307, USA.
21  *
22  * Author: Alexander Larsson <alexl@redhat.com>
23  */
24
25 #include "config.h"
26 #include "gdatainputstream.h"
27 #include "gsimpleasyncresult.h"
28 #include "gcancellable.h"
29 #include "gioenumtypes.h"
30 #include "gioerror.h"
31 #include "glibintl.h"
32
33 #include <string.h>
34
35 /**
36  * SECTION:gdatainputstream
37  * @short_description: Data Input Stream
38  * @include: gio/gio.h
39  * @see_also: #GInputStream
40  * 
41  * Data input stream implements #GInputStream and includes functions for 
42  * reading structured data directly from a binary input stream.
43  *
44  **/
45
46 struct _GDataInputStreamPrivate {
47   GDataStreamByteOrder byte_order;
48   GDataStreamNewlineType newline_type;
49 };
50
51 enum {
52   PROP_0,
53   PROP_BYTE_ORDER,
54   PROP_NEWLINE_TYPE
55 };
56
57 static void g_data_input_stream_set_property (GObject      *object,
58                                               guint         prop_id,
59                                               const GValue *value,
60                                               GParamSpec   *pspec);
61 static void g_data_input_stream_get_property (GObject      *object,
62                                               guint         prop_id,
63                                               GValue       *value,
64                                               GParamSpec   *pspec);
65
66 G_DEFINE_TYPE (GDataInputStream,
67                g_data_input_stream,
68                G_TYPE_BUFFERED_INPUT_STREAM)
69
70
71 static void
72 g_data_input_stream_class_init (GDataInputStreamClass *klass)
73 {
74   GObjectClass *object_class;
75
76   g_type_class_add_private (klass, sizeof (GDataInputStreamPrivate));
77
78   object_class = G_OBJECT_CLASS (klass);
79   object_class->get_property = g_data_input_stream_get_property;
80   object_class->set_property = g_data_input_stream_set_property;
81
82   /**
83    * GDataStream:byte-order:
84    *
85    * The ::byte-order property determines the byte ordering that
86    * is used when reading multi-byte entities (such as integers)
87    * from the stream.
88    */ 
89   g_object_class_install_property (object_class,
90                                    PROP_BYTE_ORDER,
91                                    g_param_spec_enum ("byte-order",
92                                                       P_("Byte order"),
93                                                       P_("The byte order"),
94                                                       G_TYPE_DATA_STREAM_BYTE_ORDER,
95                                                       G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN,
96                                                       G_PARAM_READWRITE|G_PARAM_STATIC_NAME|G_PARAM_STATIC_BLURB));
97
98   /**
99    * GDataStream:newline-type:
100    *
101    * The :newline-type property determines what is considered
102    * as a line ending when reading complete lines from the stream.
103    */ 
104   g_object_class_install_property (object_class,
105                                    PROP_NEWLINE_TYPE,
106                                    g_param_spec_enum ("newline-type",
107                                                       P_("Newline type"),
108                                                       P_("The accepted types of line ending"),
109                                                       G_TYPE_DATA_STREAM_NEWLINE_TYPE,
110                                                       G_DATA_STREAM_NEWLINE_TYPE_LF,
111                                                       G_PARAM_READWRITE|G_PARAM_STATIC_NAME|G_PARAM_STATIC_BLURB));
112 }
113
114 static void
115 g_data_input_stream_set_property (GObject      *object,
116                                   guint         prop_id,
117                                   const GValue *value,
118                                   GParamSpec   *pspec)
119 {
120   GDataInputStream        *dstream;
121
122   dstream = G_DATA_INPUT_STREAM (object);
123
124    switch (prop_id)
125     {
126     case PROP_BYTE_ORDER:
127       g_data_input_stream_set_byte_order (dstream, g_value_get_enum (value));
128       break;
129
130     case PROP_NEWLINE_TYPE:
131       g_data_input_stream_set_newline_type (dstream, g_value_get_enum (value));
132       break;
133
134     default:
135       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
136       break;
137     }
138
139 }
140
141 static void
142 g_data_input_stream_get_property (GObject    *object,
143                                   guint       prop_id,
144                                   GValue     *value,
145                                   GParamSpec *pspec)
146 {
147   GDataInputStreamPrivate *priv;
148   GDataInputStream        *dstream;
149
150   dstream = G_DATA_INPUT_STREAM (object);
151   priv = dstream->priv;
152
153   switch (prop_id)
154     { 
155     case PROP_BYTE_ORDER:
156       g_value_set_enum (value, priv->byte_order);
157       break;
158
159     case PROP_NEWLINE_TYPE:
160       g_value_set_enum (value, priv->newline_type);
161       break;
162
163     default:
164       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
165       break;
166     }
167
168 }
169 static void
170 g_data_input_stream_init (GDataInputStream *stream)
171 {
172   stream->priv = G_TYPE_INSTANCE_GET_PRIVATE (stream,
173                                               G_TYPE_DATA_INPUT_STREAM,
174                                               GDataInputStreamPrivate);
175
176   stream->priv->byte_order = G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN;
177   stream->priv->newline_type = G_DATA_STREAM_NEWLINE_TYPE_LF;
178 }
179
180 /**
181  * g_data_input_stream_new:
182  * @base_stream: a #GInputStream.
183  * 
184  * Creates a new data input stream for the @base_stream.
185  * 
186  * Returns: a new #GDataInputStream.
187  **/
188 GDataInputStream *
189 g_data_input_stream_new (GInputStream *base_stream)
190 {
191   GDataInputStream *stream;
192
193   g_return_val_if_fail (G_IS_INPUT_STREAM (base_stream), NULL);
194
195   stream = g_object_new (G_TYPE_DATA_INPUT_STREAM,
196                          "base-stream", base_stream,
197                          NULL);
198
199   return stream;
200 }
201
202 /**
203  * g_data_input_stream_set_byte_order:
204  * @stream: a given #GDataInputStream.
205  * @order: a #GDataStreamByteOrder to set.
206  * 
207  * This function sets the byte order for the given @stream. All subsequent
208  * reads from the @stream will be read in the given @order.
209  *  
210  **/
211 void
212 g_data_input_stream_set_byte_order (GDataInputStream     *stream,
213                                     GDataStreamByteOrder  order)
214 {
215   GDataInputStreamPrivate *priv;
216
217   g_return_if_fail (G_IS_DATA_INPUT_STREAM (stream));
218
219   priv = stream->priv;
220
221   if (priv->byte_order != order)
222     {
223       priv->byte_order = order;
224       
225       g_object_notify (G_OBJECT (stream), "byte-order");
226     }
227 }
228
229 /**
230  * g_data_input_stream_get_byte_order:
231  * @stream: a given #GDataInputStream.
232  * 
233  * Gets the byte order for the data input stream.
234  * 
235  * Returns: the @stream's current #GDataStreamByteOrder. 
236  **/
237 GDataStreamByteOrder
238 g_data_input_stream_get_byte_order (GDataInputStream *stream)
239 {
240   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN);
241
242   return stream->priv->byte_order;
243 }
244
245 /**
246  * g_data_input_stream_set_newline_type:
247  * @stream: a #GDataInputStream.
248  * @type: the type of new line return as #GDataStreamNewlineType.
249  * 
250  * Sets the newline type for the @stream.
251  * 
252  * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
253  * chunk ends in "CR" we must read an additional byte to know if this is "CR" or
254  * "CR LF", and this might block if there is no more data availible.
255  *  
256  **/
257 void
258 g_data_input_stream_set_newline_type (GDataInputStream       *stream,
259                                       GDataStreamNewlineType  type)
260 {
261   GDataInputStreamPrivate *priv;
262
263   g_return_if_fail (G_IS_DATA_INPUT_STREAM (stream));
264
265   priv = stream->priv;
266   
267   if (priv->newline_type != type)
268     {
269       priv->newline_type = type;
270
271       g_object_notify (G_OBJECT (stream), "newline-type");
272     }
273 }
274
275 /**
276  * g_data_input_stream_get_newline_type:
277  * @stream: a given #GDataInputStream.
278  * 
279  * Gets the current newline type for the @stream.
280  * 
281  * Returns: #GDataStreamNewlineType for the given @stream.
282  **/
283 GDataStreamNewlineType
284 g_data_input_stream_get_newline_type (GDataInputStream *stream)
285 {
286   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), G_DATA_STREAM_NEWLINE_TYPE_ANY);
287
288   return stream->priv->newline_type;
289 }
290
291 static gboolean
292 read_data (GDataInputStream  *stream,
293            void              *buffer,
294            gsize              size,
295            GCancellable      *cancellable,
296            GError           **error)
297 {
298   gsize available;
299   gssize res;
300
301   while ((available = g_buffered_input_stream_get_available (G_BUFFERED_INPUT_STREAM (stream))) < size)
302     {
303       res = g_buffered_input_stream_fill (G_BUFFERED_INPUT_STREAM (stream),
304                                           size - available,
305                                           cancellable, error);
306       if (res < 0)
307         return FALSE;
308       if (res == 0)
309         {
310           g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_FAILED,
311                                _("Unexpected early end-of-stream"));
312           return FALSE;
313         }
314     }
315   
316   /* This should always succeed, since it's in the buffer */
317   res = g_input_stream_read (G_INPUT_STREAM (stream),
318                              buffer, size,
319                              NULL, NULL);
320   g_warn_if_fail (res == size);
321   return TRUE;
322 }
323
324
325 /**
326  * g_data_input_stream_read_byte:
327  * @stream: a given #GDataInputStream.
328  * @cancellable: optional #GCancellable object, %NULL to ignore.
329  * @error: #GError for error reporting.
330  * 
331  * Reads an unsigned 8-bit/1-byte value from @stream.
332  *
333  * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 
334  * if an error occurred.
335  **/
336 guchar
337 g_data_input_stream_read_byte (GDataInputStream  *stream,
338                                GCancellable       *cancellable,
339                                GError            **error)
340 {
341   guchar c;
342   
343   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), '\0');
344   
345   if (read_data (stream, &c, 1, cancellable, error))
346       return c;
347   
348   return 0;
349 }
350
351
352 /**
353  * g_data_input_stream_read_int16:
354  * @stream: a given #GDataInputStream.
355  * @cancellable: optional #GCancellable object, %NULL to ignore.
356  * @error: #GError for error reporting.
357  * 
358  * Reads a 16-bit/2-byte value from @stream.
359  *
360  * In order to get the correct byte order for this read operation, 
361  * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
362  * 
363  * Returns: a signed 16-bit/2-byte value read from @stream or %0 if 
364  * an error occurred.
365  **/
366 gint16
367 g_data_input_stream_read_int16 (GDataInputStream  *stream,
368                                GCancellable       *cancellable,
369                                GError            **error)
370 {
371   gint16 v;
372   
373   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), 0);
374   
375   if (read_data (stream, &v, 2, cancellable, error))
376     {
377       switch (stream->priv->byte_order)
378         {
379         case G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN:
380           v = GINT16_FROM_BE (v);
381           break;
382         case G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN:
383           v = GINT16_FROM_LE (v);
384           break;
385         case G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN:
386         default:
387           break;
388         }
389       return v;
390     }
391   
392   return 0;
393 }
394
395
396 /**
397  * g_data_input_stream_read_uint16:
398  * @stream: a given #GDataInputStream.
399  * @cancellable: optional #GCancellable object, %NULL to ignore.
400  * @error: #GError for error reporting.
401  *
402  * Reads an unsigned 16-bit/2-byte value from @stream.
403  *
404  * In order to get the correct byte order for this read operation, 
405  * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). 
406  * 
407  * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if 
408  * an error occurred. 
409  **/
410 guint16
411 g_data_input_stream_read_uint16 (GDataInputStream  *stream,
412                                  GCancellable       *cancellable,
413                                  GError            **error)
414 {
415   guint16 v;
416   
417   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), 0);
418   
419   if (read_data (stream, &v, 2, cancellable, error))
420     {
421       switch (stream->priv->byte_order)
422         {
423         case G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN:
424           v = GUINT16_FROM_BE (v);
425           break;
426         case G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN:
427           v = GUINT16_FROM_LE (v);
428           break;
429         case G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN:
430         default:
431           break;
432         }
433       return v;
434     }
435   
436   return 0;
437 }
438
439
440 /**
441  * g_data_input_stream_read_int32:
442  * @stream: a given #GDataInputStream.
443  * @cancellable: optional #GCancellable object, %NULL to ignore.
444  * @error: #GError for error reporting.
445  * 
446  * Reads a signed 32-bit/4-byte value from @stream.
447  *
448  * In order to get the correct byte order for this read operation, 
449  * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
450  *
451  * If @cancellable is not %NULL, then the operation can be cancelled by
452  * triggering the cancellable object from another thread. If the operation
453  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
454  *   
455  * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if 
456  * an error occurred. 
457  **/
458 gint32
459 g_data_input_stream_read_int32 (GDataInputStream  *stream,
460                                 GCancellable       *cancellable,
461                                 GError            **error)
462 {
463   gint32 v;
464   
465   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), 0);
466   
467   if (read_data (stream, &v, 4, cancellable, error))
468     {
469       switch (stream->priv->byte_order)
470         {
471         case G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN:
472           v = GINT32_FROM_BE (v);
473           break;
474         case G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN:
475           v = GINT32_FROM_LE (v);
476           break;
477         case G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN:
478         default:
479           break;
480         }
481       return v;
482     }
483   
484   return 0;
485 }
486
487
488 /**
489  * g_data_input_stream_read_uint32:
490  * @stream: a given #GDataInputStream.
491  * @cancellable: optional #GCancellable object, %NULL to ignore.
492  * @error: #GError for error reporting.
493  * 
494  * Reads an unsigned 32-bit/4-byte value from @stream.
495  *
496  * In order to get the correct byte order for this read operation, 
497  * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
498  *
499  * If @cancellable is not %NULL, then the operation can be cancelled by
500  * triggering the cancellable object from another thread. If the operation
501  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
502  * 
503  * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if 
504  * an error occurred. 
505  **/
506 guint32
507 g_data_input_stream_read_uint32 (GDataInputStream  *stream,
508                                  GCancellable       *cancellable,
509                                  GError            **error)
510 {
511   guint32 v;
512   
513   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), 0);
514   
515   if (read_data (stream, &v, 4, cancellable, error))
516     {
517       switch (stream->priv->byte_order)
518         {
519         case G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN:
520           v = GUINT32_FROM_BE (v);
521           break;
522         case G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN:
523           v = GUINT32_FROM_LE (v);
524           break;
525         case G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN:
526         default:
527           break;
528         }
529       return v;
530     }
531   
532   return 0;
533 }
534
535
536 /**
537  * g_data_input_stream_read_int64:
538  * @stream: a given #GDataInputStream.
539  * @cancellable: optional #GCancellable object, %NULL to ignore.
540  * @error: #GError for error reporting.
541  * 
542  * Reads a 64-bit/8-byte value from @stream.
543  *
544  * In order to get the correct byte order for this read operation, 
545  * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
546  *
547  * If @cancellable is not %NULL, then the operation can be cancelled by
548  * triggering the cancellable object from another thread. If the operation
549  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
550  * 
551  * Returns: a signed 64-bit/8-byte value read from @stream or %0 if 
552  * an error occurred.  
553  **/
554 gint64
555 g_data_input_stream_read_int64 (GDataInputStream  *stream,
556                                GCancellable       *cancellable,
557                                GError            **error)
558 {
559   gint64 v;
560   
561   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), 0);
562   
563   if (read_data (stream, &v, 8, cancellable, error))
564     {
565       switch (stream->priv->byte_order)
566         {
567         case G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN:
568           v = GINT64_FROM_BE (v);
569           break;
570         case G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN:
571           v = GINT64_FROM_LE (v);
572           break;
573         case G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN:
574         default:
575           break;
576         }
577       return v;
578     }
579   
580   return 0;
581 }
582
583
584 /**
585  * g_data_input_stream_read_uint64:
586  * @stream: a given #GDataInputStream.
587  * @cancellable: optional #GCancellable object, %NULL to ignore.
588  * @error: #GError for error reporting.
589  * 
590  * Reads an unsigned 64-bit/8-byte value from @stream.
591  *
592  * In order to get the correct byte order for this read operation, 
593  * see g_data_input_stream_get_byte_order().
594  *
595  * If @cancellable is not %NULL, then the operation can be cancelled by
596  * triggering the cancellable object from another thread. If the operation
597  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
598  * 
599  * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if 
600  * an error occurred. 
601  **/
602 guint64
603 g_data_input_stream_read_uint64 (GDataInputStream  *stream,
604                                 GCancellable       *cancellable,
605                                 GError            **error)
606 {
607   guint64 v;
608   
609   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), 0);
610   
611   if (read_data (stream, &v, 8, cancellable, error))
612     {
613       switch (stream->priv->byte_order)
614         {
615         case G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN:
616           v = GUINT64_FROM_BE (v);
617           break;
618         case G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN:
619           v = GUINT64_FROM_LE (v);
620           break;
621         case G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN:
622         default:
623           break;
624         }
625       return v;
626     }
627   
628   return 0;
629 }
630
631 static gssize
632 scan_for_newline (GDataInputStream *stream,
633                   gsize            *checked_out,
634                   gboolean         *last_saw_cr_out,
635                   int              *newline_len_out)
636 {
637   GBufferedInputStream *bstream;
638   GDataInputStreamPrivate *priv;
639   const char *buffer;
640   gsize start, end, peeked;
641   int i;
642   gssize found_pos;
643   int newline_len;
644   gsize available, checked;
645   gboolean last_saw_cr;
646
647   priv = stream->priv;
648   
649   bstream = G_BUFFERED_INPUT_STREAM (stream);
650
651   checked = *checked_out;
652   last_saw_cr = *last_saw_cr_out;
653   found_pos = -1;
654   newline_len = 0;
655   
656   start = checked;
657   buffer = (const char*)g_buffered_input_stream_peek_buffer (bstream, &available) + start;
658   end = available;
659   peeked = end - start;
660
661   for (i = 0; checked < available && i < peeked; i++)
662     {
663       switch (priv->newline_type)
664         {
665         case G_DATA_STREAM_NEWLINE_TYPE_LF:
666           if (buffer[i] == 10)
667             {
668               found_pos = start + i;
669               newline_len = 1;
670             }
671           break;
672         case G_DATA_STREAM_NEWLINE_TYPE_CR:
673           if (buffer[i] == 13)
674             {
675               found_pos = start + i;
676               newline_len = 1;
677             }
678           break;
679         case G_DATA_STREAM_NEWLINE_TYPE_CR_LF:
680           if (last_saw_cr && buffer[i] == 10)
681             {
682               found_pos = start + i - 1;
683               newline_len = 2;
684             }
685           break;
686         default:
687         case G_DATA_STREAM_NEWLINE_TYPE_ANY:
688           if (buffer[i] == 10) /* LF */
689             {
690               if (last_saw_cr)
691                 {
692                   /* CR LF */
693                   found_pos = start + i - 1;
694                   newline_len = 2;
695                 }
696               else
697                 {
698                   /* LF */
699                   found_pos = start + i;
700                   newline_len = 1;
701                 }
702             }
703           else if (last_saw_cr)
704             {
705               /* Last was cr, this is not LF, end is CR */
706               found_pos = start + i - 1;
707               newline_len = 1;
708             }
709           /* Don't check for CR here, instead look at last_saw_cr on next byte */
710           break;
711         }
712         
713       last_saw_cr = (buffer[i] == 13);
714
715       if (found_pos != -1)
716         {
717           *newline_len_out = newline_len;
718           return found_pos;
719         }
720     }
721
722   checked = end;
723
724   *checked_out = checked;
725   *last_saw_cr_out = last_saw_cr;
726   return -1;
727 }
728                   
729
730 /**
731  * g_data_input_stream_read_line:
732  * @stream: a given #GDataInputStream.
733  * @length: a #gsize to get the length of the data read in.
734  * @cancellable: optional #GCancellable object, %NULL to ignore.
735  * @error: #GError for error reporting.
736  *
737  * Reads a line from the data input stream.
738  *
739  * If @cancellable is not %NULL, then the operation can be cancelled by
740  * triggering the cancellable object from another thread. If the operation
741  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
742  *
743  * Returns: a string with the line that was read in (without the newlines).
744  *     Set @length to a #gsize to get the length of the read line.
745  *     On an error, it will return %NULL and @error will be set. If there's no
746  *     content to read, it will still return %NULL, but @error won't be set.
747  **/
748 char *
749 g_data_input_stream_read_line (GDataInputStream  *stream,
750                                gsize             *length,
751                                GCancellable      *cancellable,
752                                GError           **error)
753 {
754   GBufferedInputStream *bstream;
755   gsize checked;
756   gboolean last_saw_cr;
757   gssize found_pos;
758   gssize res;
759   int newline_len;
760   char *line;
761   
762   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), NULL);  
763
764   bstream = G_BUFFERED_INPUT_STREAM (stream);
765
766   newline_len = 0;
767   checked = 0;
768   last_saw_cr = FALSE;
769
770   while ((found_pos = scan_for_newline (stream, &checked, &last_saw_cr, &newline_len)) == -1)
771     {
772       if (g_buffered_input_stream_get_available (bstream) ==
773           g_buffered_input_stream_get_buffer_size (bstream))
774         g_buffered_input_stream_set_buffer_size (bstream,
775                                                  2 * g_buffered_input_stream_get_buffer_size (bstream));
776
777       res = g_buffered_input_stream_fill (bstream, -1, cancellable, error);
778       if (res < 0)
779         return NULL;
780       if (res == 0)
781         {
782           /* End of stream */
783           if (g_buffered_input_stream_get_available (bstream) == 0)
784             {
785               if (length)
786                 *length = 0;
787               return NULL;
788             }
789           else
790             {
791               found_pos = checked;
792               newline_len = 0;
793               break;
794             }
795         }
796     }
797
798   line = g_malloc (found_pos + newline_len + 1);
799
800   res = g_input_stream_read (G_INPUT_STREAM (stream),
801                              line,
802                              found_pos + newline_len,
803                              NULL, NULL);
804   if (length)
805     *length = (gsize)found_pos;
806   g_warn_if_fail (res == found_pos + newline_len);
807   line[found_pos] = 0;
808   
809   return line;
810 }
811
812 static gssize
813 scan_for_chars (GDataInputStream *stream,
814                 gsize            *checked_out,
815                 const char       *stop_chars,
816                 gssize            stop_chars_len)
817 {
818   GBufferedInputStream *bstream;
819   const char *buffer;
820   gsize start, end, peeked;
821   int i;
822   gsize available, checked;
823   const char *stop_char;
824   const char *stop_end;
825
826   bstream = G_BUFFERED_INPUT_STREAM (stream);
827   stop_end = stop_chars + stop_chars_len;
828
829   checked = *checked_out;
830
831   start = checked;
832   buffer = (const char *)g_buffered_input_stream_peek_buffer (bstream, &available) + start;
833   end = available;
834   peeked = end - start;
835
836   for (i = 0; checked < available && i < peeked; i++)
837     {
838       for (stop_char = stop_chars; stop_char != stop_end; stop_char++)
839         {
840           if (buffer[i] == *stop_char)
841             return (start + i);
842         }
843     }
844
845   checked = end;
846
847   *checked_out = checked;
848   return -1;
849 }
850
851 /**
852  * g_data_input_stream_read_until:
853  * @stream: a given #GDataInputStream.
854  * @stop_chars: characters to terminate the read.
855  * @length: a #gsize to get the length of the data read in.
856  * @cancellable: optional #GCancellable object, %NULL to ignore.
857  * @error: #GError for error reporting.
858  *
859  * Reads a string from the data input stream, up to the first
860  * occurrence of any of the stop characters.
861  *
862  * Note that, in contrast to g_data_input_stream_read_until_async(),
863  * this function consumes the stop character that it finds.
864  *
865  * Don't use this function in new code.  Its functionality is
866  * inconsistent with g_data_input_stream_read_until_async().  Both
867  * functions will be marked as deprecated in a future release.  Use
868  * g_data_input_stream_read_upto() instead, but note that that function
869  * does not consume the stop character.
870  *
871  * Returns: a string with the data that was read before encountering
872  *     any of the stop characters. Set @length to a #gsize to get the length
873  *     of the string. This function will return %NULL on an error.
874  */
875 char *
876 g_data_input_stream_read_until (GDataInputStream  *stream,
877                                const gchar        *stop_chars,
878                                gsize              *length,
879                                GCancellable       *cancellable,
880                                GError            **error)
881 {
882   GBufferedInputStream *bstream;
883   gchar *result;
884
885   bstream = G_BUFFERED_INPUT_STREAM (stream);
886
887   result = g_data_input_stream_read_upto (stream, stop_chars, -1,
888                                           length, cancellable, error);
889
890   /* If we're not at end of stream then we have a stop_char to consume. */
891   if (result != NULL && g_buffered_input_stream_get_available (bstream) > 0)
892     {
893       gsize res;
894       gchar b;
895
896       res = g_input_stream_read (G_INPUT_STREAM (stream), &b, 1, NULL, NULL);
897       g_assert (res == 1);
898     }
899
900   return result;
901 }
902
903 typedef struct
904 {
905   GDataInputStream *stream;
906   GSimpleAsyncResult *simple;
907   gboolean last_saw_cr;
908   gsize checked;
909   gint io_priority;
910   GCancellable *cancellable;
911
912   gchar *stop_chars;
913   gssize stop_chars_len;
914   gchar *line;
915   gsize length;
916 } GDataInputStreamReadData;
917
918 static void
919 g_data_input_stream_read_complete (GDataInputStreamReadData *data,
920                                    gsize                     read_length,
921                                    gsize                     skip_length,
922                                    gboolean                  need_idle_dispatch)
923 {
924   if (read_length || skip_length)
925     {
926       gssize bytes;
927
928       data->length = read_length;
929       data->line = g_malloc (read_length + 1);
930       data->line[read_length] = '\0';
931
932       /* we already checked the buffer.  this shouldn't fail. */
933       bytes = g_input_stream_read (G_INPUT_STREAM (data->stream),
934                                    data->line, read_length, NULL, NULL);
935       g_assert_cmpint (bytes, ==, read_length);
936
937       bytes = g_input_stream_skip (G_INPUT_STREAM (data->stream),
938                                    skip_length, NULL, NULL);
939       g_assert_cmpint (bytes, ==, skip_length);
940     }
941
942   if (need_idle_dispatch)
943     g_simple_async_result_complete_in_idle (data->simple);
944   else
945     g_simple_async_result_complete (data->simple);
946
947   g_object_unref (data->simple);
948 }
949
950 static void
951 g_data_input_stream_read_line_ready (GObject      *object,
952                                      GAsyncResult *result,
953                                      gpointer      user_data)
954 {
955   GDataInputStreamReadData *data = user_data;
956   gssize found_pos;
957   gint newline_len;
958
959   if (result)
960     /* this is a callback.  finish the async call. */
961     {
962       GBufferedInputStream *buffer = G_BUFFERED_INPUT_STREAM (data->stream);
963       GError *error = NULL;
964       gssize bytes;
965
966       bytes = g_buffered_input_stream_fill_finish (buffer, result, &error);
967
968       if (bytes <= 0)
969         {
970           if (bytes < 0)
971             /* stream error. */
972             {
973               g_simple_async_result_set_from_error (data->simple, error);
974               g_error_free (error);
975               data->checked = 0;
976             }
977
978           g_data_input_stream_read_complete (data, data->checked, 0, FALSE);
979           return;
980         }
981
982       /* only proceed if we got more bytes... */
983     }
984
985   if (data->stop_chars)
986     {
987       found_pos = scan_for_chars (data->stream,
988                                   &data->checked,
989                                   data->stop_chars,
990                                   data->stop_chars_len);
991       newline_len = 0;
992     }
993   else
994     found_pos = scan_for_newline (data->stream, &data->checked,
995                                   &data->last_saw_cr, &newline_len);
996
997   if (found_pos == -1)
998     /* didn't find a full line; need to buffer some more bytes */
999     {
1000       GBufferedInputStream *buffer = G_BUFFERED_INPUT_STREAM (data->stream);
1001       gsize size;
1002
1003       size = g_buffered_input_stream_get_buffer_size (buffer);
1004
1005       if (g_buffered_input_stream_get_available (buffer) == size)
1006         /* need to grow the buffer */
1007         g_buffered_input_stream_set_buffer_size (buffer, size * 2);
1008
1009       /* try again */
1010       g_buffered_input_stream_fill_async (buffer, -1, data->io_priority,
1011                                           data->cancellable,
1012                                           g_data_input_stream_read_line_ready,
1013                                           user_data);
1014     }
1015   else
1016     {
1017       /* read the line and the EOL.  no error is possible. */
1018       g_data_input_stream_read_complete (data, found_pos,
1019                                          newline_len, result == NULL);
1020     }
1021 }
1022
1023 static void
1024 g_data_input_stream_read_data_free (gpointer user_data)
1025 {
1026   GDataInputStreamReadData *data = user_data;
1027
1028   /* we don't hold a ref to ->simple because it keeps a ref to us.
1029    * we are called because it is being finalized.
1030    */
1031
1032   g_free (data->stop_chars);
1033   if (data->cancellable)
1034     g_object_unref (data->cancellable);
1035   g_free (data->line);
1036   g_slice_free (GDataInputStreamReadData, data);
1037 }
1038
1039 static void
1040 g_data_input_stream_read_async (GDataInputStream    *stream,
1041                                 const gchar         *stop_chars,
1042                                 gssize               stop_chars_len,
1043                                 gint                 io_priority,
1044                                 GCancellable        *cancellable,
1045                                 GAsyncReadyCallback  callback,
1046                                 gpointer             user_data,
1047                                 gpointer             source_tag)
1048 {
1049   GDataInputStreamReadData *data;
1050
1051   data = g_slice_new (GDataInputStreamReadData);
1052   data->stream = stream;
1053   if (cancellable)
1054     g_object_ref (cancellable);
1055   data->cancellable = cancellable;
1056   if (stop_chars_len == -1)
1057     stop_chars_len = strlen (stop_chars);
1058   data->stop_chars = g_memdup (stop_chars, stop_chars_len);
1059   data->stop_chars_len = stop_chars_len;
1060   data->io_priority = io_priority;
1061   data->last_saw_cr = FALSE;
1062   data->checked = 0;
1063   data->line = NULL;
1064
1065   data->simple = g_simple_async_result_new (G_OBJECT (stream), callback,
1066                                             user_data, source_tag);
1067   g_simple_async_result_set_op_res_gpointer (data->simple, data,
1068                                              g_data_input_stream_read_data_free);
1069   g_data_input_stream_read_line_ready (NULL, NULL, data);
1070 }
1071
1072 static gchar *
1073 g_data_input_stream_read_finish (GDataInputStream  *stream,
1074                                  GAsyncResult      *result,
1075                                  gsize             *length,
1076                                  GError           **error)
1077 {
1078   GDataInputStreamReadData *data;
1079   GSimpleAsyncResult *simple;
1080   gchar *line;
1081
1082   simple = G_SIMPLE_ASYNC_RESULT (result);
1083
1084   if (g_simple_async_result_propagate_error (simple, error))
1085     return NULL;
1086
1087   data = g_simple_async_result_get_op_res_gpointer (simple);
1088
1089   line = data->line;
1090   data->line = NULL;
1091
1092   if (length && line)
1093     *length = data->length;
1094
1095   return line;
1096 }
1097
1098 /**
1099  * g_data_input_stream_read_line_async:
1100  * @stream: a given #GDataInputStream.
1101  * @io_priority: the <link linkend="io-priority">I/O priority</link>
1102  *     of the request.
1103  * @cancellable: optional #GCancellable object, %NULL to ignore.
1104  * @callback: callback to call when the request is satisfied.
1105  * @user_data: the data to pass to callback function.
1106  *
1107  * The asynchronous version of g_data_input_stream_read_line().  It is
1108  * an error to have two outstanding calls to this function.
1109  *
1110  * When the operation is finished, @callback will be called. You
1111  * can then call g_data_input_stream_read_line_finish() to get
1112  * the result of the operation.
1113  *
1114  * Since: 2.20
1115  */
1116 void
1117 g_data_input_stream_read_line_async (GDataInputStream    *stream,
1118                                      gint                 io_priority,
1119                                      GCancellable        *cancellable,
1120                                      GAsyncReadyCallback  callback,
1121                                      gpointer             user_data)
1122 {
1123   g_return_if_fail (G_IS_DATA_INPUT_STREAM (stream));
1124   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
1125
1126   g_data_input_stream_read_async (stream, NULL, 0, io_priority,
1127                                   cancellable, callback, user_data,
1128                                   g_data_input_stream_read_line_async);
1129 }
1130
1131 /**
1132  * g_data_input_stream_read_until_async:
1133  * @stream: a given #GDataInputStream.
1134  * @stop_chars: characters to terminate the read.
1135  * @io_priority: the <link linkend="io-priority">I/O priority</link>
1136  *     of the request.
1137  * @cancellable: optional #GCancellable object, %NULL to ignore.
1138  * @callback: callback to call when the request is satisfied.
1139  * @user_data: the data to pass to callback function.
1140  *
1141  * The asynchronous version of g_data_input_stream_read_until().
1142  * It is an error to have two outstanding calls to this function.
1143  *
1144  * Note that, in contrast to g_data_input_stream_read_until(),
1145  * this function does not consume the stop character that it finds.  You
1146  * must read it for yourself.
1147  *
1148  * When the operation is finished, @callback will be called. You
1149  * can then call g_data_input_stream_read_until_finish() to get
1150  * the result of the operation.
1151  *
1152  * Don't use this function in new code.  Its functionality is
1153  * inconsistent with g_data_input_stream_read_until().  Both functions
1154  * will be marked as deprecated in a future release.  Use
1155  * g_data_input_stream_read_upto_async() instead.
1156  *
1157  * Since: 2.20
1158  */
1159 void
1160 g_data_input_stream_read_until_async (GDataInputStream    *stream,
1161                                       const gchar         *stop_chars,
1162                                       gint                 io_priority,
1163                                       GCancellable        *cancellable,
1164                                       GAsyncReadyCallback  callback,
1165                                       gpointer             user_data)
1166 {
1167   g_return_if_fail (G_IS_DATA_INPUT_STREAM (stream));
1168   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
1169   g_return_if_fail (stop_chars != NULL);
1170
1171   g_data_input_stream_read_async (stream, stop_chars, -1, io_priority,
1172                                   cancellable, callback, user_data,
1173                                   g_data_input_stream_read_until_async);
1174 }
1175
1176 /**
1177  * g_data_input_stream_read_line_finish:
1178  * @stream: a given #GDataInputStream.
1179  * @result: the #GAsyncResult that was provided to the callback.
1180  * @length: a #gsize to get the length of the data read in.
1181  * @error: #GError for error reporting.
1182  *
1183  * Finish an asynchronous call started by
1184  * g_data_input_stream_read_line_async().
1185  *
1186  * Returns: a string with the line that was read in (without the newlines).
1187  *     Set @length to a #gsize to get the length of the read line.
1188  *     On an error, it will return %NULL and @error will be set. If there's no
1189  *     content to read, it will still return %NULL, but @error won't be set.
1190  *
1191  * Since: 2.20
1192  */
1193 gchar *
1194 g_data_input_stream_read_line_finish (GDataInputStream  *stream,
1195                                       GAsyncResult      *result,
1196                                       gsize             *length,
1197                                       GError           **error)
1198 {
1199   g_return_val_if_fail (
1200     g_simple_async_result_is_valid (result, G_OBJECT (stream),
1201       g_data_input_stream_read_line_async), NULL);
1202
1203   return g_data_input_stream_read_finish (stream, result, length, error);
1204 }
1205
1206 /**
1207  * g_data_input_stream_read_until_finish:
1208  * @stream: a given #GDataInputStream.
1209  * @result: the #GAsyncResult that was provided to the callback.
1210  * @length: a #gsize to get the length of the data read in.
1211  * @error: #GError for error reporting.
1212  *
1213  * Finish an asynchronous call started by
1214  * g_data_input_stream_read_until_async().
1215  *
1216  * Since: 2.20
1217  *
1218  * Returns: a string with the data that was read before encountering
1219  *     any of the stop characters. Set @length to a #gsize to get the length
1220  *     of the string. This function will return %NULL on an error.
1221  */
1222 gchar *
1223 g_data_input_stream_read_until_finish (GDataInputStream  *stream,
1224                                        GAsyncResult      *result,
1225                                        gsize             *length,
1226                                        GError           **error)
1227 {
1228   g_return_val_if_fail (
1229     g_simple_async_result_is_valid (result, G_OBJECT (stream),
1230       g_data_input_stream_read_until_async), NULL);
1231
1232   return g_data_input_stream_read_finish (stream, result, length, error);
1233 }
1234
1235 /**
1236  * g_data_input_stream_read_upto:
1237  * @stream: a #GDataInputStream
1238  * @stop_chars: characters to terminate the read
1239  * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
1240  *     nul-terminated
1241  * @length: a #gsize to get the length of the data read in
1242  * @cancellable: optional #GCancellable object, %NULL to ignore
1243  * @error: #GError for error reporting
1244  *
1245  * Reads a string from the data input stream, up to the first
1246  * occurrence of any of the stop characters.
1247  *
1248  * In contrast to g_data_input_stream_read_until(), this function
1249  * does <emphasis>not</emphasis> consume the stop character. You have
1250  * to use g_data_input_stream_read_byte() to get it before calling
1251  * g_data_input_stream_read_upto() again.
1252  *
1253  * Note that @stop_chars may contain '\0' if @stop_chars_len is
1254  * specified.
1255  *
1256  * Returns: a string with the data that was read before encountering
1257  *     any of the stop characters. Set @length to a #gsize to get the length
1258  *     of the string. This function will return %NULL on an error
1259  *
1260  * Since: 2.24
1261  */
1262 char *
1263 g_data_input_stream_read_upto (GDataInputStream  *stream,
1264                                const gchar       *stop_chars,
1265                                gssize             stop_chars_len,
1266                                gsize             *length,
1267                                GCancellable      *cancellable,
1268                                GError           **error)
1269 {
1270   GBufferedInputStream *bstream;
1271   gsize checked;
1272   gssize found_pos;
1273   gssize res;
1274   char *data_until;
1275
1276   g_return_val_if_fail (G_IS_DATA_INPUT_STREAM (stream), NULL);
1277
1278   if (stop_chars_len < 0)
1279     stop_chars_len = strlen (stop_chars);
1280
1281   bstream = G_BUFFERED_INPUT_STREAM (stream);
1282
1283   checked = 0;
1284
1285   while ((found_pos = scan_for_chars (stream, &checked, stop_chars, stop_chars_len)) == -1)
1286     {
1287       if (g_buffered_input_stream_get_available (bstream) ==
1288           g_buffered_input_stream_get_buffer_size (bstream))
1289         g_buffered_input_stream_set_buffer_size (bstream,
1290                                                  2 * g_buffered_input_stream_get_buffer_size (bstream));
1291
1292       res = g_buffered_input_stream_fill (bstream, -1, cancellable, error);
1293       if (res < 0)
1294         return NULL;
1295       if (res == 0)
1296         {
1297           /* End of stream */
1298           if (g_buffered_input_stream_get_available (bstream) == 0)
1299             {
1300               if (length)
1301                 *length = 0;
1302               return NULL;
1303             }
1304           else
1305             {
1306               found_pos = checked;
1307               break;
1308             }
1309         }
1310     }
1311
1312   data_until = g_malloc (found_pos + 1);
1313
1314   res = g_input_stream_read (G_INPUT_STREAM (stream),
1315                              data_until,
1316                              found_pos,
1317                              NULL, NULL);
1318   if (length)
1319     *length = (gsize)found_pos;
1320   g_warn_if_fail (res == found_pos);
1321   data_until[found_pos] = 0;
1322
1323   return data_until;
1324 }
1325
1326 /**
1327  * g_data_input_stream_read_upto_async:
1328  * @stream: a #GDataInputStream
1329  * @stop_chars: characters to terminate the read
1330  * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is
1331  *     nul-terminated
1332  * @cancellable: optional #GCancellable object, %NULL to ignore
1333  * @callback: callback to call when the request is satisfied
1334  * @user_data: the data to pass to callback function
1335  *
1336  * The asynchronous version of g_data_input_stream_read_upto().
1337  * It is an error to have two outstanding calls to this function.
1338  *
1339  * In contrast to g_data_input_stream_read_until(), this function
1340  * does <emphasis>not</emphasis> consume the stop character. You have
1341  * to use g_data_input_stream_read_byte() to get it before calling
1342  * g_data_input_stream_read_upto() again.
1343  *
1344  * Note that @stop_chars may contain '\0' if @stop_chars_len is
1345  * specified.
1346  *
1347  * When the operation is finished, @callback will be called. You
1348  * can then call g_data_input_stream_read_upto_finish() to get
1349  * the result of the operation.
1350  *
1351  * Since: 2.24
1352  */
1353 void
1354 g_data_input_stream_read_upto_async (GDataInputStream    *stream,
1355                                      const gchar         *stop_chars,
1356                                      gssize               stop_chars_len,
1357                                      gint                 io_priority,
1358                                      GCancellable        *cancellable,
1359                                      GAsyncReadyCallback  callback,
1360                                      gpointer             user_data)
1361 {
1362   g_return_if_fail (G_IS_DATA_INPUT_STREAM (stream));
1363   g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
1364   g_return_if_fail (stop_chars != NULL);
1365
1366   g_data_input_stream_read_async (stream, stop_chars, stop_chars_len, io_priority,
1367                                   cancellable, callback, user_data,
1368                                   g_data_input_stream_read_upto_async);
1369 }
1370
1371 /**
1372  * g_data_input_stream_read_upto_finish:
1373  * @stream: a #GDataInputStream
1374  * @result: the #GAsyncResult that was provided to the callback
1375  * @length: a #gsize to get the length of the data read in
1376  * @error: #GError for error reporting
1377  *
1378  * Finish an asynchronous call started by
1379  * g_data_input_stream_read_upto_async().
1380  *
1381  * Note that this function does <emphasis>not</emphasis> consume the
1382  * stop character. You have to use g_data_input_stream_read_byte() to
1383  * get it before calling g_data_input_stream_read_upto_async() again.
1384  *
1385  * Returns: a string with the data that was read before encountering
1386  *     any of the stop characters. Set @length to a #gsize to get the length
1387  *     of the string. This function will return %NULL on an error.
1388  *
1389  * Since: 2.24
1390  */
1391 gchar *
1392 g_data_input_stream_read_upto_finish (GDataInputStream  *stream,
1393                                       GAsyncResult      *result,
1394                                       gsize             *length,
1395                                       GError           **error)
1396 {
1397   g_return_val_if_fail (
1398     g_simple_async_result_is_valid (result, G_OBJECT (stream),
1399       g_data_input_stream_read_upto_async), NULL);
1400
1401   return g_data_input_stream_read_finish (stream, result, length, error);
1402 }