## Tag Specifications

Tag Specifications — querying tag usage information from the IPTC IIM specification

## Synopsis

    enum                IptcRecord;
    enum                IptcTag;

    struct              IptcTagInfo;
    enum                IptcFormat;
    enum                IptcMandatory;
    enum                IptcRepeatable;

    const char *        iptc_tag_get_name                   (IptcRecord record,
                                                             IptcTag tag);
    char *              iptc_tag_get_title                  (IptcRecord record,
                                                             IptcTag tag);
    char *              iptc_tag_get_description            (IptcRecord record,
                                                             IptcTag tag);
    const IptcTagInfo * iptc_tag_get_info                   (IptcRecord record,
                                                             IptcTag tag);
    char *              iptc_format_get_name                (IptcFormat format);
    int                 iptc_tag_find_by_name               (const char *name,
                                                             IptcRecord *record,
                                                             IptcTag *tag);

## Description

These functions allow queries to the IPTC IIM specification which contains information about the purpose of each IPTC tag, along with any requirements such as maximum/minimum data length, data type, repeatability and whether the tag is mandatory.

## Details

### enum IptcRecord

    typedef enum {
    	IPTC_RECORD_OBJECT_ENV		= 1,
    	IPTC_RECORD_APP_2		= 2,
    	IPTC_RECORD_APP_3		= 3,
    	IPTC_RECORD_APP_4		= 4,
    	IPTC_RECORD_APP_5		= 5,
    	IPTC_RECORD_APP_6		= 6,
    	IPTC_RECORD_PREOBJ_DATA		= 7,
    	IPTC_RECORD_OBJ_DATA		= 8,
    	IPTC_RECORD_POSTOBJ_DATA = 9
    } IptcRecord;

The record number that, together with the tag number (IptcTag), uniquely identifies the purpose of a tag.

`IPTC_RECORD_OBJECT_ENV` | the record used for file information such as file format, version, unique identifier, etc. This is often not used for photo-management applications.
`IPTC_RECORD_APP_2` | the record used for application-specific tags such as Caption, Keywords, etc.
`IPTC_RECORD_APP_3` | application-specific tags
`IPTC_RECORD_APP_4` | application-specific tags
`IPTC_RECORD_APP_5` | application-specific tags
`IPTC_RECORD_APP_6` | application-specific tags
`IPTC_RECORD_PREOBJ_DATA` | contains information about an encapsulated file
`IPTC_RECORD_OBJ_DATA` | the encapsulated file data (usually not used)
`IPTC_RECORD_POSTOBJ_DATA` | followup information about an encapsulated file

