header

header — get, set and walk image headers

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

int                 im_header_int                       (IMAGE *im,
                                                         const char *field,
                                                         int *out);
int                 im_header_double                    (IMAGE *im,
                                                         const char *field,
                                                         double *out);
int                 im_header_string                    (IMAGE *im,
                                                         const char *field,
                                                         char **out);
int                 im_header_as_string                 (IMAGE *im,
                                                         const char *field,
                                                         char **out);
GType               im_header_get_typeof                (IMAGE *im,
                                                         const char *field);
int                 im_header_get                       (IMAGE *im,
                                                         const char *field,
                                                         GValue *value_copy);
void *              (*im_header_map_fn)                 (IMAGE *Param1,
                                                         const char *Param2,
                                                         GValue *Param3,
                                                         void *Param4);
void *              im_header_map                       (IMAGE *im,
                                                         im_header_map_fn fn,
                                                         void *a);
int                 im_histlin                          (IMAGE *image,
                                                         const char *fmt,
                                                         ...);
int                 im_updatehist                       (IMAGE *out,
                                                         const char *name,
                                                         int argc,
                                                         char *argv[]);
const char *        im_history_get                      (IMAGE *im);

Description

These functions let you get at image header data (including metadata) in a uniform way. They are handy for language bindings but less useful for C users.

They first search the VIPS header fields (see image), then search for a metadata field of that name (see meta). Use im_header_get_typeof() to test for the existance and GType of a header field.

See meta for a set of functions for adding new metadata to an image.

Details

im_header_int ()

int                 im_header_int                       (IMAGE *im,
                                                         const char *field,
                                                         int *out);

Gets out from im under the name field. This function searches for int-valued fields.

See also: im_header_get(), im_header_get_typeof()

im :

image to get the header field from

field :

field name

out :

return field value

Returns :

0 on success, -1 otherwise.

im_header_double ()

int                 im_header_double                    (IMAGE *im,
                                                         const char *field,
                                                         double *out);

Gets out from im under the name field. This function searches for double-valued fields.

See also: im_header_get(), im_header_get_typeof()

im :

image to get the header field from

field :

field name

out :

return field value

Returns :

0 on success, -1 otherwise.

im_header_string ()

int                 im_header_string                    (IMAGE *im,
                                                         const char *field,
                                                         char **out);

Gets out from im under the name field. This function searches for string-valued fields.

See also: im_header_get(), im_header_get_typeof()

im :

image to get the header field from

field :

field name

out :

return field value

Returns :

0 on success, -1 otherwise.

im_header_as_string ()

int                 im_header_as_string                 (IMAGE *im,
                                                         const char *field,
                                                         char **out);

Gets out from im under the name field. This function will read any field, returning it as a printable string. You need to free the string with g_free() when you are done with it.

See also: im_header_get(), im_header_get_typeof().

im :

image to get the header field from

field :

field name

out :

return field value as string

Returns :

0 on success, -1 otherwise.

im_header_get_typeof ()

GType               im_header_get_typeof                (IMAGE *im,
                                                         const char *field);

Read the GType for a header field. Returns zero if there is no field of that name.

See also: im_header_get().

im :

image to test

field :

the name to search for

Returns :

the GType of the field, or zero if there is no field of that name.

im_header_get ()

int                 im_header_get                       (IMAGE *im,
                                                         const char *field,
                                                         GValue *value_copy);

Fill value_copy with a copy of the header field. value_copy must be zeroed but uninitialised.

This will return -1 and add a message to the error buffer if the field does not exist. Use im_header_get_typeof() to test for the existence of a field first if you are not certain it will be there.

For example, to read a double from an image (though of course you would use im_header_double() in practice):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
GValue value = { 0 };
double d;

if( im_header_get( im, field, &value ) )
  return( -1 );

if( G_VALUE_TYPE( &value ) != G_TYPE_DOUBLE ) {
  im_error( "mydomain", _( "field \"%s\" is of type %s, not double" ),
    field, g_type_name( G_VALUE_TYPE( &value ) ) );
  g_value_unset( &value );
  return( -1 );
}

d = g_value_get_double( &value );
g_value_unset( &value );

return( 0 );

See also: im_header_get_typeof(), im_header_double().

im :

image to get the field from from

field :

the name to give the metadata

value_copy :

the GValue is copied into this

Returns :

0 on success, -1 otherwise.

im_header_map_fn ()

void *              (*im_header_map_fn)                 (IMAGE *Param1,
                                                         const char *Param2,
                                                         GValue *Param3,
                                                         void *Param4);

im_header_map ()

void *              im_header_map                       (IMAGE *im,
                                                         im_header_map_fn fn,
                                                         void *a);

This function calls fn for every header field, including every item of metadata.

Like all _map functions, the user function should return NULL to continue iteration, or a non-NULL pointer to indicate early termination.

See also: im_header_get_typeof(), im_header_get().

im :

image to map over

fn :

function to call for each header field

a :

user data for function

Returns :

NULL on success, the failing pointer otherwise.

im_histlin ()

int                 im_histlin                          (IMAGE *image,
                                                         const char *fmt,
                                                         ...);

Add a line to the image history. The fmt and arguments are expanded, the date and time is appended prefixed with a hash character, and the whole string is appended to the image history and terminated with a newline.

For example:

1
im_histlin( im, "vips im_invert %s %s", in->filename, out->filename );

Might add the string

1
2
"vips im_invert /home/john/fred.v /home/john/jim.v # Fri Apr  3 23:30:35
2009\n"

VIPS operations don't add history lines for you because a single action at the application level might involve many VIPS operations. History must be recorded by the application.

See also: im_updatehist().

im :

add history liine to this image

fmt :

printf() format string

... :

arguments to format string

Returns :

0 on success, -1 on error.

im_updatehist ()

int                 im_updatehist                       (IMAGE *out,
                                                         const char *name,
                                                         int argc,
                                                         char *argv[]);

Formats the name/argv as a single string and calls im_histlin(). A convenience function for command-line prorams.

See also: im_history_get().

out :

image to attach history line to

name :

program name

argc :

number of program arguments

argv :

program arguments

Returns :

0 on success, -1 on error.

im_history_get ()

const char *        im_history_get                      (IMAGE *im);

This function reads the image history as a C string. The string is owned by VIPS and must not be freed.

VIPS tracks the history of each image, that is, the sequence of operations that generated that image. Applications built on VIPS need to call im_histlin() for each action they perform setting the command-line equivalent for the action.

See also: im_histlin().

im :

get history from here

Returns :

The history of im as a C string. Do not free!

See Also

meta, check