Input from unstructured files

## Input from unstructured files Input from unstructured files |

## Synopsis

                        GsfInput;
    guint8 const *      gsf_input_read                      (GsfInput *input,
                                                             size_t num_bytes,
                                                             guint8 *optional_buffer);
    gsf_off_t           gsf_input_tell                      (GsfInput *input);
    gboolean            gsf_input_seek                      (GsfInput *input,
                                                             gsf_off_t offset,
                                                             GSeekType whence);
    GsfInfile *         gsf_input_container                 (GsfInput *input);
    GsfInput *          gsf_input_dup                       (GsfInput *input,
                                                             GError **err);
    gsf_off_t           gsf_input_size                      (GsfInput *input);
    gboolean            gsf_input_eof                       (GsfInput *input);
    gsf_off_t           gsf_input_remaining                 (GsfInput *input);
    GQuark              gsf_input_error_id                  (void);
    GsfInput *          gsf_input_sibling                   (GsfInput const *input,
                                                             char const *name,
                                                             GError **err);
    GQuark              gsf_input_error                     (void);
    char const   *      gsf_input_name                      (GsfInput *input);
    gboolean            gsf_input_set_name_from_filename    (GsfInput *input,
                                                             char const *filename);

                        GsfInputProxy;
    GsfInput *          gsf_input_proxy_new                 (GsfInput *source);
    GsfInput *          gsf_input_proxy_new_section         (GsfInput *source,
                                                             gsf_off_t offset,
                                                             gsf_off_t size);

    gboolean            gsf_input_copy                      (GsfInput *input,
                                                             GsfOutput *output);
    GsfInput *          gsf_input_uncompress                (GsfInput *src);

## Object Hierarchy

      GObject
       +----GsfInput
             +----GsfInfile
             +----GsfInputGZip
             +----GsfInputMemory
             +----GsfInputProxy
             +----GsfInputStdio
             +----GsfInputTextline

      GObject
       +----GsfInput
             +----GsfInputProxy

## Properties

      "container"                GsfInfile*            : Read
      "eof"                      gboolean              : Read
      "modtime"                  GDateTime*            : Read
      "name"                     gchar*                : Read
      "position"                 gint64                : Read
      "remaining"                gint64                : Read
      "size"                     gint64                : Read

## Description

## Details

### GsfInput

    typedef struct _GsfInput GsfInput;

Class representing an input stream.

### gsf_input_read ()

    guint8 const *      gsf_input_read                      (GsfInput *input,
                                                             size_t num_bytes,
                                                             guint8 *optional_buffer);

Read at least `num_bytes`. Does not change the current position if there is an error. Will only read if the entire amount can be read. Invalidates the buffer associated with previous calls to gsf_input_read.

`input` : | the input stream
`num_bytes` : | number of bytes to read
`optional_buffer` : | Pointer to destination memory area
Returns : | pointer to the buffer or `NULL` if there is an error or 0 bytes are requested.

### gsf_input_tell ()

    gsf_off_t           gsf_input_tell                      (GsfInput *input);

`input` : | the input stream
Returns : | the current offset in the file.

### gsf_input_seek ()

    gboolean            gsf_input_seek                      (GsfInput *input,
                                                             gsf_off_t offset,
                                                             GSeekType whence);

Move the current location in the input stream.

`input` : | the input stream
`offset` : | target offset
`whence` : | determines whether the offset is relative to the beginning or the end of the stream, or to the current location.
Returns : | `TRUE` on error.

### gsf_input_container ()

    GsfInfile *         gsf_input_container                 (GsfInput *input);

`input` : | the input stream
Returns : | `input`'s container, potentially `NULL`. [transfer none]

### gsf_input_dup ()

    GsfInput *          gsf_input_dup                       (GsfInput *input,
                                                             GError **err);

Duplicates input `src` leaving the new one at the same offset.

`input` : | The input to duplicate
`err` : | place to store a GError if anything goes wrong. [allow-none]
Returns : | the duplicate, or `NULL` on error. [transfer full]

### gsf_input_size ()

    gsf_off_t           gsf_input_size                      (GsfInput *input);

`input` : | The input
Returns : | the total number of bytes in the input or -1 on error

### gsf_input_eof ()

    gboolean            gsf_input_eof                       (GsfInput *input);

Are we at the end of the file?

`input` : | the input
Returns : | `TRUE` if the input is at the eof.

