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
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>Adobe XMP Toolkit: TXMPFiles< tStringObj > Class Template Reference</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.1 -->
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li id="current"><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul></div>
<div class="tabs">
<ul>
<li><a href="annotated.html"><span>Class List</span></a></li>
<li><a href="functions.html"><span>Class Members</span></a></li>
</ul></div>
<h1>TXMPFiles< tStringObj > Class Template Reference</h1><!-- doxytag: class="TXMPFiles" -->API for access to the "main" metadata in a file.
<a href="#_details">More...</a>
<p>
<code>#include <<a class="el" href="TXMPFiles_8hpp-source.html">TXMPFiles.hpp</a>></code>
<p>
<a href="classTXMPFiles-members.html">List of all members.</a><table border="0" cellpadding="0" cellspacing="0">
<tr><td></td></tr>
<tr><td colspan="2"><br><h2>Constructors and destructor</h2></td></tr>
<tr><td colspan="2">The default constructor initializes an object that is associated with no file. The alternate constructors call OpenFile. The destructor automatically calls CloseFile if necessary. <br><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="14f01e38454178578fd25fff6024fd54"></a><!-- doxytag: member="TXMPFiles::TXMPFiles" ref="14f01e38454178578fd25fff6024fd54" args="()" -->
</td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#14f01e38454178578fd25fff6024fd54">TXMPFiles</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The default constructor initializes an object that is associated with no file. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="5eaa92724cc82d933a32eff9c4636739"></a><!-- doxytag: member="TXMPFiles::~TXMPFiles" ref="5eaa92724cc82d933a32eff9c4636739" args="()" -->
virtual </td><td class="memItemRight" valign="bottom"><b>~TXMPFiles</b> () throw ()</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="36abe01988d4ca3939138e871c7b75e7"></a><!-- doxytag: member="TXMPFiles::TXMPFiles" ref="36abe01988d4ca3939138e871c7b75e7" args="(XMP_StringPtr filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0)" -->
</td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#36abe01988d4ca3939138e871c7b75e7">TXMPFiles</a> (<a class="el" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6">XMP_StringPtr</a> filePath, XMP_FileFormat format=kXMP_UnknownFile, <a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> openFlags=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">These alternate constructors call <code>OpenFile</code>. The second form is a trivial overload that calls the first form passing <code>filePath.c_str()</code>. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="f540b3ea689a6d7381dca4f52132a4ac"></a><!-- doxytag: member="TXMPFiles::TXMPFiles" ref="f540b3ea689a6d7381dca4f52132a4ac" args="(const tStringObj &filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0)" -->
</td><td class="memItemRight" valign="bottom"><b>TXMPFiles</b> (const tStringObj &filePath, XMP_FileFormat format=kXMP_UnknownFile, <a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> openFlags=0)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="cf343fb6771b482ca72d467233a6f920"></a><!-- doxytag: member="TXMPFiles::TXMPFiles" ref="cf343fb6771b482ca72d467233a6f920" args="(const TXMPFiles< tStringObj > &original)" -->
</td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#cf343fb6771b482ca72d467233a6f920">TXMPFiles</a> (const <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj > &original)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The copy constructor and assignment operator increment an internal reference count, they do not perform a deep copy. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="3f1483fcc92860460d3772216dfaef81"></a><!-- doxytag: member="TXMPFiles::operator=" ref="3f1483fcc92860460d3772216dfaef81" args="(const TXMPFiles< tStringObj > &rhs)" -->
void </td><td class="memItemRight" valign="bottom"><b>operator=</b> (const <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj > &rhs)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="d986c7b2e2d82eaef6cf6a33e9d09b65"></a><!-- doxytag: member="TXMPFiles::TXMPFiles" ref="d986c7b2e2d82eaef6cf6a33e9d09b65" args="(XMPFilesRef xmpFilesObj)" -->
</td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#d986c7b2e2d82eaef6cf6a33e9d09b65">TXMPFiles</a> (XMPFilesRef xmpFilesObj)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">The "ref" constructor and <code>GetInternalRef</code> serve the same purpose as their analogs in SXMPMeta, safely passing <code>SXMPFiles</code> references across DLL boundaries where the clients might have used different string types when instantiating <code><a class="el" href="classTXMPFiles.html">TXMPFiles</a></code>. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="311fc36fdf7270fe05b1c531cdbbd009"></a><!-- doxytag: member="TXMPFiles::GetInternalRef" ref="311fc36fdf7270fe05b1c531cdbbd009" args="()" -->
XMPFilesRef </td><td class="memItemRight" valign="bottom"><b>GetInternalRef</b> ()</td></tr>
<tr><td colspan="2"><br><h2>Public Member Functions</h2></td></tr>
<tr><td colspan="2"><div class="groupHeader">OpenFile, CloseFile, and related file-oriented operations</div></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#fcd21cfe5d6f13c648c5541e161919cb">OpenFile</a> (<a class="el" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6">XMP_StringPtr</a> filePath, XMP_FileFormat format=kXMP_UnknownFile, <a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> openFlags=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Open a file for metadata access. <a href="#fcd21cfe5d6f13c648c5541e161919cb"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#eca89170c7aa3e2d56e30bff04dd7927">CloseFile</a> (<a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> closeFlags=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Close an opened file. <a href="#eca89170c7aa3e2d56e30bff04dd7927"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#f9931d081cb19f98c81e41786030765b">GetFileInfo</a> (tStringObj *filePath=0, <a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> *openFlags=0, XMP_FileFormat *format=0, <a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> *handlerFlags=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get basic information about an opened file. <a href="#f9931d081cb19f98c81e41786030765b"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#7b86c130fdbd54b5ac158ec3fee93777">SetAbortProc</a> (XMP_AbortProc abortProc, void *abortArg)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Set the callback function used to check for a user signaled abort. <a href="#7b86c130fdbd54b5ac158ec3fee93777"></a><br></td></tr>
<tr><td colspan="2"><div class="groupHeader">Metadata Access Functions</div></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#42ca0bbc5ac66a8de1710e03a7ff17b3">GetXMP</a> (SXMPMeta *xmpObj=0, tStringObj *xmpPacket=0, XMP_PacketInfo *packetInfo=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Obtain the XMP. <a href="#42ca0bbc5ac66a8de1710e03a7ff17b3"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#4ea1eda39f803322e10b2a554ef8ab06">GetThumbnail</a> (XMP_ThumbnailInfo *tnailInfo)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Obtain the native thumbnail. <a href="#4ea1eda39f803322e10b2a554ef8ab06"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#d3f7babdc07c7de0d0cd9a3362b4710a">PutXMP</a> (const SXMPMeta &xmpObj)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Update the XMP. <a href="#d3f7babdc07c7de0d0cd9a3362b4710a"></a><br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#29a11a1539d6300da3fb4c7e9ea02bb6">CanPutXMP</a> (const SXMPMeta &xmpObj)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Determine if the XMP can be updated. <a href="#29a11a1539d6300da3fb4c7e9ea02bb6"></a><br></td></tr>
<tr><td colspan="2"><br><h2>Static Public Member Functions</h2></td></tr>
<tr><td colspan="2"><div class="groupHeader">Initialization and termination</div></td></tr>
<tr><td colspan="2"><div class="groupText"><code>SXMPFiles</code> must be initialized before use and may be terminated when done. <br><br></div></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="6e521c034728b59ab55213a9d8203d1e"></a><!-- doxytag: member="TXMPFiles::GetVersionInfo" ref="6e521c034728b59ab55213a9d8203d1e" args="(XMP_VersionInfo *versionInfo)" -->
static void </td><td class="memItemRight" valign="bottom"><b>GetVersionInfo</b> (XMP_VersionInfo *versionInfo)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="0874bbbf41c9490abfb613bfe297327d"></a><!-- doxytag: member="TXMPFiles::Initialize" ref="0874bbbf41c9490abfb613bfe297327d" args="()" -->
static bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#0874bbbf41c9490abfb613bfe297327d">Initialize</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight"><code>Initialize</code> must be called before using <code>SXMPFiles</code>. It returns a Boolean success/failure value. <br></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="794e1830a84a6328eaa1995ba5aa6874"></a><!-- doxytag: member="TXMPFiles::Initialize" ref="794e1830a84a6328eaa1995ba5aa6874" args="(XMP_OptionBits options)" -->
static bool </td><td class="memItemRight" valign="bottom"><b>Initialize</b> (<a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> options)</td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="anchor" name="1e8de80c252b60b332dc4bc524139fd8"></a><!-- doxytag: member="TXMPFiles::Terminate" ref="1e8de80c252b60b332dc4bc524139fd8" args="()" -->
static void </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#1e8de80c252b60b332dc4bc524139fd8">Terminate</a> ()</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight"><code>Terminate</code> may be called when done using <code>SXMPFiles</code>. It deallocates global data structures created by <code>Initialize</code>. <br></td></tr>
<tr><td colspan="2"><div class="groupHeader">Static Functions</div></td></tr>
<tr><td class="memItemLeft" nowrap align="right" valign="top">static bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classTXMPFiles.html#6ac78e3c7286ca8dcb41eaa007aa00e8">GetFormatInfo</a> (XMP_FileFormat format, <a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> *handlerFlags=0)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Determine the supported features for a given file format. <a href="#6ac78e3c7286ca8dcb41eaa007aa00e8"></a><br></td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
<h3>template<class tStringObj><br>
class TXMPFiles< tStringObj ></h3>
API for access to the "main" metadata in a file.
<p>
<code><a class="el" href="classTXMPFiles.html">TXMPFiles</a></code> provides the API for the Adobe XMP Toolkit's File Handler component. This provides convenient access to the main, or document level, XMP for a file. The general model is to open a file, read and write the metadata, then close the file. While open, portions of the file might be maintained in RAM data structures. Memory usage can vary considerably depending on file format and access options. The file may be opened for read-only or read-write access, with typical exclusion for both modes.<p>
Errors result in the throw of an <code>XMPError</code> exception.<p>
The template is instantiated with a string object class. This allows a clean implementation that provides two major benefits: output string storage is fully owned by the client and access is fully thread safe. The template parameter, class <code>tStringObj</code>, is described in the XMP.hpp umbrella header.<p>
To use <a class="el" href="classTXMPFiles.html">TXMPFiles</a> define TXMP_STRING_TYPE and XMP_INCLUDE_XMPFILES, then include the XMP.hpp umbrella header: <div class="fragment"><pre class="fragment"><span class="preprocessor"> #define TXMP_STRING_TYPE std::string</span>
<span class="preprocessor"></span><span class="preprocessor"> #define XMP_INCLUDE_XMPFILES 1</span>
<span class="preprocessor"> #include "XMP.hpp"</span>
</pre></div>
<p>
<hr><h2>Member Function Documentation</h2>
<a class="anchor" name="6ac78e3c7286ca8dcb41eaa007aa00e8"></a><!-- doxytag: member="TXMPFiles::GetFormatInfo" ref="6ac78e3c7286ca8dcb41eaa007aa00e8" args="(XMP_FileFormat format, XMP_OptionBits *handlerFlags=0)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class tStringObj> </div>
<table class="memname">
<tr>
<td class="memname">static bool <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj >::GetFormatInfo </td>
<td>(</td>
<td class="paramtype">XMP_FileFormat </td>
<td class="paramname"> <em>format</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> * </td>
<td class="paramname"> <em>handlerFlags</em> = <code>0</code></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td width="100%"><code> [static]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Determine the supported features for a given file format.
<p>
The supported features can vary quite a bit among file formats, depending on both the general capabilities of the format and the implementation of the handler for that format.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>format</em> </td><td>The format whose support flags are desired.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>handlerFlags</em> </td><td>A set of option bits showing the support for this format:</td></tr>
</table>
</dl>
<ul>
<li>kXMPFiles_CanInjectXMP - Can inject first-time XMP into an existing file. </li>
<li>kXMPFiles_CanExpand - Can expand XMP or other metadata in an existing file. </li>
<li>kXMPFiles_CanRewrite - Can copy one file to another, writing new metadata. </li>
<li>kXMPFiles_CanReconcile - Supports reconciliation between XMP and other forms. </li>
<li>kXMPFiles_AllowsOnlyXMP - Allows access to just the XMP, ignoring other forms. </li>
<li>kXMPFiles_ReturnsRawPacket - File handler returns raw XMP packet information and string. </li>
<li>kXMPFiles_ReturnsTNail - File handler returns native thumbnail information.</li>
</ul>
The kXMPFiles_AllowsOnlyXMP flag is only meaningful if kXMPFiles_CanReconcile is set.<p>
If kXMPFiles_ReturnsRawPacket is set, the returned packet information might have an offset of -1 to indicate an unknown offset. While all file handlers should be able to return the raw packet, some might not know the offset of the packet within the file. This is typical in cases where external libraries are used. These cases might not even allow return of the raw packet.<p>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>Returns true if the format has explicit "smart" support. Returns false if the format is handled by the default packet scanning plus heuristics. </dd></dl>
</div>
</div><p>
<a class="anchor" name="fcd21cfe5d6f13c648c5541e161919cb"></a><!-- doxytag: member="TXMPFiles::OpenFile" ref="fcd21cfe5d6f13c648c5541e161919cb" args="(XMP_StringPtr filePath, XMP_FileFormat format=kXMP_UnknownFile, XMP_OptionBits openFlags=0)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class tStringObj> </div>
<table class="memname">
<tr>
<td class="memname">bool <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj >::OpenFile </td>
<td>(</td>
<td class="paramtype"><a class="el" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6">XMP_StringPtr</a> </td>
<td class="paramname"> <em>filePath</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">XMP_FileFormat </td>
<td class="paramname"> <em>format</em> = <code>kXMP_UnknownFile</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> </td>
<td class="paramname"> <em>openFlags</em> = <code>0</code></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Open a file for metadata access.
<p>
Opens a file for the requested forms of metadata access. Opening the file at a minimum causes the raw XMP packet to be read from the file. If the file handler supports legacy metadata reconciliation then legacy metadata will also be read, unless kXMPFiles_OpenOnlyXMP is passed. If the file handler supports native thumbnails and kXMPFiles_OpenCacheTNail is passed then the native thumbnail will also be cached.<p>
If the file is opened for read-only access (passing kXMPFiles_OpenForRead), then the disk file itself will be closed after reading the data from it. The XMPFiles object will not be "closed" though, it is still necessary to call CloseFile when finished using it. Other methods (GetXMP, etc.) can only be used between the OpenFile and CloseFile calls. The XMPFiles destructor will not call CloseFile, any pending updates will be lost.<p>
If the file is opened for update (passing kXMPFiles_OpenForUpdate), then the disk file remains open until CloseFile is called. The disk file is only updated once, when Close file is called, no matter how many calls are made to PutXMP.<p>
Ideally the XMP is not parsed and legacy reconciliation is not performed until GetXMP is called. This is not guaranteed though, specific file handlers might do earlier parsing of the XMP. This delayed parsing and the early disk file close for read-only access are optimizations to help clients implementing file browsers. They can access the file briefly and possibly display a thumbnail, then postpone more expensive XMP processing until later.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>filePath</em> </td><td>The UTF-8 path for the file, appropriate for the local OS. Overloads are declared to pass the path as either a "const char *" or a string object.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>format</em> </td><td>The format of the file. If the format is unknown pass <code>kXMP_UnknownFile</code> and the format will be determined from the file content. The first handler to check will be guessed from the file's extension. Passing any other format value is generally just a hint about what file handler to try first (instead of the one based on the extension). If the kXMPFiles_OpenStrictly is set, then any format other than kXMP_UnknownFile requires that the file actually be that format, an exception is thrown if not.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>openFlags</em> </td><td>A set of option bits describing the desired access. By default (zero) the file is opened for read-only access and the format handler decides on the level of reconciliation that will be performed. By default a best effort will be made to locate the correct XMP and to reconcile XMP with other forms (if reconciliation is done). The option <code>kXMPFiles_OpenStrictly</code> may be used to force more strict rules, resulting is exceptions for errors. The definition of strictness is specific to each handler, there may be no difference.</td></tr>
</table>
</dl>
The defined openFlag bits are:<p>
<ul>
<li>kXMPFiles_OpenForRead - Open for read-only access. </li>
<li>kXMPFiles_OpenForUpdate - Open for reading and writing. </li>
<li>kXMPFiles_OpenOnlyXMP - Only the XMP is wanted, no reconciliation. </li>
<li>kXMPFiles_OpenCacheTNail - Cache thumbnail if possible, GetThumbnail will be called. </li>
<li>kXMPFiles_OpenStrictly - Be strict about locating XMP and reconciling with other forms. </li>
<li>kXMPFiles_OpenUseSmartHandler - Require the use of a smart handler. </li>
<li>kXMPFiles_OpenUsePacketScanning - Force packet scanning, don't use a smart handler.</li>
</ul>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>Returns true if the file is succesfully opened and attached to a file handler. Returns false for "anticipated" problems, e.g. passing kXMPFiles_OpenUseSmartHandler but not having an appropriate smart handler. Throws an exception for serious problems. </dd></dl>
</div>
</div><p>
<a class="anchor" name="eca89170c7aa3e2d56e30bff04dd7927"></a><!-- doxytag: member="TXMPFiles::CloseFile" ref="eca89170c7aa3e2d56e30bff04dd7927" args="(XMP_OptionBits closeFlags=0)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class tStringObj> </div>
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj >::CloseFile </td>
<td>(</td>
<td class="paramtype"><a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> </td>
<td class="paramname"> <em>closeFlags</em> = <code>0</code> </td>
<td> ) </td>
<td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Close an opened file.
<p>
Performs any necessary output to the file and closes it. Files that are opened for update are written to only when closing.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>closeFlags</em> </td><td>A set of bit flags for optional closing actions.</td></tr>
</table>
</dl>
The defined closeFlags bits are:<p>
<ul>
<li>kXMPFiles_UpdateSafely - Write into a temporary file then swap for crash safety. </li>
</ul>
</div>
</div><p>
<a class="anchor" name="f9931d081cb19f98c81e41786030765b"></a><!-- doxytag: member="TXMPFiles::GetFileInfo" ref="f9931d081cb19f98c81e41786030765b" args="(tStringObj *filePath=0, XMP_OptionBits *openFlags=0, XMP_FileFormat *format=0, XMP_OptionBits *handlerFlags=0)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class tStringObj> </div>
<table class="memname">
<tr>
<td class="memname">bool <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj >::GetFileInfo </td>
<td>(</td>
<td class="paramtype">tStringObj * </td>
<td class="paramname"> <em>filePath</em> = <code>0</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> * </td>
<td class="paramname"> <em>openFlags</em> = <code>0</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">XMP_FileFormat * </td>
<td class="paramname"> <em>format</em> = <code>0</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> * </td>
<td class="paramname"> <em>handlerFlags</em> = <code>0</code></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Get basic information about an opened file.
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>filePath</em> </td><td>If not null, returns the path passed to OpenFile.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>openFlags</em> </td><td>If not null, returns the flags passed to OpenFile.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>format</em> </td><td>If not null, returns the format of the file.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>handlerFlags</em> </td><td>If not null, returns the handler's capability flags.</td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>Returns true if a file is opened, false otherwise. This notion of "open" really means that OpenFile has been called but CloseFile has not. The actual disk file might be closed in the host file system sense, as explained for OpenFile. </dd></dl>
</div>
</div><p>
<a class="anchor" name="7b86c130fdbd54b5ac158ec3fee93777"></a><!-- doxytag: member="TXMPFiles::SetAbortProc" ref="7b86c130fdbd54b5ac158ec3fee93777" args="(XMP_AbortProc abortProc, void *abortArg)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class tStringObj> </div>
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj >::SetAbortProc </td>
<td>(</td>
<td class="paramtype">XMP_AbortProc </td>
<td class="paramname"> <em>abortProc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"> <em>abortArg</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Set the callback function used to check for a user signaled abort.
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>abortProc</em> </td><td>The callback function used to check for a user signaled abort. It will be called periodically to allow an abort of time consuming operations. The abort results in an exception being thrown. The callback function should return true to signal an abort.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>abortArg</em> </td><td>An argument passed to the callback function. </td></tr>
</table>
</dl>
</div>
</div><p>
<a class="anchor" name="42ca0bbc5ac66a8de1710e03a7ff17b3"></a><!-- doxytag: member="TXMPFiles::GetXMP" ref="42ca0bbc5ac66a8de1710e03a7ff17b3" args="(SXMPMeta *xmpObj=0, tStringObj *xmpPacket=0, XMP_PacketInfo *packetInfo=0)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class tStringObj> </div>
<table class="memname">
<tr>
<td class="memname">bool <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj >::GetXMP </td>
<td>(</td>
<td class="paramtype">SXMPMeta * </td>
<td class="paramname"> <em>xmpObj</em> = <code>0</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">tStringObj * </td>
<td class="paramname"> <em>xmpPacket</em> = <code>0</code>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">XMP_PacketInfo * </td>
<td class="paramname"> <em>packetInfo</em> = <code>0</code></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Obtain the XMP.
<p>
<code>GetXMP</code> is used to obtain the parsed XMP, and/or the raw XMP packet, and/or information about the raw XMP packet. If all parameters are null it simply tells if XMP is present or not. The options provided when the file was opened determine if reconciliation is done with other forms of metadata.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>xmpObj</em> </td><td>If not null, returns the parsed XMP.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>xmpPacket</em> </td><td>If not null, returns the raw XMP packet as stored in the file. The encoding of the packet is given in the packetInfo. The string will be empty if the low level file handler does not provide the raw packet.</td></tr>
<tr><td valign="top"></td><td valign="top"><em>packetInfo</em> </td><td>If not null, returns the location and form of the raw XMP in the file. The charForm and writeable flag reflect the raw XMP in the file. The parsed XMP property values are always UTF-8. The writeable flag is taken from the packet trailer, it is only relevant for "format ignorant" writing.</td></tr>
</table>
</dl>
<dl class="note" compact><dt><b>Note:</b></dt><dd>The packetInfo struct always reflects the state of the XMP in the file. The offset, length, and character form will not change as a result of calling <code>PutXMP</code> unless the file is also written.<p>
Some file handlers might not return location or contents of the raw packet string. Check the <code>kXMPFiles_ReturnsRawPacket</code> bit returned by GetFormatInfo if you depend on this. If the low level file handler does not provide the raw packet location then the offset and length will both be 0, the charForm will be UTF-8, and the writeable flag will be false.</dd></dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>Returns true if the file has XMP, false otherwise. </dd></dl>
</div>
</div><p>
<a class="anchor" name="4ea1eda39f803322e10b2a554ef8ab06"></a><!-- doxytag: member="TXMPFiles::GetThumbnail" ref="4ea1eda39f803322e10b2a554ef8ab06" args="(XMP_ThumbnailInfo *tnailInfo)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class tStringObj> </div>
<table class="memname">
<tr>
<td class="memname">bool <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj >::GetThumbnail </td>
<td>(</td>
<td class="paramtype">XMP_ThumbnailInfo * </td>
<td class="paramname"> <em>tnailInfo</em> </td>
<td> ) </td>
<td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Obtain the native thumbnail.
<p>
<code>GetThumbnail</code> is used to obtain native thumbnail information, if the associated file handler supports that and the thumbnail was cached by OpenFile. This requires that kXMPFiles_OpenCacheTNail be passed to OpenFile. The tnailInfo output pointer can be null, in which case GetThumbnail will simply tell if a recognized native thumbnail is present.<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>tnailInfo</em> </td><td>If not null, returns information about a recognized native thumbnail, and some related information about the primary image if appropriate.</td></tr>
</table>
</dl>
<dl class="note" compact><dt><b>Note:</b></dt><dd>The returned thumbnail information can be incomplete. What gets returned can depend on the file format, the file handler's capabilities, and the specific file content.</dd></dl>
<ul>
<li>The fullHeight, fullWIdth, and fullOrientation fields are only meaningful for image files. They are not meaningful for multi-page files such as PDF or InDesign, for dynamic audio or video files, etc. The fields will be zero if not meaningful or not determined.</li>
</ul>
<ul>
<li>The tnailImage and tnailSize fields might be zero even if a "recognized" thumbnail is present. Being recognized means only that the handler has determined that the file does contain a native thumbnail. The thumbnail data might be of a format that the file handler cannot (or does not) return a single contiguous block of thumbnail data. A possible case of this is a TIFF uncompressed thumbnail, the handler might not have logic to gather the various disjoint pieces of the thumbnail from the overall TIFF stream.</li>
</ul>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>Returns true if a recognized native thumbnail is presentand the thumbnail was cached by OpenFile. This requires that kXMPFiles_OpenCacheTNail be passed to OpenFile. Note that GetThumbnail can return true but still not return an actual thumbnail image, see the above note. </dd></dl>
</div>
</div><p>
<a class="anchor" name="d3f7babdc07c7de0d0cd9a3362b4710a"></a><!-- doxytag: member="TXMPFiles::PutXMP" ref="d3f7babdc07c7de0d0cd9a3362b4710a" args="(const SXMPMeta &xmpObj)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class tStringObj> </div>
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj >::PutXMP </td>
<td>(</td>
<td class="paramtype">const SXMPMeta & </td>
<td class="paramname"> <em>xmpObj</em> </td>
<td> ) </td>
<td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Update the XMP.
<p>
<code>PutXMP</code> supplies new XMP for the file. However, the file is not actully written until closed. The options provided when the file was opened determine if reconciliation is done with other forms of metadata. Overloads are provided to pass the XMP as an XMP object, a string object, or a "const char *" plus length.
</div>
</div><p>
<a class="anchor" name="29a11a1539d6300da3fb4c7e9ea02bb6"></a><!-- doxytag: member="TXMPFiles::CanPutXMP" ref="29a11a1539d6300da3fb4c7e9ea02bb6" args="(const SXMPMeta &xmpObj)" -->
<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template<class tStringObj> </div>
<table class="memname">
<tr>
<td class="memname">bool <a class="el" href="classTXMPFiles.html">TXMPFiles</a>< tStringObj >::CanPutXMP </td>
<td>(</td>
<td class="paramtype">const SXMPMeta & </td>
<td class="paramname"> <em>xmpObj</em> </td>
<td> ) </td>
<td width="100%"></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>
Determine if the XMP can be updated.
<p>
<code>CanPutXMP</code> determines if the XMP can (probably) be updated. The provided XMP is only used to obtain the length of the serialized packet. The new XMP is not kept, calling this will not cause the file to be written when closed. Overloads are provided to pass the XMP as an XMP object, a string object, or a "const char *" plus length. This is implemented roughly as:<p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">bool</span> <a class="code" href="classTXMPFiles.html#29a11a1539d6300da3fb4c7e9ea02bb6">CanPutXMP</a> ( <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6">XMP_StringPtr</a> xmpPacket )
{
XMP_FileFormat format;
this-><a class="code" href="classTXMPFiles.html#f9931d081cb19f98c81e41786030765b">GetFileInfo</a> ( 0, &format, 0 );
<a class="code" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> formatFlags;
<a class="code" href="classTXMPFiles.html#6ac78e3c7286ca8dcb41eaa007aa00e8">GetFormatInfo</a> ( format, &formatFlags );
<span class="keywordflow">if</span> ( (formatFlags & kXMPFiles_CanInjectXMP) && (formatFlags & kXMPFiles_CanExpand) ) <span class="keywordflow">return</span> <span class="keyword">true</span>;
XMP_PacketInfo packetInfo;
<span class="keywordtype">bool</span> hasXMP = this-><a class="code" href="classTXMPFiles.html#42ca0bbc5ac66a8de1710e03a7ff17b3">GetXMP</a> ( 0, 0, &packetInfo );
<span class="keywordflow">if</span> ( ! hasXMP ) {
<span class="keywordflow">if</span> ( formatFlags & kXMPFiles_CanInjectXMP ) <span class="keywordflow">return</span> <span class="keyword">true</span>;
} <span class="keywordflow">else</span> {
<span class="keywordflow">if</span> ( (formatFlags & kXMPFiles_CanExpand) ||
(packetInfo.length >= strlen(xmpPacket)) ) <span class="keywordflow">return</span> <span class="keyword">true</span>;
}
<span class="keywordflow">return</span> <span class="keyword">false</span>;
}
</pre></div>
</div>
</div><p>
<hr>The documentation for this class was generated from the following file:<ul>
<li><a class="el" href="TXMPFiles_8hpp-source.html">TXMPFiles.hpp</a></ul>
<hr size="1"><address style="align: right;"><small>Generated on Thu May 3 14:54:58 2007 for Adobe XMP Toolkit by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.1 </small></address>
</body>
</html>
|