### enum IptcTag

    typedef enum {
    	IPTC_TAG_MODEL_VERSION		= 0, /* Begin record 1 tags */
    	IPTC_TAG_DESTINATION		= 5,
    	IPTC_TAG_FILE_FORMAT		= 20,
    	IPTC_TAG_FILE_VERSION		= 22,
    	IPTC_TAG_SERVICE_ID		= 30,
    	IPTC_TAG_ENVELOPE_NUM		= 40,
    	IPTC_TAG_PRODUCT_ID		= 50,
    	IPTC_TAG_ENVELOPE_PRIORITY = 60,
    	IPTC_TAG_DATE_SENT		= 70,
    	IPTC_TAG_TIME_SENT		= 80,
    	IPTC_TAG_CHARACTER_SET		= 90,
    	IPTC_TAG_UNO			= 100,
    	IPTC_TAG_ARM_ID			= 120,
    	IPTC_TAG_ARM_VERSION		= 122, /* End record 1 tags */
    	IPTC_TAG_RECORD_VERSION		= 0, /* Begin record 2 tags */
    	IPTC_TAG_OBJECT_TYPE		= 3,
    	IPTC_TAG_OBJECT_ATTRIBUTE = 4,
    	IPTC_TAG_OBJECT_NAME		= 5,
    	IPTC_TAG_EDIT_STATUS		= 7,
    	IPTC_TAG_EDITORIAL_UPDATE = 8,
    	IPTC_TAG_URGENCY		= 10,
    	IPTC_TAG_SUBJECT_REFERENCE = 12,
    	IPTC_TAG_CATEGORY		= 15,
    	IPTC_TAG_SUPPL_CATEGORY		= 20,
    	IPTC_TAG_FIXTURE_ID		= 22,
    	IPTC_TAG_KEYWORDS		= 25,
    	IPTC_TAG_CONTENT_LOC_CODE = 26,
    	IPTC_TAG_CONTENT_LOC_NAME = 27,
    	IPTC_TAG_RELEASE_DATE		= 30,
    	IPTC_TAG_RELEASE_TIME		= 35,
    	IPTC_TAG_EXPIRATION_DATE = 37,
    	IPTC_TAG_EXPIRATION_TIME = 38,
    	IPTC_TAG_SPECIAL_INSTRUCTIONS = 40,
    	IPTC_TAG_ACTION_ADVISED		= 42,
    	IPTC_TAG_REFERENCE_SERVICE = 45,
    	IPTC_TAG_REFERENCE_DATE		= 47,
    	IPTC_TAG_REFERENCE_NUMBER = 50,
    	IPTC_TAG_DATE_CREATED		= 55,
    	IPTC_TAG_TIME_CREATED		= 60,
    	IPTC_TAG_DIGITAL_CREATION_DATE = 62,
    	IPTC_TAG_DIGITAL_CREATION_TIME = 63,
    	IPTC_TAG_ORIGINATING_PROGRAM = 65,
    	IPTC_TAG_PROGRAM_VERSION = 70,
    	IPTC_TAG_OBJECT_CYCLE		= 75,
    	IPTC_TAG_BYLINE			= 80,
    	IPTC_TAG_BYLINE_TITLE		= 85,
    	IPTC_TAG_CITY			= 90,
    	IPTC_TAG_SUBLOCATION		= 92,
    	IPTC_TAG_STATE			= 95,
    	IPTC_TAG_COUNTRY_CODE		= 100,
    	IPTC_TAG_COUNTRY_NAME		= 101,
    	IPTC_TAG_ORIG_TRANS_REF		= 103,
    	IPTC_TAG_HEADLINE		= 105,
    	IPTC_TAG_CREDIT			= 110,
    	IPTC_TAG_SOURCE			= 115,
    	IPTC_TAG_COPYRIGHT_NOTICE = 116,
    	IPTC_TAG_PICASA_UNKNOWN		= 117,
    	IPTC_TAG_CONTACT		= 118,
    	IPTC_TAG_CAPTION		= 120,
    	IPTC_TAG_WRITER_EDITOR		= 122,
    	IPTC_TAG_RASTERIZED_CAPTION = 125,
    	IPTC_TAG_IMAGE_TYPE		= 130,
    	IPTC_TAG_IMAGE_ORIENTATION = 131,
    	IPTC_TAG_LANGUAGE_ID		= 135,
    	IPTC_TAG_AUDIO_TYPE		= 150,
    	IPTC_TAG_AUDIO_SAMPLING_RATE = 151,
    	IPTC_TAG_AUDIO_SAMPLING_RES = 152,
    	IPTC_TAG_AUDIO_DURATION		= 153,
    	IPTC_TAG_AUDIO_OUTCUE		= 154,
    	IPTC_TAG_PREVIEW_FORMAT		= 200,
    	IPTC_TAG_PREVIEW_FORMAT_VER = 201,
    	IPTC_TAG_PREVIEW_DATA		= 202, /* End record 2 tags */
    	IPTC_TAG_SIZE_MODE		= 10, /* Begin record 7 tags */
    	IPTC_TAG_MAX_SUBFILE_SIZE = 20,
    	IPTC_TAG_SIZE_ANNOUNCED		= 90,
    	IPTC_TAG_MAX_OBJECT_SIZE = 95, /* End record 7 tags */
    	IPTC_TAG_SUBFILE		= 10, /* Record 8 tags */
    	IPTC_TAG_CONFIRMED_DATA_SIZE = 10 /* Record 9 tags */
    } IptcTag;

The tag number that, together with the record number (IptcRecord), uniquely identifies the purpose of a tag.