### gsf_input_remaining ()

    gsf_off_t           gsf_input_remaining                 (GsfInput *input);

`input` : | the input stream
Returns : | the number of bytes left in the file.

### gsf_input_error_id ()

    GQuark              gsf_input_error_id                  (void);

Returns : | A utility quark to flag a GError as being an input problem.

### gsf_input_sibling ()

    GsfInput *          gsf_input_sibling                   (GsfInput const *input,
                                                             char const *name,
                                                             GError **err);

UNIMPLEMENTED BY ANY BACKEND and it is probably unnecessary. gsf_input_get_container provides enough power to do what is necessary.

Attempts to open a 'sibling' of `input`. The caller is responsible for managing the resulting object.

`input` : | The input
`name` : | name.
`err` : | place to store a GError if anything goes wrong. [allow-none]
Returns : | A related GsfInput or `NULL` on failure. [transfer full]

### gsf_input_error ()

    GQuark              gsf_input_error                     (void);

### Warning

`gsf_input_error` is deprecated and should not be used in newly-written code.

Deprecated as of GSF 1.12.0; use `gsf_input_error_id()` instead.

Returns : | A utility quark to flag a GError as being an input problem.

### gsf_input_name ()

    char const   *      gsf_input_name                      (GsfInput *input);

The name of the input stream.

`input` : | the input stream
Returns : | `input`'s name in utf8 form, or `NULL` if it has no name. [transfer none]

### gsf_input_set_name_from_filename ()

    gboolean            gsf_input_set_name_from_filename    (GsfInput *input,
                                                             char const *filename);

protected.

`input` : | the input stream
`filename` : | the (fs-sys encoded) filename
Returns : | `TRUE` if the assignment was ok.

### GsfInputProxy

    typedef struct _GsfInputProxy GsfInputProxy;

### gsf_input_proxy_new ()

    GsfInput *          gsf_input_proxy_new                 (GsfInput *source);

This creates a new proxy to the entire, given input source. See gsf_input_proxy_new_section for details.

`source` : | The underlying data source.
Returns : | a new input object.

### gsf_input_proxy_new_section ()

    GsfInput *          gsf_input_proxy_new_section         (GsfInput *source,
                                                             gsf_off_t offset,
                                                             gsf_off_t size);

This creates a new proxy to a section of the given source. The new object will have its own current position, but any operation on it can change the source's position.

If a proxy to a proxy is created, the intermediate proxy is short- circuited.

This function will ref the source.

`source` : | The underlying data source.
`offset` : | Offset into source for start of section.
`size` : | Length of section.
Returns : | a new input object.

### gsf_input_copy ()

    gboolean            gsf_input_copy                      (GsfInput *input,
                                                             GsfOutput *output);

Copy the contents from `input` to `output` from their respective current positions. So if you want to be sure to copy *everything*, make sure to call gsf_input_seek (input, 0, G_SEEK_SET) and gsf_output_seek (output, 0, G_SEEK_SET) first, if applicable.

`input` : | a non-null GsfInput
`output` : | a non-null GsfOutput
Returns : | `TRUE` on success

### gsf_input_uncompress ()

    GsfInput *          gsf_input_uncompress                (GsfInput *src);

This functions takes ownership of the incoming reference and yields a new one as its output.

`src` : | stream to be uncompressed. [transfer full]
Returns : | A stream equivalent to the source stream, but uncompressed if the source was compressed. [transfer full]

## Property Details

### The `"container"` property

      "container"                GsfInfile*            : Read

The container, optionally `NULL`, in which this input lives.

### The `"eof"` property

      "eof"                      gboolean              : Read

`TRUE` if the end of the file has been reached.

Default value: FALSE

### The `"modtime"` property

      "modtime"                  GDateTime*            : Read

The time the input was last updated. This represents the timestamp from the originating file or `GsfInfile` member. It is not supported by all derived classes.

### The `"name"` property

      "name"                     gchar*                : Read

The input's name.

Default value: NULL

### The `"position"` property

      "position"                 gint64                : Read

The current position in the input.

Allowed values: >= 0

Default value: 0

### The `"remaining"` property

      "remaining"                gint64                : Read

The number of bytes remaining in the file.

Allowed values: >= 0

Default value: 0

### The `"size"` property

      "size"                     gint64                : Read

The total number of bytes in the file.

Allowed values: >= 0

Default value: 0