VipsConnection: libvips Reference Manual

## VipsConnection VipsConnection — a source/sink of bytes, perhaps a network socket |

## Stability Level

Stable, unless otherwise indicated

## Functions

const char * | vips_connection_filename ()
const char * | vips_connection_nick ()
void | vips_pipe_read_limit_set ()
VipsSource * | vips_source_new_from_descriptor ()
VipsSource * | vips_source_new_from_file ()
VipsSource * | vips_source_new_from_blob ()
VipsSource * | vips_source_new_from_target ()
VipsSource * | vips_source_new_from_memory ()
VipsSource * | vips_source_new_from_options ()
void | vips_source_minimise ()
int | vips_source_unminimise ()
int | vips_source_decode ()
gint64 | vips_source_read ()
gboolean | vips_source_is_mappable ()
gboolean | vips_source_is_file ()
const void * | vips_source_map ()
VipsBlob * | vips_source_map_blob ()
gint64 | vips_source_seek ()
int | vips_source_rewind ()
gint64 | vips_source_sniff_at_most ()
unsigned char * | vips_source_sniff ()
gint64 | vips_source_length ()
VipsSourceCustom * | vips_source_custom_new ()
GInputStream * | vips_g_input_stream_new_from_source ()
VipsSourceGInputStream * | vips_source_g_input_stream_new ()
VipsTarget * | vips_target_new_to_descriptor ()
VipsTarget * | vips_target_new_to_file ()
VipsTarget * | vips_target_new_to_memory ()
VipsTarget * | vips_target_new_temp ()
int | vips_target_write ()
gint64 | vips_target_read ()
off_t | vips_target_seek ()
int | vips_target_end ()
void | vips_target_finish ()
unsigned char * | vips_target_steal ()
char * | vips_target_steal_text ()
int | vips_target_putc ()
#define | VIPS_TARGET_PUTC()
int | vips_target_writes ()
int | vips_target_writef ()
int | vips_target_write_amp ()
VipsTargetCustom * | vips_target_custom_new ()

## Properties

int | descriptor | Read / Write
char * | filename | Read / Write
VipsBlob * | blob | Read / Write
VipsBlob * | blob | Read / Write
gboolean | memory | Read / Write

## Signals

gint64 | read | Action
gint64 | seek | Action
int | end | Action
void | finish | Action
gint64 | read | Action
gint64 | seek | Action
gint64 | write | Action

## Types and Values

| VipsSourceGInputStream
| VipsSourceGInputStreamClass
#define | VIPS_TARGET_BUFFER_SIZE
#define | VIPS_TARGET_CUSTOM_BUFFER_SIZE

## Object Hierarchy

        GObject
        ├── GInputStream
        │   ╰── VipsGInputStream
        ╰── VipsObject
            ╰── VipsConnection
                ├── VipsSource
                │   ╰── VipsSourceCustom
                ╰── VipsTarget
                    ╰── VipsTargetCustom

## Includes

    #include <vips/vips.h>

## Description

A VipsConnection is a source or sink of bytes for something like jpeg loading, see for example `vips_jpegload_source()`.

It can be connected to a network socket, for example, or perhaps a node.js stream, or to an area of memory.

Subclass to add other input sources. Use VipsSourceCustom and VipsTargetCustom to make a source or target with action signals for ::read, ::write and ::seek.

## Functions

### vips_connection_filename ()

    const char *
    vips_connection_filename (VipsConnection *connection);

#### Parameters

connection | connection to operate on |

#### Returns

any filename associated with this connection, or NULL.

### vips_connection_nick ()

    const char *
    vips_connection_nick (VipsConnection *connection);

#### Parameters

connection | connection to operate on |

#### Returns

a string describing this connection which could be displayed to a user.

### vips_pipe_read_limit_set ()

    void
    vips_pipe_read_limit_set (gint64 limit);

If a source does not support mmap or seek and the source is used with a loader that can only work from memory, then the data will be automatically read into memory to EOF before the loader starts. This can produce high memory use if the descriptor represents a large object.

Use `vips_pipe_read_limit_set()` to limit the size of object that will be read in this way. The default is 1GB.

Set a value of -1 to mean no limit.

See also: `--vips-pipe-read-limit` and the environment variable `VIPS_PIPE_READ_LIMIT`.

#### Parameters

limit | maximum number of bytes to buffer from a pipe |