`IPTC_TAG_MODEL_VERSION` |
`IPTC_TAG_DESTINATION` |
`IPTC_TAG_FILE_FORMAT` |
`IPTC_TAG_FILE_VERSION` |
`IPTC_TAG_SERVICE_ID` |
`IPTC_TAG_ENVELOPE_NUM` |
`IPTC_TAG_PRODUCT_ID` |
`IPTC_TAG_ENVELOPE_PRIORITY` |
`IPTC_TAG_DATE_SENT` |
`IPTC_TAG_TIME_SENT` |
`IPTC_TAG_CHARACTER_SET` |
`IPTC_TAG_UNO` |
`IPTC_TAG_ARM_ID` |
`IPTC_TAG_ARM_VERSION` |
`IPTC_TAG_RECORD_VERSION` |
`IPTC_TAG_OBJECT_TYPE` |
`IPTC_TAG_OBJECT_ATTRIBUTE` |
`IPTC_TAG_OBJECT_NAME` |
`IPTC_TAG_EDIT_STATUS` |
`IPTC_TAG_EDITORIAL_UPDATE` |
`IPTC_TAG_URGENCY` |
`IPTC_TAG_SUBJECT_REFERENCE` |
`IPTC_TAG_CATEGORY` |
`IPTC_TAG_SUPPL_CATEGORY` |
`IPTC_TAG_FIXTURE_ID` |
`IPTC_TAG_KEYWORDS` |
`IPTC_TAG_CONTENT_LOC_CODE` |
`IPTC_TAG_CONTENT_LOC_NAME` |
`IPTC_TAG_RELEASE_DATE` |
`IPTC_TAG_RELEASE_TIME` |
`IPTC_TAG_EXPIRATION_DATE` |
`IPTC_TAG_EXPIRATION_TIME` |
`IPTC_TAG_SPECIAL_INSTRUCTIONS` |
`IPTC_TAG_ACTION_ADVISED` |
`IPTC_TAG_REFERENCE_SERVICE` |
`IPTC_TAG_REFERENCE_DATE` |
`IPTC_TAG_REFERENCE_NUMBER` |
`IPTC_TAG_DATE_CREATED` |
`IPTC_TAG_TIME_CREATED` |
`IPTC_TAG_DIGITAL_CREATION_DATE` |
`IPTC_TAG_DIGITAL_CREATION_TIME` |
`IPTC_TAG_ORIGINATING_PROGRAM` |
`IPTC_TAG_PROGRAM_VERSION` |
`IPTC_TAG_OBJECT_CYCLE` |
`IPTC_TAG_BYLINE` |
`IPTC_TAG_BYLINE_TITLE` |
`IPTC_TAG_CITY` |
`IPTC_TAG_SUBLOCATION` |
`IPTC_TAG_STATE` |
`IPTC_TAG_COUNTRY_CODE` |
`IPTC_TAG_COUNTRY_NAME` |
`IPTC_TAG_ORIG_TRANS_REF` |
`IPTC_TAG_HEADLINE` |
`IPTC_TAG_CREDIT` |
`IPTC_TAG_SOURCE` |
`IPTC_TAG_COPYRIGHT_NOTICE` |
`IPTC_TAG_PICASA_UNKNOWN` |
`IPTC_TAG_CONTACT` |
`IPTC_TAG_CAPTION` |
`IPTC_TAG_WRITER_EDITOR` |
`IPTC_TAG_RASTERIZED_CAPTION` |
`IPTC_TAG_IMAGE_TYPE` |
`IPTC_TAG_IMAGE_ORIENTATION` |
`IPTC_TAG_LANGUAGE_ID` |
`IPTC_TAG_AUDIO_TYPE` |
`IPTC_TAG_AUDIO_SAMPLING_RATE` |
`IPTC_TAG_AUDIO_SAMPLING_RES` |
`IPTC_TAG_AUDIO_DURATION` |
`IPTC_TAG_AUDIO_OUTCUE` |
`IPTC_TAG_PREVIEW_FORMAT` |
`IPTC_TAG_PREVIEW_FORMAT_VER` |
`IPTC_TAG_PREVIEW_DATA` |
`IPTC_TAG_SIZE_MODE` |
`IPTC_TAG_MAX_SUBFILE_SIZE` |
`IPTC_TAG_SIZE_ANNOUNCED` |
`IPTC_TAG_MAX_OBJECT_SIZE` |
`IPTC_TAG_SUBFILE` |
`IPTC_TAG_CONFIRMED_DATA_SIZE` |

### struct IptcTagInfo

    struct IptcTagInfo {
    	IptcRecord record;
    	IptcTag		tag;
    	const char     *name;
    	const char     *title;
    	const char     *description;
    	IptcFormat format;
    	IptcMandatory mandatory;
    	IptcRepeatable repeatable;
    	unsigned int minbytes;
    	unsigned int maxbytes;
    };

Contains static information about a specific tag (identified by its record-tag pair) from the IPTC IIM specificiation. This info is for reference only and should never be modified by an application.

IptcRecord `record`; | record number of the tag
IptcTag `tag`; | dataset number of the tag
const char *`name`; | English name of the tag (no spaces)
const char *`title`; | English title of the tag (may contain spaces)
const char *`description`; | English description of the tag
IptcFormat `format`; | data format of the tag
IptcMandatory `mandatory`; | whether the specification says the tag is required
IptcRepeatable `repeatable`; | whether the specification says the tag can appear more than once
unsigned int `minbytes`; | minimum number of bytes in the tag value
unsigned int `maxbytes`; | maximum number of bytes in the tag value

### enum IptcFormat

    typedef enum {
    	IPTC_FORMAT_UNKNOWN,
    	IPTC_FORMAT_BINARY,
    	IPTC_FORMAT_BYTE,
    	IPTC_FORMAT_SHORT,
    	IPTC_FORMAT_LONG,
    	IPTC_FORMAT_STRING,
    	IPTC_FORMAT_NUMERIC_STRING,
    	IPTC_FORMAT_DATE,
    	IPTC_FORMAT_TIME
    } IptcFormat;

