1
// ***************************************************************** -*- C++ -*-
3
* Copyright (C) 2004, 2005 Andreas Huggel <ahuggel@gmx.net>
5
* This program is part of the Exiv2 distribution.
7
* This program is free software; you can redistribute it and/or
8
* modify it under the terms of the GNU General Public License
9
* as published by the Free Software Foundation; either version 2
10
* of the License, or (at your option) any later version.
12
* This program is distributed in the hope that it will be useful,
13
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15
* GNU General Public License for more details.
17
* You should have received a copy of the GNU General Public License
18
* along with this program; if not, write to the Free Software
19
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
23
@brief Class JpegImage to access JPEG images
25
@author Andreas Huggel (ahu)
26
<a href="mailto:ahuggel@gmx.net">ahuggel@gmx.net</a>
27
@author Brad Schick (brad)
28
<a href="mailto:brad@robotbattle.com">brad@robotbattle.com</a>
29
@date 15-Jan-05, brad: split out from image.cpp
34
// *****************************************************************************
35
// included header files
38
#include "basicio.hpp"
42
// + standard includes
45
// *****************************************************************************
46
// namespace extensions
50
// *****************************************************************************
54
@brief Abstract helper base class to access JPEG images.
56
class JpegBase : public Image {
60
//! Virtual destructor.
61
virtual ~JpegBase() {}
63
//! @name Manipulators
66
@brief Read all metadata from the image. Before this method
67
is called, the various metadata types (Iptc, Exif) will be empty.
69
This method returns success even when no metadata is found in
70
the image. Callers must therefore check the size of individual
71
metadata types before accessing the data.
73
@throw Error if opening or reading of the file fails or the image
74
data is not valid (does not look like JPEG data).
78
@brief Write metadata back to the image.
80
All existing metadata sections in the image are either created,
81
replaced, or erased. If values for a given metadata type have been
82
assigned, a section for that metadata type will either be created or
83
replaced. If no values have been assigned to a given metadata type,
84
any exists section for that metadata type will be removed from the
87
@throw Error if the operation fails
91
@brief Assign new exif data. The new exif data is not written
92
to the image until the writeMetadata() method is called.
93
@param exifData An ExifData instance holding exif data to be copied
95
void setExifData(const ExifData& exifData);
97
void setIptcData(const IptcData& iptcData);
99
void setComment(const std::string& comment);
101
void setMetadata(const Image& image);
102
void clearMetadata();
108
const ExifData& exifData() const { return exifData_; }
109
ExifData& exifData() { return exifData_; }
110
const IptcData& iptcData() const { return iptcData_; }
111
IptcData& iptcData() { return iptcData_; }
112
std::string comment() const { return comment_; }
113
BasicIo& io() const { return *io_; }
119
@brief Constructor that can either open an existing image or create
120
a new image from scratch. If a new image is to be created, any
121
existing data is overwritten.
122
@param io An auto-pointer that owns a BasicIo instance used for
123
reading and writing image metadata. \b Important: The constructor
124
takes ownership of the passed in BasicIo instance through the
125
auto-pointer. Callers should not continue to use the BasicIo
126
instance after it is passed to this method. Use the Image::io()
127
method to get a temporary reference.
128
@param create Specifies if an existing image should be read (false)
129
or if a new image should be created (true).
130
@param initData Data to initialize newly created images. Only used
131
when \em create is true. Should contain data for the smallest
132
valid image of the calling subclass.
133
@param dataSize Size of initData in bytes.
135
JpegBase(BasicIo::AutoPtr io, bool create,
136
const byte initData[], long dataSize);
138
//! @name Manipulators
141
@brief Writes the image header (aka signature) to the BasicIo instance.
142
@param oIo BasicIo instance that the header is written to.
143
@return 0 if successful;<BR>
144
4 if the output file can not be written to;<BR>
146
virtual int writeHeader(BasicIo& oIo) const =0;
151
@brief Determine if the content of the BasicIo instance is of the
152
type supported by this class.
154
The advance flag determines if the read position in the stream is
155
moved (see below). This applies only if the type matches and the
156
function returns true. If the type does not match, the stream
157
position is not changed. However, if reading from the stream fails,
158
the stream position is undefined. Consult the stream state to obtain
159
more information in this case.
161
@param iIo BasicIo instance to read from.
162
@param advance Flag indicating whether the position of the io
163
should be advanced by the number of characters read to
164
analyse the data (true) or left at its original
165
position (false). This applies only if the type matches.
166
@return true if the data matches the type of this class;<BR>
167
false if the data does not match;<BR>
169
virtual bool isThisType(BasicIo& iIo, bool advance) const =0;
173
static const byte sos_; //!< JPEG SOS marker
174
static const byte eoi_; //!< JPEG EOI marker
175
static const byte app0_; //!< JPEG APP0 marker
176
static const byte app1_; //!< JPEG APP1 marker
177
static const byte app13_; //!< JPEG APP13 marker
178
static const byte com_; //!< JPEG Comment marker
179
static const char exifId_[]; //!< Exif identifier
180
static const char jfifId_[]; //!< JFIF identifier
181
static const char ps3Id_[]; //!< Photoshop marker
182
static const char bimId_[]; //!< Photoshop marker
183
static const uint16_t iptc_; //!< Photoshop Iptc marker
187
BasicIo::AutoPtr io_; //!< Image data io pointer
188
ExifData exifData_; //!< Exif data container
189
IptcData iptcData_; //!< Iptc data container
190
std::string comment_; //!< JPEG comment
194
@brief Advances associated io instance to one byte past the next
195
Jpeg marker and returns the marker. This method should be called
196
when the BasicIo instance is positioned one byte past the end of a
198
@return the next Jpeg segment marker if successful;<BR>
199
-1 if a maker was not found before EOF;<BR>
201
int advanceToMarker() const;
203
@brief Locates Photoshop formated Iptc data in a memory buffer.
204
Operates on raw data to simplify reuse.
205
@param pPsData Pointer to buffer containing entire payload of
206
Photoshop formated APP13 Jpeg segment.
207
@param sizePsData Size in bytes of pPsData.
208
@param record Output value that is set to the start of the Iptc
209
data block within pPsData (may not be null).
210
@param sizeHdr Output value that is set to the size of the header
211
within the Iptc data block pointed to by record (may not
213
@param sizeIptc Output value that is set to the size of the actual
214
Iptc data within the Iptc data block pointed to by record
216
@return 0 if successful;<BR>
217
3 if no Iptc data was found in pPsData;<BR>
218
-2 if the pPsData buffer does not contain valid data.
220
int locateIptcData(const byte *pPsData,
223
uint16_t *const sizeHdr,
224
uint16_t *const sizeIptc) const;
226
@brief Initialize the image with the provided data.
227
@param initData Data to be written to the associated BasicIo
228
@param dataSize Size in bytes of data to be written
229
@return 0 if successful;<BR>
230
4 if the image can not be written to.
232
int initImage(const byte initData[], long dataSize);
234
@brief Provides the main implementation of writeMetadata() by
235
writing all buffered metadata to the provided BasicIo.
236
@param oIo BasicIo instance to write to (a temporary location).
238
@return 4 if opening or writing to the associated BasicIo fails
240
void doWriteMetadata(BasicIo& oIo);
243
//! Default constructor.
246
JpegBase(const JpegBase& rhs);
247
//! Assignment operator
248
JpegBase& operator=(const JpegBase& rhs);
252
@brief Class to access JPEG images
254
class JpegImage : public JpegBase {
255
friend bool isJpegType(BasicIo& iIo, bool advance);
260
@brief Constructor that can either open an existing Jpeg image or create
261
a new image from scratch. If a new image is to be created, any
262
existing data is overwritten. Since the constructor can not return
263
a result, callers should check the good() method after object
264
construction to determine success or failure.
265
@param io An auto-pointer that owns a BasicIo instance used for
266
reading and writing image metadata. \b Important: The constructor
267
takes ownership of the passed in BasicIo instance through the
268
auto-pointer. Callers should not continue to use the BasicIo
269
instance after it is passed to this method. Use the Image::io()
270
method to get a temporary reference.
271
@param create Specifies if an existing image should be read (false)
272
or if a new file should be created (true).
274
JpegImage(BasicIo::AutoPtr io, bool create);
280
// Public only so that we can create a static instance
289
@brief Determine if the content of the BasicIo instance is a Jpeg image.
290
See base class for more details.
291
@param iIo BasicIo instance to read from.
292
@param advance Flag indicating whether the position of the io
293
should be advanced by the number of characters read to
294
analyse the data (true) or left at its original
295
position (false). This applies only if the type matches.
296
@return true if the data matches a Jpeg image;<BR>
297
false if the data does not match;<BR>
299
bool isThisType(BasicIo& iIo, bool advance) const;
301
//! @name Manipulators
304
@brief Writes a Jpeg header (aka signature) to the BasicIo instance.
305
@param oIo BasicIo instance that the header is written to.
306
@return 0 if successful;<BR>
307
2 if the input image is invalid or can not be read;<BR>
308
4 if the temporary image can not be written to;<BR>
309
-3 other temporary errors;<BR>
311
int writeHeader(BasicIo& oIo) const;
315
static const byte soi_; // SOI marker
316
static const byte blank_[]; // Minimal Jpeg image
319
//! Default constructor
322
JpegImage(const JpegImage& rhs);
323
//! Assignment operator
324
JpegImage& operator=(const JpegImage& rhs);
325
}; // class JpegImage
327
static JpegImage::JpegRegister jpegReg;
329
//! Helper class to access %Exiv2 files
330
class ExvImage : public JpegBase {
331
friend bool isExvType(BasicIo& iIo, bool advance);
336
@brief Constructor that can either open an existing Exv image or create
337
a new image from scratch. If a new image is to be created, any
338
existing data is overwritten. Since the constructor can not return
339
a result, callers should check the good() method after object
340
construction to determine success or failure.
341
@param io An auto-pointer that owns a BasicIo instance used for
342
reading and writing image metadata. \b Important: The constructor
343
takes ownership of the passed in BasicIo instance through the
344
auto-pointer. Callers should not continue to use the BasicIo
345
instance after it is passed to this method. Use the Image::io()
346
method to get a temporary reference.
347
@param create Specifies if an existing image should be read (false)
348
or if a new file should be created (true).
350
ExvImage(BasicIo::AutoPtr io, bool create);
356
// Public only so that we can create a static instance
365
@brief Determine if the content of the BasicIo instance is an Exv
366
image. See base class for more details.
367
@param iIo BasicIo instance to read from.
368
@param advance Flag indicating whether the position of the io
369
should be advanced by the number of characters read to
370
analyse the data (true) or left at its original
371
position (false). This applies only if the type matches.
372
@return true if the data matches a Jpeg image;<BR>
373
false if the data does not match;<BR>
375
virtual bool isThisType(BasicIo& iIo, bool advance) const;
377
//! @name Manipulators
380
@brief Writes an Exv header (aka signature) to the BasicIo instance.
381
@param oIo BasicIo instance that the header is written to.
382
@return 0 if successful;<BR>
383
4 if the output file can not be written to;<BR>
385
int writeHeader(BasicIo& oIo) const;
389
static const char exiv2Id_[]; // Exv identifier
390
static const byte blank_[]; // Minimal exiv file
393
//! Default constructor
396
ExvImage(const ExvImage& rhs);
397
//! Assignment operator
398
ExvImage& operator=(const ExvImage& rhs);
401
static ExvImage::ExvRegister exvReg;
405
#endif // #ifndef JPGIMAGE_HPP_