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