### vips_source_new_from_descriptor ()

    VipsSource *
    vips_source_new_from_descriptor (int descriptor);

Create an source attached to a file descriptor. `descriptor` is closed with `close()` when source is finalized.

#### Parameters

descriptor | read from this file descriptor |

#### Returns

a new source.

### vips_source_new_from_file ()

    VipsSource *
    vips_source_new_from_file (const char *filename);

Create an source attached to a file.

If this descriptor does not support mmap and the source is used with a loader that can only work from memory, then the data will be automatically read into memory to EOF before the loader starts. This can produce high memory use if the descriptor represents a large object.

Use `vips_pipe_read_limit_set()` to limit the size of object that will be read in this way. The default is 1GB.

#### Parameters

descriptor | read from this filename |

#### Returns

a new source.

### vips_source_new_from_blob ()

    VipsSource *
    vips_source_new_from_blob (VipsBlob *blob);

Create a source attached to an area of memory.

#### Parameters

blob | memory area to load |

#### Returns

a new source.

### vips_source_new_from_target ()

    VipsSource *
    vips_source_new_from_target (VipsTarget *target);

Create a source from a temp target that has been written to.

#### Parameters

target | build the source from this target |

#### Returns

a new source.

### vips_source_new_from_memory ()

    VipsSource *
    vips_source_new_from_memory (const void *data,
                                 size_t size);

Create a source attached to an area of memory.

You must not free `data` while the source is active.

#### Parameters

data | memory area to load |
length | size of memory area |

#### Returns

a new source.

### vips_source_new_from_options ()

    VipsSource *
    vips_source_new_from_options (const char *options);

Create a source from an option string.

#### Parameters

options | option string |

#### Returns

a new source.

### vips_source_minimise ()

    void
    vips_source_minimise (VipsSource *source);

Minimise the source. As many resources as can be safely removed are removed. Use `vips_source_unminimise()` to restore the source if you wish to use it again.

Loaders should call this in response to the minimise signal on their output image.

#### Parameters

source | source to operate on |

### vips_source_unminimise ()

    int
    vips_source_unminimise (VipsSource *source);

Restore the source after minimisation. This is called at the start of every source method, so loaders should not usually need this.

See also: `vips_source_minimise()`.

#### Parameters

source | source to operate on |

#### Returns

0 on success, or -1 on error.

### vips_source_decode ()

    int
    vips_source_decode (VipsSource *source);

Signal the end of header read and the start of the pixel decode phase. After this, you can no longer seek on this source.

Loaders should call this at the end of header read.

See also: `vips_source_unminimise()`.

#### Parameters

source | source to operate on |

#### Returns

0 on success, -1 on error.

### vips_source_read ()

    gint64
    vips_source_read (VipsSource *source,
                      void *data,
                      size_t length);

Read up to `length` bytes from `source` and store the bytes in `buffer` . Return the number of bytes actually read. If all bytes have been read from the file, return 0.

Arguments exactly as read(2).

#### Parameters

source | source to operate on |
buffer | store bytes here |
length | length of `buffer` in bytes |

#### Returns

the number of bytes read, 0 on end of file, -1 on error.

### vips_source_is_mappable ()

    gboolean
    vips_source_is_mappable (VipsSource *source);

Some sources can be efficiently mapped into memory. You can still use `vips_source_map()` if this function returns `FALSE`, but it will be slow.

#### Parameters

source | source to operate on |

#### Returns

`TRUE` if the source can be efficiently mapped into memory.

### vips_source_is_file ()

    gboolean
    vips_source_is_file (VipsSource *source);

Test if this source is a simple file with support for seek. Named pipes, for example, will fail this test. If TRUE, you can use `vips_connection_filename()` to find the filename.

Use this to add basic source support for older loaders which can only work on files.

#### Parameters

source | source to operate on |

#### Returns

`TRUE` if the source is a simple file.

### vips_source_map ()

    const void *
    vips_source_map (VipsSource *source,
                     size_t *length);

Map the source entirely into memory and return a pointer to the start. If `length_out` is non-NULL, the source size is written to it.

This operation can take a long time. Use `vips_source_is_mappable()` to check if a source can be mapped efficiently.

The pointer is valid for as long as `source` is alive.

#### Parameters

source | source to operate on |
length_out | return the file length here, or NULL |

#### Returns

