IPTC Data

## IPTC Data IPTC Data — creating, loading, saving, and editing a collection of IPTC datasets |

## Synopsis

                        IptcData;
    IptcData*           iptc_data_new                       (void);
    IptcData*           iptc_data_new_mem                   (IptcMem *mem);
    void                iptc_data_ref                       (IptcData *data);
    void                iptc_data_unref                     (IptcData *data);
    void                iptc_data_free                      (IptcData *data);

    IptcData*           iptc_data_new_from_jpeg             (const char *path);
    IptcData*           iptc_data_new_from_data             (unsigned char *buf,
                                                             unsigned int size);

    int                 iptc_data_load                      (IptcData *data,
                                                             unsigned char *buf,
                                                             unsigned int size);
    int                 iptc_data_save                      (IptcData *data,
                                                             unsigned char **buf,
                                                             unsigned int *size);
    void                iptc_data_free_buf                  (IptcData *data,
                                                             unsigned char *buf);

    IptcDataSet*        iptc_data_get_dataset               (IptcData *data,
                                                             IptcRecord record,
                                                             IptcTag tag);
    IptcDataSet*        iptc_data_get_next_dataset          (IptcData *data,
                                                             IptcDataSet *ds,
                                                             IptcRecord record,
                                                             IptcTag tag);
    int                 iptc_data_add_dataset               (IptcData *data,
                                                             IptcDataSet *ds);
    int                 iptc_data_add_dataset_before        (IptcData *data,
                                                             IptcDataSet *ds,
                                                             IptcDataSet *newds);
    int                 iptc_data_add_dataset_after         (IptcData *data,
                                                             IptcDataSet *ds,
                                                             IptcDataSet *newds);
    int                 iptc_data_remove_dataset            (IptcData *data,
                                                             IptcDataSet *ds);

    void                (*IptcDataForeachDataSetFunc)       (IptcDataSet *dataset,
                                                             void *user_data);
    void                iptc_data_foreach_dataset           (IptcData *data,
                                                             IptcDataForeachDataSetFunc func,
                                                             void *user_data);

    void                iptc_data_sort                      (IptcData *data);

    enum                IptcEncoding;
    IptcEncoding        iptc_data_get_encoding              (IptcData *data);
    int                 iptc_data_set_encoding_utf8         (IptcData *data);

    #define             IPTC_IIM_VERSION
    int                 iptc_data_set_version               (IptcData *data,
                                                             unsigned int version);

    int                 iptc_data_add_dataset_with_value    (IptcData *data,
                                                             IptcRecord record,
                                                             IptcTag tag,
                                                             unsigned int value,
                                                             IptcValidate validate);
    int                 iptc_data_add_dataset_with_contents (IptcData *data,
                                                             IptcRecord record,
                                                             IptcTag tag,
                                                             unsigned char *buf,
                                                             unsigned int size,
                                                             IptcValidate validate);

    void                iptc_data_dump                      (IptcData *data,
                                                             unsigned int indent);
    void                iptc_data_log                       (IptcData *data,
                                                             IptcLog *log);

## Description

The IptcData object is the top-level container for a collection of IPTC metadata tags. Each of these tags is stored in an IptcDataSet object.

## Details

### IptcData

    typedef struct {
            IptcDataSet **datasets;
            unsigned int count;

    	IptcDataPrivate *priv;
    } IptcData;

Represents the collection of datasets that make up a IPTC data block.

IptcDataSet **`datasets`; | array of pointers to the datasets in the collection
unsigned int `count`; | the number of datasets in the collection
IptcDataPrivate *`priv`; | private data

### iptc_data_new ()

    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.

Returns : | pointer to the new IptcData object, NULL on error

### iptc_data_new_mem ()

    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.

`mem` : | Pointer to an IptcMem object that defines custom memory managment functions. The refcount of `mem` will be incremented. It is decremented when the returned IptcData object is freed.
Returns : | pointer to the new IptcData object, NULL on error

### iptc_data_ref ()

    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.

`data` : | the referenced pointer

### iptc_data_unref ()

    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.

`data` : | the unreferenced pointer

### iptc_data_free ()

    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.

`data` : | the object to free

### iptc_data_new_from_jpeg ()

    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.

`path` : | filesystem path of the jpeg file to be read
Returns : | pointer to the new IptcData object. NULL on error (including parsing errors or if the file did not include IPTC data).

