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 Contains the Exif %MakerNote interface, IFD %MakerNote and a
26
@author Andreas Huggel (ahu)
27
<a href="mailto:ahuggel@gmx.net">ahuggel@gmx.net</a>
28
@date 18-Feb-04, ahu: created
30
#ifndef MAKERNOTE_HPP_
31
#define MAKERNOTE_HPP_
33
// *****************************************************************************
34
// included header files
38
// + standard includes
47
// *****************************************************************************
48
// namespace extensions
51
// *****************************************************************************
55
// *****************************************************************************
59
@brief Exif makernote interface
61
%MakerNote is a low-level container for makernote entries. The ExifData
62
container uses makernote entries just like the other Exif metadata. Thus,
63
clients can access Exif and makernote tags and their values uniformly
64
through the ExifData interface. The role of %MakerNote is very similar to
65
that of class Ifd (but makernotes do not need to be in IFD format, see
66
below). In addition, it provides %MakerNote specific tag descriptions and
67
print functions to interpret the makernote values.
69
MakerNote holds methods and functionality to
70
- read the makernote from a character buffer
71
- copy the makernote to a character buffer
72
- maintain a list of makernote entries (similar to IFD entries)
73
- interpret (print) the values of makernote tags
75
Makernotes can be added to the system by subclassing %MakerNote and
76
registering a create function for the new subclass together with the
77
camera make and model (which may contain wildcards) in the
78
MakerNoteFactory. Since the majority of makernotes are in IFD format,
79
subclass IfdMakerNote is provided. It contains an IFD container and
80
implements all interface methods related to the makernote entries. <BR>
82
To implement a new IFD makernote, all that you need to do is
83
- subclass %IfdMakerNote,
84
- implement methods to read and check the header (if any) as well as
85
clone and create functions,
86
- add a list of tag descriptions and appropriate print functions and
87
- register the camera make/model and create function in the makernote factory.
89
See existing makernote implementations for examples, e.g., CanonMakerNote
92
Finally, the header file which defines the static variable
93
\em register*MakerNote needs to be included from mn.hpp, to ensure that
94
the makernote is automatically registered in the factory.
97
//! @name Not implemented
99
//! Assignment not allowed (memory management mode alloc_ is const)
100
MakerNote& operator=(const MakerNote& rhs);
104
//! Shortcut for a %MakerNote auto pointer.
105
typedef std::auto_ptr<MakerNote> AutoPtr;
110
@brief Constructor. Allows to choose whether or not memory management
111
is required for the Entries.
113
explicit MakerNote(bool alloc =true);
114
//! Virtual destructor.
115
virtual ~MakerNote() {}
118
//! @name Manipulators
121
@brief Read the makernote, including the makernote header, from
122
character buffer buf of length len at position offset (from the
123
start of the TIFF header) and encoded in byte order byteOrder.
124
Return 0 if successful.
126
virtual int read(const byte* buf,
131
@brief Copy (write) the makerNote to the character buffer buf at
132
position offset (from the start of the TIFF header), encoded
133
in byte order byteOrder. Update internal offsets if necessary.
134
Return the number of bytes written.
136
virtual long copy(byte* buf, ByteOrder byteOrder, long offset) =0;
138
@brief Add the entry to the makernote. No duplicate-check is performed,
139
i.e., it is possible to add multiple entries with the same tag.
140
The memory allocation mode of the entry to be added must be the
141
same as that of the makernote and the IFD id of the entry must
142
be set to 'makerIfd'.
144
virtual void add(const Entry& entry) =0;
145
//! The first makernote entry
146
virtual Entries::iterator begin() =0;
147
//! End of the makernote entries
148
virtual Entries::iterator end() =0;
150
@brief Update the base pointer of the %MakerNote and all its entries
153
Allows to re-locate the underlying data buffer to a new location
154
\em pNewBase. This method only has an effect in non-alloc mode.
156
virtual void updateBase(byte* pNewBase) =0;
161
//! Return the byte order (little or big endian).
162
ByteOrder byteOrder() const { return byteOrder_; }
163
//! Return the offset of the makernote from the start of the TIFF header
164
long offset() const { return offset_; }
166
@brief Return an auto-pointer to an newly created, empty instance of
167
the same type as this. The makernote entries are <B>not</B>
168
copied. The caller owns the new object and the auto-pointer
169
ensures that it will be deleted.
171
@param alloc Memory management model for the newly created object.
172
Indicates if memory required to store data should be allocated
173
and deallocated (true) or not (false). If false, only pointers
174
to the buffer provided to read() will be kept. See Ifd for more
175
background on this concept.
177
AutoPtr create(bool alloc =true) const;
179
@brief Return an auto-pointer to a clone of this object. The caller
180
owns the new object and the auto-pointer ensures that it will
183
@note In non-alloc mode the clone potentially contains pointers to
184
the same data buffer as the original.
185
Use updateBase(byte* pNewBase) to adjust them.
187
AutoPtr clone() const;
188
//! The first makernote entry
189
virtual Entries::const_iterator begin() const =0;
190
//! End of the makernote entries
191
virtual Entries::const_iterator end() const =0;
192
//! Find an entry by idx, return a const iterator to the record
193
virtual Entries::const_iterator findIdx(int idx) const =0;
194
//! Return the size of the makernote in bytes
195
virtual long size() const =0;
201
@brief Flag to control the memory management: <BR>
202
True: requires memory allocation and deallocation, <BR>
203
False: no memory management needed.
207
@brief Offset of the makernote from the start of the TIFF header
212
@brief Alternative byte order to use, invalid if the byte order of the
213
Exif block can be used
215
ByteOrder byteOrder_;
218
//! Internal virtual create function.
219
virtual MakerNote* create_(bool alloc =true) const =0;
220
//! Internal virtual copy constructor.
221
virtual MakerNote* clone_() const =0;
223
}; // class MakerNote
225
//! Type for a pointer to a function creating a makernote
226
typedef MakerNote::AutoPtr (*CreateFct)(bool, const byte*, long, ByteOrder, long);
229
@brief Interface for MakerNotes in IFD format. See MakerNote.
231
class IfdMakerNote : public MakerNote {
232
//! @name Not implemented
234
//! Assignment not allowed (Ifd does not have an assignment operator)
235
IfdMakerNote& operator=(const IfdMakerNote& rhs);
239
//! Shortcut for an %IfdMakerNote auto pointer.
240
typedef std::auto_ptr<IfdMakerNote> AutoPtr;
245
@brief Constructor. Requires an %Ifd id and allows to choose whether
246
or not memory management is needed for the Entries and whether
247
the IFD has a next pointer.
249
explicit IfdMakerNote(IfdId ifdId, bool alloc =true, bool hasNext =true);
251
IfdMakerNote(const IfdMakerNote& rhs);
252
//! Virtual destructor
253
virtual ~IfdMakerNote() {}
256
//! @name Manipulators
258
virtual int read(const byte* buf,
263
@brief Read the makernote header from the makernote databuffer. This
264
method must set the offset adjustment (adjOffset_), if needed
265
(assuming that the required information is in the header).
266
Return 0 if successful.
267
@note The default implementation does nothing, assuming there is no
270
virtual int readHeader(const byte* buf,
272
ByteOrder byteOrder);
273
virtual long copy(byte* buf, ByteOrder byteOrder, long offset);
274
virtual void add(const Entry& entry) { ifd_.add(entry); }
275
virtual Entries::iterator begin() { return ifd_.begin(); }
276
virtual Entries::iterator end() { return ifd_.end(); }
277
virtual void updateBase(byte* pNewBase);
282
virtual Entries::const_iterator begin() const { return ifd_.begin(); }
283
virtual Entries::const_iterator end() const { return ifd_.end(); }
284
virtual Entries::const_iterator findIdx(int idx) const;
285
virtual long size() const;
286
AutoPtr create(bool alloc =true) const;
287
AutoPtr clone() const;
289
@brief Check the makernote header. This will typically check if a
290
required prefix string is present in the header. Return 0 if
292
@note The default implementation does nothing, assuming there is no
295
virtual int checkHeader() const;
297
@brief Write the makernote header to a character buffer, return the
298
number of characters written.
299
@note The default implementation copies the header_ buffer.
301
virtual long copyHeader(byte* buf) const;
303
@brief Return the size of the makernote header in bytes.
304
@note The default implementation returns the size of the header_
307
virtual long headerSize() const;
313
@brief True: Adjustment of the IFD offsets is to be added to the
314
offset from the start of the TIFF header (i.e., the
315
start of the Exif data section),
316
False: Adjustment of the IFD offsets is a suitable absolute
317
value. Ignore the offset from the start of the TIFF
322
@brief Adjustment of the IFD offsets relative to the start of the
323
TIFF header or to the start of the makernote, depending on
324
the setting of absOffset_.
327
//! Data buffer for the makernote header
329
//! The makernote IFD
333
virtual IfdMakerNote* create_(bool alloc =true) const =0;
334
virtual IfdMakerNote* clone_() const =0;
336
}; // class IfdMakerNote
339
@brief Factory for MakerNote objects.
341
Maintains an associative list (tree) of camera makes/models and
342
corresponding %MakerNote create functions. Creates an instance of the
343
%MakerNote for one camera make/model. The factory is implemented as a
346
class MakerNoteFactory {
349
static void cleanup();
351
@brief Register a %MakerNote create function for a camera make and
354
Registers a create function for a %MakerNote for a given make and
355
model combination with the factory. Both the make and model strings
356
may contain wildcards ('*', e.g., "Canon*"). If the make already
357
exists in the registry, then a new branch for the model is added. If
358
the model also already exists, then the new create function replaces
361
@param make Camera manufacturer. (Typically the string from the Exif
363
@param model Camera model. (Typically the string from the Exif
365
@param createMakerNote Pointer to a function to create a new
366
%MakerNote of a particular type.
368
static void registerMakerNote(const std::string& make,
369
const std::string& model,
370
CreateFct createMakerNote);
372
//! Register a %MakerNote prototype in the IFD id registry.
373
static void registerMakerNote(IfdId ifdId, MakerNote::AutoPtr makerNote);
376
@brief Create the appropriate %MakerNote based on camera make and
377
model and possibly the contents of the makernote itself, return
378
an auto-pointer to the newly created MakerNote instance. Return
379
0 if no %MakerNote is defined for the camera model.
381
The method searches the make-model tree for a make and model
382
combination in the registry that matches the search key. The search is
383
case insensitive (Todo: implement case-insensitive comparisons) and
384
wildcards in the registry entries are supported. First the best
385
matching make is searched, then the best matching model for this make
386
is searched. If there is no matching make or no matching model within
387
the models registered for the best matching make, then no makernote
388
is created and the function returns 0. If a match is found, the
389
function invokes the registered create function and returns an
390
auto-pointer to the newly created MakerNote. The makernote pointed to
391
is owned by the caller of the function and the auto-pointer ensures
392
that it is deleted. The best match is an exact match, then a match is
393
rated according to the number of matching characters. The makernote
394
buffer is passed on to the create function, which can based on its
395
content, automatically determine the correct version or flavour of the
396
makernote required. This is used, e.g., to determine which of the
397
three Nikon makernotes to create.
399
@param make Camera manufacturer. (Typically the string from the Exif
401
@param model Camera model. (Typically the string from the Exif
403
@param alloc Memory management model for the new MakerNote. Determines
404
if memory required to store data should be allocated and
405
deallocated (true) or not (false). If false, only pointers to
406
the buffer provided to read() will be kept. See Ifd for more
407
background on this concept.
408
@param buf Pointer to the makernote character buffer.
409
@param len Length of the makernote character buffer.
410
@param byteOrder Byte order in which the Exif data (and possibly the
411
makernote) is encoded.
412
@param offset Offset from the start of the TIFF header of the makernote
415
@return An auto-pointer that owns a %MakerNote for the camera model.
416
If the camera is not supported, the pointer is 0.
418
static MakerNote::AutoPtr create(const std::string& make,
419
const std::string& model,
426
//! Create a %MakerNote for an IFD id.
427
static MakerNote::AutoPtr create(IfdId ifdId, bool alloc =true);
430
@brief Match a registry entry with a key (used for make and model).
432
The matching algorithm is case insensitive and wildcards ('*') in the
433
registry entry are supported. The best match is an exact match, then
434
a match is rated according to the number of matching characters.
436
@return A score value indicating how good the key and registry entry
437
match. 0 means no match, values greater than 0 indicate a
438
match, larger values are better matches:<BR>
439
0: key and registry entry do not match<BR>
440
1: a pure wildcard match, i.e., the registry entry is just
442
Score values greater than 1 are computed by adding 1 to the
443
number of matching characters, except for an exact match,
444
which scores 2 plus the number of matching characters.
446
static int match(const std::string& regEntry, const std::string& key);
449
@brief Class Init is used to execute initialisation and termination
450
code exactly once, at the begin and end of the program.
452
See Bjarne Stroustrup, 'The C++ Programming Language 3rd
453
Edition', section 21.5.2 for details about this pattern.
456
static int count; //!< Counts calls to constructor
460
//! Perform one-time initialisations.
462
//! Perform one-time cleanup operations.
470
//! Prevent construction: not implemented.
471
MakerNoteFactory() {}
472
//! Prevent copy construction: not implemented.
473
MakerNoteFactory(const MakerNoteFactory& rhs);
476
//! Creates the private static instance
479
//! Type used to store model labels and %MakerNote create functions
480
typedef std::vector<std::pair<std::string, CreateFct> > ModelRegistry;
481
//! Type used to store a list of make labels and model registries
482
typedef std::vector<std::pair<std::string, ModelRegistry*> > Registry;
483
//! Type used to store a list of IFD ids and %MakerNote prototypes
484
typedef std::map<IfdId, MakerNote*> IfdIdRegistry;
487
//! List of makernote types and corresponding makernote create functions.
488
static Registry* pRegistry_;
489
//! List of makernote IFD ids and corresponding create functions.
490
static IfdIdRegistry* pIfdIdRegistry_;
492
}; // class MakerNoteFactory
498
Each translation unit that includes makernote.hpp declares its own
499
Init object. The destructor ensures that the factory is properly
502
See Bjarne Stroustrup, 'The C++ Programming Language 3rd
503
Edition', section 21.5.2 for details about this pattern.
505
Exiv2::MakerNoteFactory::Init makerNoteFactoryInit;
508
#endif // #ifndef MAKERNOTE_HPP_
added
removed
src/plugins/exiv2/makernote.hpp