a pointer to the start of the file contents, or NULL on error.

### vips_source_map_blob ()

    VipsBlob *
    vips_source_map_blob (VipsSource *source);

Just like `vips_source_map()`, but return a VipsBlob containing the pointer. `source` will stay alive as long as the result is alive.

#### Parameters

source | source to operate on |

#### Returns

a new VipsBlob containing the data, or NULL on error.

### vips_source_seek ()

    gint64
    vips_source_seek (VipsSource *source,
                      gint64 offset,
                      int whence);

Move the file read position. You can't call this after pixel decode starts. The arguments are exactly as lseek(2).

#### Parameters

source | source to operate on |
offset | seek by this offset |
whence | seek relative to this point |

#### Returns

the new file position, or -1 on error.

### vips_source_rewind ()

    int
    vips_source_rewind (VipsSource *source);

Rewind the source to the start.

You can't always do this after the pixel decode phase starts -- for example, pipe-like sources can't be rewound.

#### Parameters

source | source to operate on |

#### Returns

0 on success, or -1 on error.

### vips_source_sniff_at_most ()

    gint64
    vips_source_sniff_at_most (VipsSource *source,
                               unsigned char **data,
                               size_t length);

Attempt to sniff at most `length` bytes from the start of the source. A pointer to the bytes is returned in `data` . The number of bytes actually read is returned -- it may be less than `length` if the file is shorter than `length` . A negative number indicates a read error.

#### Parameters

source | peek this source |
data | return a pointer to the bytes read here |
length | max number of bytes to read |

#### Returns

number of bytes read, or -1 on error.

### vips_source_sniff ()

    unsigned char *
    vips_source_sniff (VipsSource *source,
                       size_t length);

Return a pointer to the first few bytes of the file. If the file is too short, return NULL.

#### Parameters

source | sniff this source |
length | number of bytes to sniff |

#### Returns

a pointer to the bytes at the start of the file, or NULL on error.

### vips_source_length ()

    gint64
    vips_source_length (VipsSource *source);

Return the length in bytes of the source. Unseekable sources, for example pipes, will have to be read entirely into memory before the length can be found, so this operation can take a long time.

#### Parameters

source | source to operate on |

#### Returns

number of bytes in source, or -1 on error.

### vips_source_custom_new ()

    VipsSourceCustom *
    vips_source_custom_new (void);

Create a VipsSourceCustom. Attach signals to implement read and seek.

#### Returns

a new VipsSourceCustom

### vips_g_input_stream_new_from_source ()

    GInputStream *
    vips_g_input_stream_new_from_source (VipsSource *source);

Create a new GInputStream wrapping a VipsSource. This is useful for loaders like SVG and PDF which support GInput methods.

#### Parameters

source | vips source to wrap |

#### Returns

a new GInputStream

### vips_source_g_input_stream_new ()

    VipsSourceGInputStream *
    vips_source_g_input_stream_new (GInputStream *stream);

Create a VipsSourceGInputStream which wraps `stream` .

#### Parameters

stream | read from this stream |

#### Returns

the new source.

### vips_target_new_to_descriptor ()

    VipsTarget *
    vips_target_new_to_descriptor (int descriptor);

Create a target attached to a file descriptor. `descriptor` is kept open until the target is finalized.

See also: `vips_target_new_to_file()`.

#### Parameters

descriptor | write to this file descriptor |

#### Returns

a new target.

### vips_target_new_to_file ()

    VipsTarget *
    vips_target_new_to_file (const char *filename);

Create a target attached to a file.

#### Parameters

filename | write to this file |

#### Returns

a new target.

### vips_target_new_to_memory ()

    VipsTarget *
    vips_target_new_to_memory (void);

Create a target which will write to a memory area. Read from `blob` to get memory.

See also: `vips_target_new_to_file()`.

#### Returns

a new VipsConnection

### vips_target_new_temp ()

    VipsTarget *
    vips_target_new_temp (VipsTarget *target);

Create a temporary target -- either a temporary file on disc, or an area in memory, depending on what sort of target `based_on` is.

See also: `vips_target_new_to_file()`.

#### Parameters

based_on | base the temporary target on this target |

#### Returns

a new target.

### vips_target_write ()

    int
    vips_target_write (VipsTarget *target,
                       const void *data,
                       size_t length);

Write `length` bytes from `buffer` to the output.

#### Parameters

