GSF Reference Manual: Input from unstructured files

## Input from unstructured files Input from unstructured files |

## Functions

guint8 const * | gsf_input_read ()
gsf_off_t | gsf_input_tell ()
gboolean | gsf_input_seek ()
GsfInfile * | gsf_input_container ()
GsfInput * | gsf_input_dup ()
gsf_off_t | gsf_input_size ()
gboolean | gsf_input_eof ()
gsf_off_t | gsf_input_remaining ()
GQuark | gsf_input_error_id ()
GsfInput * | gsf_input_sibling ()
GQuark | gsf_input_error ()
char const * | gsf_input_name ()
gboolean | gsf_input_set_name_from_filename ()
GsfInput * | gsf_input_proxy_new ()
GsfInput * | gsf_input_proxy_new_section ()
gboolean | gsf_input_copy ()
GsfInput * | gsf_input_uncompress ()

## Properties

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

## Types and Values

| GsfInput
| GsfInputProxy

## Object Hierarchy

        GObject
        ├── GsfInput
        │   ╰── GsfInputProxy
        ╰── GsfInput
            ├── GsfInfile
            ├── GsfInputGZip
            ├── GsfInputMemory
            ├── GsfInputProxy
            ├── GsfInputStdio
            ╰── GsfInputTextline

## Description

## Functions

### 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.

#### Parameters

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);

#### Parameters

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.

#### Parameters

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);

#### Parameters

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.

#### Parameters

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);

#### Parameters

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?

#### Parameters

input | the input |

#### Returns

`TRUE` if the input is at the eof.

### gsf_input_remaining ()

    gsf_off_t
    gsf_input_remaining (GsfInput *input);

#### Parameters

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.

#### Parameters

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);

`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.

#### Parameters

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.

#### Parameters

input | the input stream |
filename | the (fs-sys encoded) filename |

#### Returns

`TRUE` if the assignment was ok.

### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

src | stream to be uncompressed. | [transfer full]

#### Returns

A stream equivalent to the source stream, but uncompressed if the source was compressed.

[transfer full]

## Types and Values

### GsfInput

    typedef struct _GsfInput GsfInput;

Class representing an input stream.

### GsfInputProxy

    typedef struct _GsfInputProxy GsfInputProxy;

## Property Details

### The `“container”` property

      “container”                GsfInfile *

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

Flags: Read

### The `“eof”` property

      “eof”                      gboolean

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

Flags: Read

Default value: FALSE

### The `“modtime”` property

      “modtime”                  GDateTime *

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.

Flags: Read

### The `“name”` property

      “name”                     gchar *

The input's name.

Flags: Read

Default value: NULL

### The `“position”` property

      “position”                 gint64

The current position in the input.

Flags: Read

Allowed values: >= 0

Default value: 0

### The `“remaining”` property

      “remaining”                gint64

The number of bytes remaining in the file.

Flags: Read

Allowed values: >= 0

Default value: 0

### The `“size”` property

      “size”                     gint64

The total number of bytes in the file.

Flags: Read

Allowed values: >= 0

Default value: 0