Top |
Functions
Object Hierarchy
GObject ├── GInputStream │ ╰── VipsGInputStream ╰── VipsObject ╰── VipsConnection ├── VipsSource │ ╰── VipsSourceCustom ╰── VipsTarget ╰── VipsTargetCustom
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_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
.
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.
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.
vips_source_new_from_blob ()
VipsSource *
vips_source_new_from_blob (VipsBlob *blob
);
Create a source attached to an area of memory.
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.
vips_source_new_from_options ()
VipsSource *
vips_source_new_from_options (const char *options
);
Create a source from an option string.
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.
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()
.
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()
.
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).
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.
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.
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.
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).
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.
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.
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.
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.
vips_source_custom_new ()
VipsSourceCustom *
vips_source_custom_new (void
);
Create a VipsSourceCustom. Attach signals to implement read and seek.
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.
vips_source_g_input_stream_new ()
VipsSourceGInputStream *
vips_source_g_input_stream_new (GInputStream *stream
);
Create a VipsSourceGInputStream which wraps stream
.
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()
.
vips_target_new_to_file ()
VipsTarget *
vips_target_new_to_file (const char *filename
);
Create a target attached to a file.
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()
.
vips_target_write ()
int vips_target_write (VipsTarget *target
,const void *data
,size_t length
);
Write length
bytes from buffer
to the output.
vips_target_finish ()
void
vips_target_finish (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.
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.
vips_target_steal_text ()
char *
vips_target_steal_text (VipsTarget *target
);
As vips_target_steal_text()
, but return a null-terminated string.
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.
vips_target_writes ()
int vips_target_writes (VipsTarget *target
,const char *str
);
Write a null-terminated string to target
.
vips_target_writef ()
int vips_target_writef (VipsTarget *target
,const char *fmt
,...
);
Format the string and write to target
.
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.
vips_target_custom_new ()
VipsTargetCustom *
vips_target_custom_new (void
);
Create a VipsTargetCustom. Attach signals to implement write and finish.
Types and Values
VipsSourceGInputStreamClass
typedef struct { VipsSourceClass parent_class; } VipsSourceGInputStreamClass;
Property Details
The “descriptor”
property
“descriptor” gint
File descriptor for read or write.
Owner: VipsConnection
Flags: Read / Write
Allowed values: [-1,1000000000]
Default value: 0
The “filename”
property
“filename” gchar *
Name of file to open.
Owner: VipsConnection
Flags: Read / Write
Default value: NULL
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 |
|
|
size |
|
|
user_data |
user data set when the signal handler was connected. |
Flags: Action
The “seek”
signal
gint64 user_function (VipsSourceCustom *source_custom, gint64 offset, gint 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 |
|
|
whence |
|
|
user_data |
user data set when the signal handler was connected. |
Flags: Action
The “finish”
signal
void 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. |
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 |
|
|
length |
|
|
user_data |
user data set when the signal handler was connected. |
Flags: Action