Tag Specifications

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

Synopsis

enum                IptcRecord;
enum                IptcTag;

                    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.

IptcTagInfo

typedef struct {
	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;
} IptcTagInfo;

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
Generated by GTK-Doc V1.10