tag: libiptcdata Reference Manual

## tag tag |

## Functions

const char * | iptc_tag_get_name ()
char * | iptc_tag_get_title ()
char * | iptc_tag_get_description ()
const IptcTagInfo * | iptc_tag_get_info ()
char * | iptc_format_get_name ()
int | iptc_tag_find_by_name ()

## Types and Values

enum | IptcRecord
enum | IptcTag
struct | IptcTagInfo
enum | IptcFormat
enum | IptcMandatory
enum | IptcRepeatable

## Description

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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".

#### Parameters

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.

#### Parameters

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

## Types and Values

### enum IptcRecord

#### Members

IPTC_RECORD_OBJECT_ENV |  |
IPTC_RECORD_APP_2 |  |
IPTC_RECORD_APP_3 |  |
IPTC_RECORD_APP_4 |  |
IPTC_RECORD_APP_5 |  |
IPTC_RECORD_APP_6 |  |
IPTC_RECORD_PREOBJ_DATA |  |
IPTC_RECORD_OBJ_DATA |  |
IPTC_RECORD_POSTOBJ_DATA |  |

### enum IptcTag

#### Members

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;
    };

### enum IptcFormat

#### Members

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 |  |

### enum IptcMandatory

#### Members

IPTC_OPTIONAL |  |
IPTC_MANDATORY |  |

### enum IptcRepeatable

#### Members

IPTC_NOT_REPEATABLE |  |
IPTC_REPEATABLE |  |