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

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

0 on success, -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

printf()-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

foreign