### iptc_data_new_from_data ()

    IptcData*           iptc_data_new_from_data             (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()`.

`buf` : | the buffer of IPTC data to be decoded
`size` : | the length to be read in bytes
Returns : | pointer to the new IptcData object. NULL on error (including parsing errors in the contents of `buf`).

### iptc_data_load ()

    int                 iptc_data_load                      (IptcData *data,
                                                             unsigned char *buf,
                                                             unsigned int size);

Parses a buffer containing raw IPTC data and adds the datasets to the IptcData object `data`.

`data` : | object to be populated with the loaded datasets
`buf` : | data buffer to be parsed, containing IPTC data
`size` : | length of data buffer to be parsed
Returns : | 0 on success, -1 on failure. Note that in the failure case, some datasets may still have been added to `data`.

### iptc_data_save ()

    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
Returns : | 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.

### iptc_data_free_buf ()

    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.

`data` : | the IptcData object that allocated the buffer
`buf` : | the buffer to free

### iptc_data_get_dataset ()

    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.

`data` : | collection to search
`record` : | record identifier of dataset
`tag` : | tag identifier (dataset number) of dataset
Returns : | pointer to dataset if found, NULL if no matching dataset found

### iptc_data_get_next_dataset ()

    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()`.

`data` : | collection to search
`ds` : | dataset where the search should originate (can be NULL)
`record` : | record identifier of dataset
`tag` : | tag identifier (dataset number) of dataset
Returns : | pointer to dataset if found, NULL if no matching dataset found

### iptc_data_add_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.

`data` : | the collection to which the dataset will be added
`ds` : | dataset to add
Returns : | 0 on success, -1 on error

### iptc_data_add_dataset_before ()

    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.

`data` : | the collection to which the dataset will be added
`ds` : | existing dataset before which `newds` will be added
`newds` : | dataset to add
Returns : | 0 on success, -1 on error

### iptc_data_add_dataset_after ()

    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.

`data` : | the collection to which the dataset will be added
`ds` : | existing dataset after which `newds` will be added
`newds` : | dataset to add
Returns : | 0 on success, -1 on error

### iptc_data_remove_dataset ()

    int                 iptc_data_remove_dataset            (IptcData *data,
                                                             IptcDataSet *ds);

Removes a dataset from a collection. This function also calls `iptc_dataset_unref()` on `ds`.

`data` : | the collection from which to remove an entry
`ds` : | the dataset to remove from the collection
Returns : | 0 on success, -1 on error

### IptcDataForeachDataSetFunc ()

    void                (*IptcDataForeachDataSetFunc)       (IptcDataSet *dataset,
                                                             void *user_data);

Application callback executed for each dataset from `iptc_data_foreach_dataset()`.

`dataset` : | the dataset
`user_data` : | the same `user_data` passed to `iptc_data_foreach_dataset()`

### iptc_data_foreach_dataset ()

    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.

`data` : | collection through which to iterate
`func` : | callback function
`user_data` : | arbitrary user data to be passed to the callback

### iptc_data_sort ()

    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.

`data` : | collection of datasets to sort

### enum IptcEncoding

    typedef enum {
    	IPTC_ENCODING_UNKNOWN = 0,
    	IPTC_ENCODING_UNSPECIFIED = 1,
    	IPTC_ENCODING_UTF8 = 2
    } IptcEncoding;

### iptc_data_get_encoding ()

    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.

`data` : | collection of datasets
Returns : | IPTC_ENCODING_UTF8, IPTC_ENCODING_UNKNOWN, or IPTC_ENCODING_UNSPECIFIED.

### iptc_data_set_encoding_utf8 ()

    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.

`data` : | collection of datasets for which to specify the encoding
Returns : | 0 on success, -1 on failure.

### IPTC_IIM_VERSION

    #define IPTC_IIM_VERSION	4

The version of the IPTC IIM specification implemented by this library.

### iptc_data_set_version ()

    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.

`data` : | collection of datasets for which to specify the version
`version` : | version number to write
Returns : | 0 on success, -1 on failure.

### iptc_data_add_dataset_with_value ()

    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.
Returns : | -1 on error, 0 if validation failed, the number of bytes copied on success

### iptc_data_add_dataset_with_contents ()

    int                 iptc_data_add_dataset_with_contents (IptcData *data,
                                                             IptcRecord record,
                                                             IptcTag tag,
                                                             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.
Returns : | -1 on error, 0 if validation failed, the number of bytes copied on success

### iptc_data_dump ()

    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.

`data` : | collection of datasets to print
`indent` : | indentation level of the printout

### iptc_data_log ()

    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.

`data` : | collection for which the log object should be changed.
`log` : | log object to use for the collection