target | target to operate on |
buffer | bytes to write |
length | length of `buffer` in bytes |

#### Returns

0 on success, -1 on error.

### vips_target_read ()

    gint64
    vips_target_read (VipsTarget *target,
                      void *buffer,
                      size_t length);

Read up to `length` bytes from `target` and store the bytes in `buffer` . Return the number of bytes actually read. If all bytes have been read from the file, return 0.

Arguments exactly as read(2).

Reading froma target sounds weird, but libtiff needs this for multi-page writes. This method will fail for targets like pipes.

#### Parameters

target | target to operate on |
buffer | store bytes here |
length | length of `buffer` in bytes |

#### Returns

the number of bytes read, 0 on end of file, -1 on error.

### vips_target_seek ()

    off_t
    vips_target_seek (VipsTarget *target,
                      off_t offset,
                      int whence);

Seek the target. This behaves exactly as lseek(2).

Seeking a target sounds weird, but libtiff needs this. This method will fail for targets like pipes.

#### Parameters

target | target to operate on |
position | position to seek to |
whence | seek relative to beginning, offset, or end |

#### Returns

the new seek position, -1 on error.

### vips_target_end ()

    int
    vips_target_end (VipsTarget *target);

Call this at the end of write to make the target do any cleaning up. You can call it many times.

After a target has been finished, further writes will do nothing.

#### Parameters

target | target to operate on |
buffer | bytes to write |
length | length of `buffer` in bytes |

#### Returns

0 on success, -1 on error.

### vips_target_finish ()

    void
    vips_target_finish (VipsTarget *target);

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

Deprecated in favour of `vips_target_end()`.

#### Parameters

target | target to operate on |
buffer | bytes to write |
length | length of `buffer` in bytes |

### vips_target_steal ()

    unsigned char *
    vips_target_steal (VipsTarget *target,
                       size_t *length);

Memory targets only (see `vips_target_new_to_memory()`). Steal all data written to the target so far, and finish it.

You must free the returned pointer with `g_free()`.

The data is NOT automatically null-terminated. `vips_target_putc()` a '\0' before calling this to get a null-terminated string.

#### Parameters

target | target to operate on |
length | return number of bytes of data |

#### Returns

the data.

[array length=length][element-type guint8][transfer full]

### vips_target_steal_text ()

    char *
    vips_target_steal_text (VipsTarget *target);

As `vips_target_steal_text()`, but return a null-terminated string.

#### Parameters

target | target to operate on |

#### Returns

target contents as a null-terminated string.

[transfer full]

### vips_target_putc ()

    int
    vips_target_putc (VipsTarget *target,
                      int ch);

Write a single character `ch` to `target` . See the macro `VIPS_TARGET_PUTC()` for a faster way to do this.

#### Parameters

target | target to operate on |
ch | character to write |

#### Returns

0 on success, -1 on error.

### VIPS_TARGET_PUTC()

    #define             VIPS_TARGET_PUTC( S, C )

### vips_target_writes ()

    int
    vips_target_writes (VipsTarget *target,
                        const char *str);

Write a null-terminated string to `target` .

#### Parameters

target | target to operate on |
str | string to write |

#### Returns

0 on success, and -1 on error.

### vips_target_writef ()

    int
    vips_target_writef (VipsTarget *target,
                        const char *fmt,
                        ...);

Format the string and write to `target` .

#### Parameters

target | target to operate on |
fmt | <function>`printf()`</function>-style format string |
... | arguments to format string |

#### Returns

0 on success, and -1 on error.

### vips_target_write_amp ()

    int
    vips_target_write_amp (VipsTarget *target,
                           const char *str);

Write `str` to `target` , but escape stuff that xml hates in text. Our argument string is utf-8.

XML rules:

- We must escape &<>

- Don't escape \n, \t, \r

- Do escape the other ASCII codes.

#### Parameters

target | target to operate on |
str | string to write |

#### Returns

0 on success, -1 on error.

### vips_target_custom_new ()

    VipsTargetCustom *
    vips_target_custom_new (void);

Create a VipsTargetCustom. Attach signals to implement write and finish.

#### Returns

a new VipsTargetCustom

## Types and Values

### VipsSourceGInputStream

    typedef struct {
    	VipsSource parent_instance;
    } VipsSourceGInputStream;

