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_ENVthe 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_2the record used for application-specific tags such as Caption, Keywords, etc.
IPTC_RECORD_APP_3application-specific tags
IPTC_RECORD_APP_4application-specific tags
IPTC_RECORD_APP_5application-specific tags
IPTC_RECORD_APP_6application-specific tags
IPTC_RECORD_PREOBJ_DATAcontains information about an encapsulated file
IPTC_RECORD_OBJ_DATAthe encapsulated file data (usually not used)
IPTC_RECORD_POSTOBJ_DATAfollowup 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.


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 recordrecord number of the tag
IptcTag tagdataset number of the tag
const char *nameEnglish name of the tag (no spaces)
const char *titleEnglish title of the tag (may contain spaces)
const char *descriptionEnglish description of the tag
IptcFormat formatdata format of the tag
IptcMandatory mandatorywhether the specification says the tag is required
IptcRepeatable repeatablewhether the specification says the tag can appear more than once
unsigned int minbytesminimum number of bytes in the tag value
unsigned int maxbytesmaximum 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_UNKNOWNUnknown format (for a tag not in the specification)
IPTC_FORMAT_BINARYBinary data (variable length)
IPTC_FORMAT_BYTE1-byte integer
IPTC_FORMAT_SHORT2-byte integer (big-endian)
IPTC_FORMAT_LONG4-byte integer (big-endian)
IPTC_FORMAT_STRINGString data (variable length, of any character set)
IPTC_FORMAT_NUMERIC_STRINGString containing only numerals (variable length)
IPTC_FORMAT_DATEString of the format "YYYYMMDD" (8 bytes)
IPTC_FORMAT_TIMEString 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_OPTIONALtag is allowed to be absent
IPTC_MANDATORYtag 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_REPEATABLEtag can only appear once
IPTC_REPEATABLEtag 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