iptc_dataset_new ()

IptcDataSet *
iptc_dataset_new (void);

Allocates a new dataset, which is initialized to be empty (undefined tag and empty value). The default memory allocation functions (malloc, etc.) are used. If you need custom memory management functions, use iptc_dataset_new_mem() instead. This allocation will set the IptcDataSet refcount to 1, so use iptc_dataset_unref() when finished with the pointer.

iptc_dataset_new_mem ()

IptcDataSet *
iptc_dataset_new_mem (IptcMem *mem);

Allocates a new dataset, which is initialized to be empty (undefined tag and empty value), using custom memory management functions. This allocation will set the IptcDataSet refcount to 1, so use iptc_dataset_unref() when finished with the pointer.

iptc_dataset_copy ()

IptcDataSet *
iptc_dataset_copy (IptcDataSet *dataset);

Allocates a new dataset and copies the contents of an existing dataset into the new one. Copied data includes record, tag, and the data payload. This is a "deep copy" so that a new copy of the data payload is created, not just a pointer duplication. The new dataset has no parent collection, regardless of the parent of the copied dataset. This allocation will set the IptcDataSet refcount to 1, so use iptc_dataset_unref() when finished with the pointer.

iptc_dataset_ref ()

void
iptc_dataset_ref (IptcDataSet *dataset);

Increments the reference count of an IptcDataSet object. This function should be called whenever a copy of a pointer is made by the application. iptc_dataset_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.

iptc_dataset_unref ()

void
iptc_dataset_unref (IptcDataSet *dataset);

Decrements the reference count of an IptcDataSet 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.

iptc_dataset_free ()

void
iptc_dataset_free (IptcDataSet *dataset);

Frees an IptcDataSet object and its contained data. This function should be used only for error handling since iptc_dataset_unref() provides a safer mechanism for freeing that allows multiple components to have access to an object.

iptc_dataset_get_format ()

IptcFormat
iptc_dataset_get_format (IptcDataSet *dataset);

Retrieves the data format of a dataset tag according to the IPTC specification.

iptc_dataset_get_data ()

int
iptc_dataset_get_data (IptcDataSet *dataset,
                       unsigned char *buf,
                       unsigned int size);

Copies the value of a dataset into a buffer. If the buffer has extra space, the data will be NULL-terminated to assist in dealing with strings.

iptc_dataset_get_value ()

unsigned int
iptc_dataset_get_value (IptcDataSet *dataset);

Gets the value of a dataset as an unsigned integer. This function is meant to be used when the format of a tag is a byte, short, or long. Undefined results occur when this function is used on a tag containing data in another format.

iptc_dataset_get_date ()

int
iptc_dataset_get_date (IptcDataSet *dataset,
                       int *year,
                       int *month,
                       int *day);

Interprets the contents of the dataset as an IPTC date and parses the year, month, and day into the given output variables. If any variable is NULL, that value is skipped. IPTC dates are stored as a string in the format YYYYMMDD.

iptc_dataset_get_time ()

int
iptc_dataset_get_time (IptcDataSet *dataset,
                       int *hour,
                       int *min,
                       int *sec,
                       int *tz);

Interprets the contents of the dataset as an IPTC time and parses the hour, minute, second, and timezone into the given output variables. If any variable is NULL, that value is skipped. IPTC times are stored as a string in the format HHMMSS±HHMM.

iptc_dataset_set_tag ()

void
iptc_dataset_set_tag (IptcDataSet *dataset,
                      IptcRecord record,
                      IptcTag tag);

Sets the record and tag number for a dataset object. Each record/tag pair is assigned a specific meaning by the IPTC IIM specification. This function allows any value to be set for the dataset object, regardless of its meaning. This function can also be used to change the record/tag number in place even if it has been already set.

iptc_dataset_set_data ()

int
iptc_dataset_set_data (IptcDataSet *dataset,
                       const unsigned char *buf,
                       unsigned int size,
                       IptcValidate validate);

Copies bytes from a buffer as the new value for a dataset. This is the correct method for setting a dataset value to a string or raw binary sequence. The length of a string should be specified without the trailing NULL. New memory is allocated for the value and size bytes are copied from buf into this new memory (which is freed when the dataset is freed or when a new value is set). If validate is set to IPTC_VALIDATE, the buffer will only be copied if the size does not violate the IPTC specification (it must not be too long or too short). This check is ignored if the dataset's tag is undefined or no information from the specification is available for that tag.

iptc_dataset_set_value ()

int
iptc_dataset_set_value (IptcDataSet *dataset,
                        unsigned int value,
                        IptcValidate validate);

Sets the value of a dataset as an integer. This is the correct method for setting a dataset value with type byte, short, or long. If validate is set to IPTC_VALIDATE, the value will only be set if the tag has type byte, short, or long according the IPTC specification. This check is ignored if the dataset's tag is undefined or no information from the specification is available for that tag.

iptc_dataset_set_date ()

int
iptc_dataset_set_date (IptcDataSet *dataset,
                       int year,
                       int month,
                       int day,
                       IptcValidate validate);

Sets the contents of the dataset to be a date with the specified value. IPTC dates are stored as a string in the format YYYYMMDD.

iptc_dataset_set_time ()

int
iptc_dataset_set_time (IptcDataSet *dataset,
                       int hour,
                       int min,
                       int sec,
                       int tz,
                       IptcValidate validate);

Sets the contents of the dataset to be a time with the specified value. IPTC times are stored as a string in the format HHMMSS±HHMM.

iptc_dataset_get_as_str ()

const char *
iptc_dataset_get_as_str (IptcDataSet *dataset,
                         char *buf,
                         unsigned int size);

Copies the value of a dataset into a buffer as a printable, NULL-terminated string. For tags of type byte, short, or long, the value will be formatted as a string. For tags of type string (including dates and times), the string will simply be copied into the output buffer. For tags containing binary data, the data will be formatted as a string in hexidecimal.

iptc_dataset_dump ()

void
iptc_dataset_dump (IptcDataSet *dataset,
                   unsigned int indent);

A debugging aid that prints out the contents of a dataset to standard output.

struct IptcDataSet

struct IptcDataSet {
	IptcRecord record;
        IptcTag tag;
        const IptcTagInfo * info;

        unsigned char *data;
        unsigned int size;

	/* Data containing this dataset */
	IptcData *parent;

	IptcDataSetPrivate *priv;
};

enum IptcValidate