### VipsSourceGInputStreamClass

    typedef struct {
    	VipsSourceClass parent_class;
    } VipsSourceGInputStreamClass;

### VIPS_TARGET_BUFFER_SIZE

    #define VIPS_TARGET_BUFFER_SIZE (8500)

### VIPS_TARGET_CUSTOM_BUFFER_SIZE

    #define VIPS_TARGET_CUSTOM_BUFFER_SIZE (4096)

## Property Details

### The `“descriptor”` property

      “descriptor”               int

File descriptor for read or write.

Owner: VipsConnection

Flags: Read / Write

Allowed values: [-1,1000000000]

Default value: 0

### The `“filename”` property

      “filename”                 char *

Name of file to open.

Owner: VipsConnection

Flags: Read / Write

Default value: NULL

### The `“blob”` property

      “blob”                     VipsBlob *

Blob to load from.

Owner: VipsSource

Flags: Read / Write

### The `“blob”` property

      “blob”                     VipsBlob *

Blob to save to.

Owner: VipsTarget

Flags: Read / Write

### The `“memory”` property

      “memory”                   gboolean

File descriptor should output to memory.

Owner: VipsTarget

Flags: Read / Write

Default value: FALSE

## Signal Details

### The `“read”` signal

    gint64
    user_function (VipsSourceCustom *source_custom,
                   gpointer          buffer,
                   gint64            size,
                   gpointer          user_data)

This signal is emitted to read bytes from the source into `buffer` .

#### Parameters

source_custom | the source being operated on |
buffer | `gpointer`, buffer to fill |
size | `gint64`, size of buffer |
user_data | user data set when the signal handler was connected. |

#### Returns

the number of bytes read. Return 0 for EOF.

Flags: Action

### The `“seek”` signal

    gint64
    user_function (VipsSourceCustom *source_custom,
                   gint64            offset,
                   int               whence,
                   gpointer          user_data)

This signal is emitted to seek the source. The handler should change the source position appropriately.

The handler for an unseekable source should always return -1.

#### Parameters

source_custom | the source being operated on |
offset | `gint64`, seek offset |
whence | `gint`, seek origin |
user_data | user data set when the signal handler was connected. |

#### Returns

the new seek position.

Flags: Action

### The `“end”` signal

    int
    user_function (VipsTargetCustom *target_custom,
                   gpointer          user_data)

This signal is emitted at the end of write. The target should do any finishing necessary.

#### Parameters

target_custom | the target being operated on |
user_data | user data set when the signal handler was connected. |

#### Returns

0 on success, -1 on error.

Flags: Action

### The `“finish”` signal

    void
    user_function (VipsTargetCustom *target_custom,
                   gpointer          user_data)

Deprecated for VipsTargetCustom::end.

#### Parameters

target_custom | the target being operated on |
user_data | user data set when the signal handler was connected. |

Flags: Action

### The `“read”` signal

    gint64
    user_function (VipsTargetCustom *target_custom,
                   gpointer          buffer,
                   gint64            size,
                   gpointer          user_data)

This signal is emitted to read bytes from the target into `buffer` .

The handler for an unreadable target should always return -1.

#### Parameters

target_custom | the target being operated on |
buffer | `gpointer`, buffer to fill |
size | `gint64`, size of buffer |
user_data | user data set when the signal handler was connected. |

#### Returns

the number of bytes read. Return 0 for EOF.

Flags: Action

### The `“seek”` signal

    gint64
    user_function (VipsTargetCustom *target_custom,
                   gint64            offset,
                   int               whence,
                   gpointer          user_data)

This signal is emitted to seek the target. The handler should change the target position appropriately.

The handler for an unseekable target should always return -1.

#### Parameters

target_custom | the target being operated on |
offset | `gint64`, seek offset |
whence | `gint`, seek origin |
user_data | user data set when the signal handler was connected. |

#### Returns

the new seek position.

Flags: Action

### The `“write”` signal

    gint64
    user_function (VipsTargetCustom *target_custom,
                   gpointer          data,
                   gint64            length,
                   gpointer          user_data)

This signal is emitted to write bytes to the target.

#### Parameters

target_custom | the target being operated on |
data | `pointer`, bytes to write |
length | `gint64`, number of bytes |
user_data | user data set when the signal handler was connected. |

#### Returns

the number of bytes written.

Flags: Action

## See Also

<link linkend="libvips-foreign">foreign</link>