1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY iptc-overview SYSTEM "overview.sgml">
<!ENTITY iptc-about SYSTEM "about.sgml">
<!ENTITY iptc-commandline SYSTEM "commandline.sgml">
<!ENTITY iptc-i18n SYSTEM "i18n.sgml">
<!ENTITY iptc-libjpeg SYSTEM "libjpeg.sgml">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="libiptcdata-jpeg">
<refmeta>
<refentrytitle role="top_of_page">JPEG</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBIPTCDATA Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>JPEG</refname>
<refpurpose>functions for loading and saving IPTC data from JPEG files</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>
<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>
<synopsis>
<link linkend="int">int</link> <link linkend="iptc-jpeg-read-ps3">iptc_jpeg_read_ps3</link> (<link linkend="FILE:CAPS">FILE</link> *infile,
unsigned <link linkend="char">char</link> *buf,
unsigned <link linkend="int">int</link> size);
<link linkend="int">int</link> <link linkend="iptc-jpeg-ps3-find-iptc">iptc_jpeg_ps3_find_iptc</link> (unsigned <link linkend="char">char</link> *ps3,
unsigned <link linkend="int">int</link> ps3_size,
unsigned <link linkend="int">int</link> *iptc_len);
<link linkend="int">int</link> <link linkend="iptc-jpeg-ps3-save-iptc">iptc_jpeg_ps3_save_iptc</link> (unsigned <link linkend="char">char</link> *ps3,
unsigned <link linkend="int">int</link> ps3_size,
unsigned <link linkend="char">char</link> *iptc,
unsigned <link linkend="int">int</link> iptc_size,
unsigned <link linkend="char">char</link> *buf,
unsigned <link linkend="int">int</link> size);
<link linkend="int">int</link> <link linkend="iptc-jpeg-save-with-ps3">iptc_jpeg_save_with_ps3</link> (<link linkend="FILE:CAPS">FILE</link> *infile,
<link linkend="FILE:CAPS">FILE</link> *outfile,
unsigned <link linkend="char">char</link> *ps3,
unsigned <link linkend="int">int</link> ps3_size);
</synopsis>
</refsynopsisdiv>
<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
Convenience functions for loading and saving IPTC data blocks from JPEG files.
</para>
</refsect1>
<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="iptc-jpeg-read-ps3" role="function"/>iptc_jpeg_read_ps3 ()</title>
<indexterm><primary>iptc_jpeg_read_ps3</primary></indexterm><programlisting><link linkend="int">int</link> iptc_jpeg_read_ps3 (<link linkend="FILE:CAPS">FILE</link> *infile,
unsigned <link linkend="char">char</link> *buf,
unsigned <link linkend="int">int</link> size);</programlisting>
<para>
Scans the headers of a JPEG file looking for a "Photoshop 3.0" header, and if
found, stores the raw contents of this header in the <parameter>buf</parameter> buffer. The Photoshop
3.0 header is a series of records found in the APP13 section of a JPEG file.
If a JPEG file contains IPTC metadata, the metadata is stored in one of the
Photoshop 3.0 records.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>infile</parameter> :</term>
<listitem><simpara> an open JPEG file with the current position set to the start of the file
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter> :</term>
<listitem><simpara> an output buffer to store the Photoshop 3.0 data
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter> :</term>
<listitem><simpara> the size of the output buffer
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of bytes stored on success, 0 if the PS3 header was
not found, or -1 if an error occurred.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="iptc-jpeg-ps3-find-iptc" role="function"/>iptc_jpeg_ps3_find_iptc ()</title>
<indexterm><primary>iptc_jpeg_ps3_find_iptc</primary></indexterm><programlisting><link linkend="int">int</link> iptc_jpeg_ps3_find_iptc (unsigned <link linkend="char">char</link> *ps3,
unsigned <link linkend="int">int</link> ps3_size,
unsigned <link linkend="int">int</link> *iptc_len);</programlisting>
<para>
Parses a "Photoshop 3.0" header in search of IPTC metadata.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ps3</parameter> :</term>
<listitem><simpara> the data of a Photoshop 3.0 header to search
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ps3_size</parameter> :</term>
<listitem><simpara> size in bytes of <parameter>ps3</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>iptc_len</parameter> :</term>
<listitem><simpara> output parameter, the size in bytes of any found IPTC data
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the offset in bytes from the start of <parameter>ps3</parameter> where a block
of IPTC metadata begins, 0 if no IPTC metadata was found, -1 on error.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="iptc-jpeg-ps3-save-iptc" role="function"/>iptc_jpeg_ps3_save_iptc ()</title>
<indexterm><primary>iptc_jpeg_ps3_save_iptc</primary></indexterm><programlisting><link linkend="int">int</link> iptc_jpeg_ps3_save_iptc (unsigned <link linkend="char">char</link> *ps3,
unsigned <link linkend="int">int</link> ps3_size,
unsigned <link linkend="char">char</link> *iptc,
unsigned <link linkend="int">int</link> iptc_size,
unsigned <link linkend="char">char</link> *buf,
unsigned <link linkend="int">int</link> size);</programlisting>
<para>
Takes a Photoshop 3.0 header, <parameter>ps3</parameter>, removes any existing IPTC data inside
that header, and inserts the new IPTC data from <parameter>iptc</parameter>. Any other non-IPTC
portions of <parameter>ps3</parameter> are left unmodified. If <parameter>ps3</parameter> is NULL, a blank PS3 header
is created. If <parameter>iptc</parameter> is NULL, the output PS3 header will contain no IPTC
data, even if <parameter>ps3</parameter> originally contained some.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>ps3</parameter> :</term>
<listitem><simpara> a template PS3 header in which to insert the
new iptc data. Any non-IPTC data in this template will be preserved
in the output Photoshop 3.0 header. If NULL, a PS3 header will be
generated from scratch.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ps3_size</parameter> :</term>
<listitem><simpara> size in bytes of <parameter>ps3</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>iptc</parameter> :</term>
<listitem><simpara> the IPTC bytestream to be encapsulated in the PS3 output. The IPTC
bytestream can be generated with <link linkend="iptc-data-save"><function>iptc_data_save()</function></link>. If
NULL, the output will still be a valid PS3 header, but without any
contained IPTC data.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>iptc_size</parameter> :</term>
<listitem><simpara> size in bytes of <parameter>iptc</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>buf</parameter> :</term>
<listitem><simpara> output buffer for the generated PS3 header
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>size</parameter> :</term>
<listitem><simpara> size in bytes of <parameter>buf</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of bytes written to <parameter>buf</parameter>; -1 on error.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="iptc-jpeg-save-with-ps3" role="function"/>iptc_jpeg_save_with_ps3 ()</title>
<indexterm><primary>iptc_jpeg_save_with_ps3</primary></indexterm><programlisting><link linkend="int">int</link> iptc_jpeg_save_with_ps3 (<link linkend="FILE:CAPS">FILE</link> *infile,
<link linkend="FILE:CAPS">FILE</link> *outfile,
unsigned <link linkend="char">char</link> *ps3,
unsigned <link linkend="int">int</link> ps3_size);</programlisting>
<para>
Takes an existing JPEG file, <parameter>infile</parameter>, removes any existing Photoshop
3.0 header from it, and adds a new PS3 header, writing the output
to <parameter>outfile</parameter>. <parameter>infile</parameter> must be open for reading and is expected to point
to the beginning of the JPEG file, which should be different from <parameter>outfile</parameter>,
which must be open for writing. If <parameter>ps3</parameter> is NULL, the output will contain
no PS3 header. PS3 headers reside in the APP13 section of the JPEG file,
which is created if necessary. All other headers and data will be copied
directly from <parameter>infile</parameter> without modification.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>infile</parameter> :</term>
<listitem><simpara> the file stream from which the image data is copied
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>outfile</parameter> :</term>
<listitem><simpara> the output file stream
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ps3</parameter> :</term>
<listitem><simpara> the Photoshop 3.0 header to add to the output file
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>ps3_size</parameter> :</term>
<listitem><simpara> size in bytes of <parameter>ps3</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 on success, -1 on error. Note that even in error, some data
may have been written to <parameter>outfile</parameter>, and its contents should be considered
undefined.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>
<refsect1><refsect2 /><refsect2 /></refsect1>
</refentry>
|
