<refentry id="libtracker-extract-tracker-iptc">
<refmeta>
<refentrytitle role="top_of_page" id="libtracker-extract-tracker-iptc.top_of_page">IPTC</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBTRACKER-EXTRACT Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>IPTC</refname>
<refpurpose>Information Interchange Model (IIM) /
International Press Telecommunications Council (IPTC)</refpurpose>
</refnamediv>
<refsect1 id="libtracker-extract-tracker-iptc.stability-level">
<title>Stability Level</title>
Stable, unless otherwise indicated
</refsect1>

<refsynopsisdiv id="libtracker-extract-tracker-iptc.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;libtracker-extract/tracker-extract.h&gt;

                    <link linkend="TrackerIptcData">TrackerIptcData</link>;
<link linkend="TrackerIptcData">TrackerIptcData</link> *   <link linkend="tracker-iptc-new">tracker_iptc_new</link>                    (const <link linkend="guchar">guchar</link> *buffer,
                                                         <link linkend="gsize">gsize</link> len,
                                                         const <link linkend="gchar">gchar</link> *uri);
<link linkend="void">void</link>                <link linkend="tracker-iptc-free">tracker_iptc_free</link>                   (<link linkend="TrackerIptcData">TrackerIptcData</link> *data);
<link linkend="gboolean">gboolean</link>            <link linkend="tracker-iptc-read">tracker_iptc_read</link>                   (unsigned <link linkend="char">char</link> *buffer,
                                                         <link linkend="size-t">size_t</link> len,
                                                         const <link linkend="gchar">gchar</link> *uri,
                                                         <link linkend="TrackerIptcData">TrackerIptcData</link> *data);
</synopsis>
</refsynopsisdiv>









<refsect1 id="libtracker-extract-tracker-iptc.description" role="desc">
<title role="desc.title">Description</title>
<para>
The Information Interchange Model (IIM) is a file structure and set
of metadata attributes that can be applied to text, images and
other media types. It was developed in the early 1990s by the
International Press Telecommunications Council (IPTC) to expedite
the international exchange of news among newspapers and news
agencies.
</para>
<para>
The full IIM specification includes a complex data structure and a
set of metadata definitions.
</para>
<para>
Although IIM was intended for use with all types of news items —
including simple text articles — a subset found broad worldwide
acceptance as the standard embedded metadata used by news and
commercial photographers. Information such as the name of the
photographer, copyright information and the caption or other
description can be embedded either manually or automatically.
</para>
<para>
IIM metadata embedded in images are often referred to as "IPTC
headers," and can be easily encoded and decoded by most popular
photo editing software.
</para>
<para>
The Extensible Metadata Platform (XMP) has largely superseded IIM's
file structure, but the IIM image attributes are defined in the
IPTC Core schema for XMP and most image manipulation programs keep
the XMP and non-XMP IPTC attributes synchronized.
</para>
<para>
This API is provided to remove code duplication between extractors
using these standards.</para>
<para>
</para>
</refsect1>

<refsect1 id="libtracker-extract-tracker-iptc.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="TrackerIptcData" role="struct">
<title>TrackerIptcData</title>
<indexterm zone="TrackerIptcData"><primary sortas="TrackerIptcData">TrackerIptcData</primary></indexterm><programlisting>typedef struct {
	gchar *keywords;
	gchar *date_created;
	gchar *byline;
	gchar *credit;
	gchar *copyright_notice;
	gchar *image_orientation;
	gchar *byline_title;
	gchar *city;
	gchar *state;
	gchar *sublocation;
	gchar *country_name;
	gchar *contact;
} TrackerIptcData;
</programlisting>
<para>
</para></refsect2>
<refsect2 id="tracker-iptc-new" role="function" condition="since:0.9">
<title>tracker_iptc_new ()</title>
<indexterm zone="tracker-iptc-new" role="0.9"><primary sortas="tracker_iptc_new">tracker_iptc_new</primary></indexterm><programlisting><link linkend="TrackerIptcData">TrackerIptcData</link> *   tracker_iptc_new                    (const <link linkend="guchar">guchar</link> *buffer,
                                                         <link linkend="gsize">gsize</link> len,
                                                         const <link linkend="gchar">gchar</link> *uri);</programlisting>
<para>
This function takes <parameter>len</parameter> bytes of <parameter>buffer</parameter> and runs it through the
IPTC library.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>buffer</parameter>&#160;:</term>
<listitem><simpara> a chunk of data with iptc data in it.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</term>
<listitem><simpara> the size of <parameter>buffer</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter>&#160;:</term>
<listitem><simpara> the URI this is related to.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated <link linkend="TrackerIptcData"><type>TrackerIptcData</type></link> struct if IPTC data was
found, <link linkend="NULL--CAPS"><literal>NULL</literal></link> otherwise. Free the returned struct with
<link linkend="tracker-iptc-free"><function>tracker_iptc_free()</function></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.9</para></refsect2>
<refsect2 id="tracker-iptc-free" role="function" condition="since:0.9">
<title>tracker_iptc_free ()</title>
<indexterm zone="tracker-iptc-free" role="0.9"><primary sortas="tracker_iptc_free">tracker_iptc_free</primary></indexterm><programlisting><link linkend="void">void</link>                tracker_iptc_free                   (<link linkend="TrackerIptcData">TrackerIptcData</link> *data);</programlisting>
<para>
Frees <parameter>data</parameter> and all <link linkend="TrackerIptcData"><type>TrackerIptcData</type></link> members. <link linkend="NULL--CAPS"><literal>NULL</literal></link> will produce a
a warning.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="TrackerIptcData"><type>TrackerIptcData</type></link>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.9</para></refsect2>
<refsect2 id="tracker-iptc-read" role="function" condition="deprecated:0.9. Use tracker_iptc_new() instead.|since:0.8">
<title>tracker_iptc_read ()</title>
<indexterm zone="tracker-iptc-read" role="deprecated"><primary sortas="tracker_iptc_read">tracker_iptc_read</primary></indexterm><indexterm zone="tracker-iptc-read" role="0.8"><primary sortas="tracker_iptc_read">tracker_iptc_read</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            tracker_iptc_read                   (unsigned <link linkend="char">char</link> *buffer,
                                                         <link linkend="size-t">size_t</link> len,
                                                         const <link linkend="gchar">gchar</link> *uri,
                                                         <link linkend="TrackerIptcData">TrackerIptcData</link> *data);</programlisting>
<warning><para><literal>tracker_iptc_read</literal> is deprecated and should not be used in newly-written code. 0.9. Use <link linkend="tracker-iptc-new"><function>tracker_iptc_new()</function></link> instead.</para></warning>
<para>
This function takes <parameter>len</parameter> bytes of <parameter>buffer</parameter> and runs it through the
IPTC library. The result is that <parameter>data</parameter> is populated with the IPTC
data found in <parameter>uri</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>buffer</parameter>&#160;:</term>
<listitem><simpara> a chunk of data with iptc data in it.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>len</parameter>&#160;:</term>
<listitem><simpara> the size of <parameter>buffer</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>uri</parameter>&#160;:</term>
<listitem><simpara> the URI this is related to.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> a pointer to a TrackerIptcData struture to populate.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the <parameter>data</parameter> was populated successfully, otherwise
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link> is returned.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 0.8</para></refsect2>

</refsect1>




</refentry>