The possible data formats for a tag's value, derived from the IPTC IIM specification. Integer formats are always represented with the most significant byte first (big-endian) in the IPTC bytestream.

`IPTC_FORMAT_UNKNOWN` | Unknown format (for a tag not in the specification)
`IPTC_FORMAT_BINARY` | Binary data (variable length)
`IPTC_FORMAT_BYTE` | 1-byte integer
`IPTC_FORMAT_SHORT` | 2-byte integer (big-endian)
`IPTC_FORMAT_LONG` | 4-byte integer (big-endian)
`IPTC_FORMAT_STRING` | String data (variable length, of any character set)
`IPTC_FORMAT_NUMERIC_STRING` | String containing only numerals (variable length)
`IPTC_FORMAT_DATE` | String of the format "YYYYMMDD" (8 bytes)
`IPTC_FORMAT_TIME` | String of the format "HHMMSS±HHMM" where the second HHMM defines the timezone offset (11 bytes)

### enum IptcMandatory

    typedef enum {
    	IPTC_OPTIONAL = 0,
    	IPTC_MANDATORY = 1
    } IptcMandatory;

Whether a tag is mandatory according to the IPTC IIM specification. Note that most applications ignore this aspect of the specification since the spec was designed to encapsulate the media file rather than the other way around (which is how nearly all applications use it). This renders most mandatory tags unnecessary.

`IPTC_OPTIONAL` | tag is allowed to be absent
`IPTC_MANDATORY` | tag must be present

### enum IptcRepeatable

    typedef enum {
    	IPTC_NOT_REPEATABLE = 0,
    	IPTC_REPEATABLE = 1
    } IptcRepeatable;

Whether a tag can occur more than once according to the IPTC IIM specification. For example, the "Keywords" tag only contains a single keyword, but the tag itself is repeated for media that references more than one keyword.

`IPTC_NOT_REPEATABLE` | tag can only appear once
`IPTC_REPEATABLE` | tag can be repeated

### iptc_tag_get_name ()

    const char *        iptc_tag_get_name                   (IptcRecord record,
                                                             IptcTag tag);

Retrieves the name of a tag. The name is derived from the IPTC IIM specification and gives an indication of the purpose of a particular tag. The name will consist of ASCII characters with no spaces, for example "CopyrightNotice".

`record` : | record number of tag
`tag` : | dataset number of tag
Returns : | a static string containing the tag name, NULL if none found

### iptc_tag_get_title ()

    char *              iptc_tag_get_title                  (IptcRecord record,
                                                             IptcTag tag);

Retrieves the title of a tag. The title is similar to the name, except it will be translated to the current locale (if available) and may contain spaces, for example "Copyright Notice". It is appropriate for the title to appear in user interfaces. The return value will be encoding using the UTF-8 character set.

`record` : | record number of tag
`tag` : | dataset number of tag
Returns : | a static string containing the tag title, empty string if none found

### iptc_tag_get_description ()

    char *              iptc_tag_get_description            (IptcRecord record,
                                                             IptcTag tag);

Retrieves the description of a tag, which explains the purpose of the tag from the IPTC IIM specification. It is translated to the current locale if available. The return value will be encoded using the UTF-8 character set.

`record` : | record number of tag
`tag` : | dataset number of tag
Returns : | a static string containing the tag desciption, empty string if none found

### iptc_tag_get_info ()

    const IptcTagInfo * iptc_tag_get_info                   (IptcRecord record,
                                                             IptcTag tag);

Retrieves the IptcTagInfo structure containing information about the tag from the IPTC IIM specification such as purpose, data format, and minimum and maximum lengths.

`record` : | record number of tag
`tag` : | dataset number of tag
Returns : | a pointer to a static IptcTagInfo structure or NULL if the tag is not found.

### iptc_format_get_name ()

    char *              iptc_format_get_name                (IptcFormat format);

Retrieves a string version of a data format. For example, `IPTC_FORMAT_STRING` returns "String".

`format` : | the format to be retrieved
Returns : | a static string in the native locale

### iptc_tag_find_by_name ()

    int                 iptc_tag_find_by_name               (const char *name,
                                                             IptcRecord *record,
                                                             IptcTag *tag);

Looks up the record and tag numbers for a tag specified by name. For example, searching for "Caption" would return 2:120 in the record and tag variables.

`name` : | the name to search for
`record` : | output variable to store the record number
`tag` : | output variable to store the tag number
Returns : | 0 on success, -1 on failure or if the tag name was not found