Top | ![]() |
![]() |
![]() |
![]() |
IptcData * | iptc_data_new () |
IptcData * | iptc_data_new_mem () |
void | iptc_data_ref () |
void | iptc_data_unref () |
void | iptc_data_free () |
IptcData * | iptc_data_new_from_jpeg () |
IptcData * | iptc_data_new_from_data () |
int | iptc_data_load () |
int | iptc_data_save () |
void | iptc_data_free_buf () |
IptcDataSet * | iptc_data_get_dataset () |
IptcDataSet * | iptc_data_get_next_dataset () |
int | iptc_data_add_dataset () |
int | iptc_data_add_dataset_before () |
int | iptc_data_add_dataset_after () |
int | iptc_data_remove_dataset () |
void | (*IptcDataForeachDataSetFunc) () |
void | iptc_data_foreach_dataset () |
void | iptc_data_sort () |
IptcEncoding | iptc_data_get_encoding () |
int | iptc_data_set_encoding_utf8 () |
int | iptc_data_set_version () |
int | iptc_data_add_dataset_with_value () |
int | iptc_data_add_dataset_with_contents () |
void | iptc_data_dump () |
void | iptc_data_log () |
IptcData *
iptc_data_new (void
);
Allocates a new collection of datasets, which is initialized to be
empty. The default memory allocation functions (malloc, etc.) are
used. If you need custom memory management functions, use
iptc_data_new_mem()
instead. This allocation will set the IptcData
refcount to 1, so use iptc_data_unref()
when finished with the pointer.
IptcData *
iptc_data_new_mem (IptcMem *mem
);
Allocates a new collection of datasets, which is initialized to be
empty, using custom memory management functions. This allocation
will set the IptcData refcount to 1, so use iptc_data_unref()
when
finished with the object.
void
iptc_data_ref (IptcData *data
);
Increments the reference count of an IptcData object. This function
should be called whenever a copy of a pointer is made by the application.
iptc_data_unref()
can then be used when the pointer is no longer needed
to ensure that the object is freed once the object is completely unused.
void
iptc_data_unref (IptcData *data
);
Decrements the reference count of an IptcData object. The object will automatically be freed when the count reaches 0. This function should be called whenever a pointer is no longer needed by an application. It is also good practice to set the local copy of the pointer to NULL to shield against accidently reusing the value.
void
iptc_data_free (IptcData *data
);
Frees an IptcData object. This function should be used only for error
handling since iptc_data_unref()
provides a safer mechanism for freeing
that allows multiple components to have access to an object. This
function decrements the reference count of any datasets contained by the
object. This will generally cause them to be freed as well unless other
parts of the application are referencing them individually.
IptcData *
iptc_data_new_from_jpeg (const char *path
);
Allocates a new collection of datasets which is initialized by decoding
the IPTC data in JPEG file path
. This allocation will set the IptcData
refcount to 1, so use iptc_data_unref()
when finished with the object.
This is a convenience function that reads the contents of the file,
creates a new IptcData object, parses the file with
iptc_jpeg_read_ps3()
and iptc_jpeg_ps3_find_iptc()
, and loads the
data with iptc_data_load()
. If more fine-grained error detection
is needed, those functions should be used individually.
pointer to the new IptcData object. NULL on error (including parsing errors or if the file did not include IPTC data).
IptcData * iptc_data_new_from_data (const unsigned char *buf
,unsigned int size
);
Allocates a new collection of datasets which is initialized by decoding
the contents of buf
. This allocation will set the IptcData
refcount to 1, so use iptc_data_unref()
when finished with the object.
This is simply a convenience function that can be duplicated by calling
iptc_data_new()
followed by iptc_data_load()
.
pointer to the new IptcData object. NULL on error (including
parsing errors in the contents of buf
).
int iptc_data_load (IptcData *data
,const unsigned char *buf
,unsigned int size
);
Parses a buffer containing raw IPTC data and adds the datasets
to the IptcData object data
.
int iptc_data_save (IptcData *data
,unsigned char **buf
,unsigned int *size
);
Outputs a collection of datasets as an IPTC bytestream. No memory allocation
is required in advance. buf
should point to a NULL pointer that will be set
to the address of the output buffer by this function. size
will contain
this buffer's length after completion. The object data
is unmodified by this
function. The application should free the output buffer using
iptc_data_free_buf()
when it is no longer needed.
data |
collection of datasets to be saved |
|
buf |
pointer to a pointer that will hold the address of the output buffer |
|
size |
pointer to an integer that will hold the length of the output buffer |
0 on success, -1 on failure. In the failure case, buf
should still
be checked for a non-NULL value, and freed using iptc_data_free_buf()
if
necessary.
void iptc_data_free_buf (IptcData *data
,unsigned char *buf
);
Frees a temporary buffer created from an IptcData object by the
iptc_data_save()
function.
IptcDataSet * iptc_data_get_dataset (IptcData *data
,IptcRecord record
,IptcTag tag
);
Finds the first occurence of a dataset inside a collection with the specified record and tag identifiers.
IptcDataSet * iptc_data_get_next_dataset (IptcData *data
,IptcDataSet *ds
,IptcRecord record
,IptcTag tag
);
Finds the next occurence of a dataset inside a collection with
the specified record and tag identifiers following ds
. This is useful
when a collection contains more than one dataset with the same record
and tag identifier (for example, the keywords tag appears once for
each keyword in the IPTC metadata). When ds
is NULL, this function
is equivalent to iptc_data_get_dataset()
.
int iptc_data_add_dataset (IptcData *data
,IptcDataSet *ds
);
Adds an IptcDataSet at the end of an existing collection. A
dataset can only be a member of a single collection. This
function will increment the reference count of dataset
, so if
the application no longer intends to use dataset
directly, it
should call iptc_dataset_unref()
immediately following this call.
int iptc_data_add_dataset_before (IptcData *data
,IptcDataSet *ds
,IptcDataSet *newds
);
Same as iptc_data_add_dataset()
, except the dataset
will be added
before an existing dataset ds
, so that if they are enumerated,
newds
will appear before ds
in the collection. ds
must be
a dataset already present in the collection.
int iptc_data_add_dataset_after (IptcData *data
,IptcDataSet *ds
,IptcDataSet *newds
);
Same as iptc_data_add_dataset()
, except the dataset
will be added
after an existing dataset ds
, so that if they are enumerated,
newds
will appear after ds
in the collection. ds
must be a
dataset already present in the collection.
int iptc_data_remove_dataset (IptcData *data
,IptcDataSet *ds
);
Removes a dataset from a collection. This function also calls
iptc_dataset_unref()
on ds
.
void (*IptcDataForeachDataSetFunc) (IptcDataSet *dataset
,void *user_data
);
void iptc_data_foreach_dataset (IptcData *data
,IptcDataForeachDataSetFunc func
,void *user_data
);
Iterates through each dataset in the collection and calls the callback function on that dataset.
void
iptc_data_sort (IptcData *data
);
Sorts a collection of datasets in ascending order first by record number and second by tag number. It can be useful to call this function before saving IPTC data in order to maintain a more organized file.
IptcEncoding
iptc_data_get_encoding (IptcData *data
);
Identifies the character encoding of the collection of datasets as specified by the "character set" dataset (1:90). The specification allows this dataset to contain control sequences from the ISO 2022 standard. Unfortunately, this standard is very complicated and generally not used by application writers. Thus, rather than attempt to decode any possible any possible control sequence, this function only attempts to recognize the control sequence that identifies the UTF-8 character set. If found, this function will return IPTC_ENCODING_UTF8. All character-based datasets in record 2 and higher are then expected to contain data encoded in the UTF-8 character set. Otherwise, this function will return IPTC_ENCODING_UNKNOWN, meaning that any other character set might be used, including ISO 2022 control sequences that have not been decoded. If dataset 1:90 is not present, this function returns IPTC_ENCODING_UNSPECIFIED, in which case character-based datasets will usually be plain ASCII, although broken applications may have used some other encoding.
int
iptc_data_set_encoding_utf8 (IptcData *data
);
Sets the contents of the "character set" dataset (1:90) to contain the control sequence that indicates UTF-8 as the character encoding for any character-based datasets in record 2 or higher. If dataset 1:90 is not present, it will be added to the collection. Any prior value of dataset 1:90 will be overwritten by this function. Note that some third-party applications (notably Picasa) will ignore all your IPTC data if this option is set.
int iptc_data_set_version (IptcData *data
,unsigned int version
);
Specifies the version of the IIM specification used by this library by setting the value of datasets 1:00 and 2:00. It is recommended to set the version number to IPTC_IIM_VERSION, which specifies the version implemented by this library (currently 4). If datasets 1:00 or 2:00 are not present, they will be added to the collection. Any prior value of the datasets will be overwritten by this function. To ensure strict compliance with the standard, this function should be called before saving a collection of datasets. However, in practice, some applications (notably Picasa) will ignore all your IPTC data if this option is set.
int iptc_data_add_dataset_with_value (IptcData *data
,IptcRecord record
,IptcTag tag
,unsigned int value
,IptcValidate validate
);
This is a convenience function that creates a new dataset with the given
record and tag, adds it to the specified collection of datasets, and
stores the given numeric value as the contents of the dataset. It is
equivalent to calling this sequence of functions: iptc_dataset_new()
,
iptc_dataset_set_tag()
, iptc_data_add_dataset()
,
and iptc_dataset_set_value()
.
data |
collection to which the new dataset should be added |
|
record |
record number of the dataset to be added |
|
tag |
tag (dataset number) of the dataset to be added |
|
value |
value for the dataset |
|
validate |
whether or not the passed value should be validated against the IPTC specification for this dataset's tag. |
int iptc_data_add_dataset_with_contents (IptcData *data
,IptcRecord record
,IptcTag tag
,const unsigned char *buf
,unsigned int size
,IptcValidate validate
);
This is a convenience function that creates a new dataset with the given
record and tag, adds it to the specified collection of datasets, and
stores a copy of the given data buffer as the contents of the dataset.
It is equivalent to calling this sequence of functions: iptc_dataset_new()
,
iptc_dataset_set_tag()
, iptc_data_add_dataset()
,
and iptc_dataset_set_data()
.
data |
collection to which the new dataset should be added |
|
record |
record number of the dataset to be added |
|
tag |
tag (dataset number) of the dataset to be added |
|
buf |
buffer containing the value |
|
size |
number of bytes to copy |
|
validate |
whether or not the passed value should be validated against the IPTC specification for this dataset's tag. |
void iptc_data_dump (IptcData *data
,unsigned int indent
);
A debugging aid that prints out the contents of a collection of datasets to standard output.
void iptc_data_log (IptcData *data
,IptcLog *log
);
Changes the logging object for a IptcData object. The logging
object determines how warning and error messages are relayed back
to the application. This function also calls iptc_log_ref()
on
the new log object and iptc_log_unref()
on the previous log
object.