Debian Codegraph @

core/libs/dngwriter/extra/xmp_sdk/public/include/TXMPDocOps.hpp

raw
1 #if AdobePrivate // The whole class is private for now.
2
3 #ifndef __TXMPDocOps_hpp__
4 #define __TXMPDocOps_hpp__ 1
5
6 #if ( ! __XMP_hpp__ )
7 #error "Do not directly include, use XMP.hpp"
8 #endif
9
10 // =================================================================================================
11 // Copyright Adobe
12 // Copyright 2002-2008 Adobe
13 // All Rights Reserved
14 //
15 // NOTICE: Adobe permits you to use, modify, and distribute this file in accordance with the terms
16 // of the Adobe license agreement accompanying it. If you have received this file from a source other
17 // than Adobe, then your use, modification, or distribution of it requires the prior written permission
18 // of Adobe.
19 // =================================================================================================
20
21 #if AdobePrivate
22 // =================================================================================================
23 // Change history
24 // ==============
25 //
26 // Writers:
27 // AWL Alan Lillich
28 //
29 // mm-dd-yy who Description of changes, most recent on top
30 //
31 // 07-22-09 AWL 5.0-c048 [2381643] Properly fix memory leaks from XMPDocOps::Clone.
32 // 07-17-09 AWL [2381643] Fix memory leaks from XMPDocOps::Clone (client-only fix).
33 // 05-21-09 AWL 5.0-c032 Revamp glue again to pass SetClientString with each function.
34 //
35 // 04-24-08 AWL 4.2.2-c051 [1765983] Add SXMPDocOps::IsDirty overload to return reason mask.
36 //
37 // 03-04-08 AWL Add Doxygen API comments.
38 // 02-22-08 AWL 4.2-c041 Add routines to SXMPDocOps - EnsureIDsExist, IsDirty, Clone, and GetMetaRef.
39 // 12-10-07 AWL Change name of fileType params to mimeType.
40 // 12-03-07 AWL 4.2-c028 Change file type parameters in XMPDocOps from XMP_FileFormat enum to a MIME string.
41 // 11-12-07 AWL 4.2-c026 More progress implementing XMPDocOps.
42 // 11-07-07 AWL 4.2-c025 More progress implementing XMPDocOps.
43 // 10-31-07 AWL 4.2-c023 Add new class XMPDocOps.
44 //
45 // =================================================================================================
46 #endif // AdobePrivate
47
48 // =================================================================================================
49 /// \file TXMPDocOps.hpp
50 /// \brief Services to support application "document operations".
51 ///
52 /// @details\c TXMPDocOps is the template class providing services in support of common operations to
53 /// application documents. These services implement XMP policy that needs to be consistent across
54 /// applications. The template must be instantiated with a string class such as \c std::string. See
55 /// the instructions in XMP.hpp, and the Overview for a discussion of the overall architecture of
56 /// the XMP API.
57 // =================================================================================================
58
59 // =================================================================================================
60 /// \class TXMPDocOps TXMPDocOps.hpp
61 /// @brief Services to support application "document operations".
62 ///
63 /// \c TXMPDocOps is a template class which must be instantiated with a string class such as
64 /// \c std::string. See the instructions in XMP.hpp, and the Overview for a discussion of the overall
65 /// architecture of the XMP API.
66 ///
67 /// @details This class defines helper functions that support common behavior for high level operations on
68 /// application documents. Common examples are the user menu actions \c File/New, \c File/Open,
69 /// \c File/Save, \c File/SaveAs, etc. Applications must keep a per-document \c SXMPDocOps object
70 /// alongside their \c SXMPMeta object, document level state is kept by the \c SXMPDocOps object.
71 // =================================================================================================
72
73 #include <vector>
74 #if XMP_AndroidBuild
75 #include "jni.h"
76 #endif
77
78 template <class tStringObj> class TXMPDocOps {
79
80 public:
81
82 // ============================================================================================
83 /// \name Constructors, destructor, assignment
84 /// @{
85 ///
86 /// ...
87
88 // -----------------------------------------------------------------
89 /// @brief Default constructor initializes an empty document object.
90
91 TXMPDocOps();
92
93 // ---------------------------------------------------------------------------------------------
94 /// @brief Copy constructor
95 ///
96 /// Increments an internal reference count but does not perform a deep copy.
97 ///
98 /// @param original The existing \c TXMPDocOps object to copy. The new \c TXMPDocOps object returned via original.
99 ///
100 TXMPDocOps ( const TXMPDocOps<tStringObj> & original );
101
102 // ---------------------------------------------------------------------------------------------
103 /// @brief Reconstruct a \c TXMPDocOps object from an internal reference.
104 ///
105 /// @details This constructor creates a new \c TXMPDocOps object that refers to the underlying reference
106 /// object of an existing \c TXMPDocOps object. Use to safely pass \c SXMPDocOps references across
107 /// DLL boundaries.
108 ///
109 /// @param _xmpDocOpsRef The underlying reference object, obtained from some other XMP object
110 /// with \c TXMPDocOps::GetInternalRef().
111 ///
112
113 TXMPDocOps ( XMPDocOpsRef _xmpDocOpsRef );
114
115 // ---------------------------------------------------------------------------------------------
116 /// @brief Destructor; typical virtual destructor.
117
118 virtual ~TXMPDocOps() throw();
119
120 // ---------------------------------------------------------------------------------------------
121 /// @brief Assignment operator
122 ///
123 /// @details Increments an internal reference count but does not perform a deep copy. The two client
124 /// objects will both refer to the same internal object.
125 ///
126 /// @param rhs The existing \c TXMPDocOps object.
127
128 void operator= ( const TXMPDocOps<tStringObj> & rhs );
129
130 // ---------------------------------------------------------------------------------------------
131 /// @brief GetInternalRef() retrieves an internal reference that can be safely passed across DLL
132 /// boundaries and reconstructed.
133 ///
134 /// @details Use with the reconstruction constructor to safely pass \c SXMPDocOps references across DLL
135 /// boundaries where the clients might have used different string types when instantiating
136 /// \c TXMPDocOps.
137 ///
138 /// @return The internal reference.
139 ///
140 /// @see \c TXMPMeta::GetInternalRef() for usage.
141
142 XMPDocOpsRef GetInternalRef();
143
144 /// @}
145
146 // ============================================================================================
147 /// \name Static functions
148 /// @{
149 ///
150 /// Static utility functions.
151
152 // ---------------------------------------------------------------------------------------------
153 /// @brief \c SetAppName() sets the application's name.
154 ///
155 /// @details Use \c SetAppName to provide the application name which is used to set \c xmp:CreatorTool
156 /// property and the \c stEvt:softwareAgent field of \c xmpMM:History entries.
157 ///
158 /// @param in_appName The application's name for use in the \c xmp:CreatorTool property.
159
160 static void SetAppName ( XMP_StringPtr in_appName );
161
162 // ---------------------------------------------------------------------------------------------
163 /// @brief \c CreateID() creates a new GUID string.
164 ///
165 /// @details Generates a new GUID and formats it as a string with the given prefix. It is recommended
166 /// that the prefix end with a colon and follow W3C URI scheme syntax.
167 ///
168 /// @param out_xmpID The string to received the value of the generated GUID.
169 /// @param prefix The prefix for the generated GUID.
170
171 static void CreateID ( tStringObj * out_xmpID, XMP_StringPtr prefix = "xmp.id:" );
172
173 /// @}
174
175 // ============================================================================================
176 /// \name General document manipulation
177 /// @{
178 ///
179 /// @details These are general operations intended to help applications maintain standard XMP properties.
180 /// The basic model is that an application's document object would contain both an \c SXMPMeta
181 /// object and an \c SXMPDocOps object. These functions define the association of those, and
182 /// perform standard operations on the \c SXMPMeta for typical user actions like New, Open,
183 /// Save, or SaveAs.
184
185 // ---------------------------------------------------------------------------------------------
186 /// @brief \c NewXMP() initializes the \c SXMPDocOps and \c SXMPMeta objects for a new document.
187 ///
188 /// @details An application should call \c NewXMP when it creates a new document to perform standard XMP
189 /// initialization. This includes setting \c dc:format to the MIME type (if provided), setting
190 /// \c xmp:CreatorTool to the application name (if provided via \c SetAppName), setting
191 /// \c xmp:CreateDate to the current local date-time, and noting that the entire document has
192 /// changed (see \c NoteChange).
193 ///
194 /// @param inout_docXMP The SXMPMeta object associated with the application document. This should
195 /// be an empty SXMPMeta object. The application can set other properties after calling \c NewXMP.
196 ///
197 /// @param in_mimeType Optional MIME type string, used to set \c dc:format.
198 ///
199 /// @param in_options There are no currently defined options.
200
201 void NewXMP ( TXMPMeta<tStringObj> * inout_docXMP,
202 XMP_StringPtr in_mimeType = "",
203 XMP_OptionBits in_options = kXMP_NoOptions );
204
205 // ---------------------------------------------------------------------------------------------
206 /// @brief \c OpenXMP() performs standard normalization when opening existing documents.
207 ///
208 /// @details An application should call \c OpenXMP when opening an existing document, after reading any
209 /// existing XMP. The primary role of \c OpenXMP is to detect changes by other "ignorant"
210 /// applications, and to prepare the \c SXMPDocOps object for editing operations.
211 ///
212 /// @param inout_docXMP The SXMPMeta object associated with the existing document. This should
213 /// be initialized with the XMP from the document, if any.
214 ///
215 /// @param in_mimeType Optional MIME type string, used to detect changes and to set \c dc:format.
216 /// If provided and different from an existing dc:format value, an xmpMM:History entry is
217 /// appended to report the change in format.
218 ///
219 /// @param in_options There are no currently defined options.
220
221 void OpenXMP ( TXMPMeta<tStringObj> * inout_docXMP,
222 XMP_StringPtr in_mimeType,
223 XMP_OptionBits in_options = kXMP_NoOptions );
224
225 // ---------------------------------------------------------------------------------------------
226 /// @brief \c OpenXMP() performs standard normalization when opening existing documents.
227 ///
228 /// @details This overload of \c OpenXMP adds an optional file path parameter.
229 ///
230 /// @param inout_docXMP The SXMPMeta object associated with the existing document. This should
231 /// be initialized with the XMP from the document, if any.
232 ///
233 /// @param in_mimeType Optional MIME type string, used to detect changes and to set \c dc:format.
234 /// If provided and different from an existing dc:format value, an xmpMM:History entry is
235 /// appended to report the change in format.
236 ///
237 /// @param in_filePath An optional disk path of the file, should be an absolute path. Saved for
238 /// use in \c PrepareForSave to detect SaveAs operations to a new location.
239 ///
240 /// @param in_options There are no currently defined options.
241
242 void OpenXMP ( TXMPMeta<tStringObj> * inout_docXMP,
243 XMP_StringPtr in_mimeType,
244 XMP_StringPtr in_filePath,
245 XMP_OptionBits in_options = kXMP_NoOptions );
246
247 // ---------------------------------------------------------------------------------------------
248 /// @brief \c OpenXMP() performs standard normalization when opening existing documents.
249 ///
250 /// @details This overload of \c OpenXMP adds an optional file modification time parameter.
251 ///
252 /// @param inout_docXMP The SXMPMeta object associated with the existing document. This should
253 /// be initialized with the XMP from the document, if any.
254 ///
255 /// @param in_mimeType Optional MIME type string, used to detect changes and to set \c dc:format.
256 /// If provided and different from an existing dc:format value, an xmpMM:History entry is
257 /// appended to report the change in format.
258 ///
259 /// @param in_filePath An optional disk path of the file, should be an absolute path. Saved for
260 /// use in \c PrepareForSave to detect SaveAs operations to a new location.
261 ///
262 /// @param in_fileModTime An optional file modification time, presumably from the file system.
263 /// This is compared with the timestamp in the most recent "created" or "saved" \c xmpMM:History
264 /// entry. If this time is newer, presumably the file has been modified by an "ignorant"
265 /// application and a "modified" \c xmpMM:History entry is appended. See \c PrepareForSave.
266 ///
267 /// @param in_options There are no currently defined options.
268
269 void OpenXMP ( TXMPMeta<tStringObj> * inout_docXMP,
270 XMP_StringPtr in_mimeType,
271 XMP_StringPtr in_filePath,
272 XMP_DateTime & in_fileModTime,
273 XMP_OptionBits in_options = kXMP_NoOptions );
274
275 // ---------------------------------------------------------------------------------------------
276 /// @brief \c BranchXMP() is used to initialize a derived document's XMP.
277 ///
278 /// @details \c BranchXMP() is used to initialize a derived document's XMP. It should be called when
279 /// deriving one document from another, for example when doing a Save As operation. It should be
280 /// called on the source document:
281 /// {code}
282 /// sourceDoc.BranchXMP ( &derivedDoc, &derivedXMP, ... );
283 /// {code}
284 ///
285 /// @param inout_derivedDoc The SXMPDocOps object for the derived document. Can be the same as
286 /// the source document, in which case inout_derivedXMP must be null or match the source.
287 ///
288 /// @param inout_derivedXMP The XMP to be associated with the derived document. Must not be null
289 /// unless inout_derivedDoc matches the source document ("this").
290 ///
291 /// @param in_mimeType Optional MIME type string, used to detect changes and to set \c dc:format.
292 /// If provided and different from an existing dc:format value, an xmpMM:History entry is
293 /// appended to report the change in format.
294 ///
295 /// @param in_options There are no currently defined options.
296
297 void BranchXMP ( TXMPDocOps<tStringObj> * inout_derivedDoc,
298 TXMPMeta<tStringObj> * inout_derivedXMP,
299 XMP_StringPtr in_mimeType,
300 XMP_OptionBits in_options = kXMP_NoOptions );
301
302 // ---------------------------------------------------------------------------------------------
303 /// @brief \c PrepareForSave() is used to finalize the XMP in preparation for saving the document.
304 ///
305 /// @details \c PrepareForSave() is used to finalize the XMP in preparation for saving the document. It
306 /// makes sure that standard IDs exist, sets various date properties, appends appropriate
307 /// history, etc. It does nothing though if the document is unchanged (not dirty).
308 ///
309 /// @param in_mimeType Optional MIME type string, used to detect changes and to set \c dc:format.
310 /// If provided and different from an existing dc:format value, an xmpMM:History entry is
311 /// appended to report the change in format.
312 ///
313 /// @param in_options There are no currently defined options.
314
315 void PrepareForSave ( XMP_StringPtr in_mimeType,
316 XMP_OptionBits in_options = kXMP_NoOptions );
317
318 // ---------------------------------------------------------------------------------------------
319 /// @brief \c PrepareForSave() is used to finalize the XMP in preparation for saving the document.
320 ///
321 /// @details This overload of \c PrepareForSave adds an optional file path parameter.
322 ///
323 /// @param in_mimeType Optional MIME type string, used to detect changes and to set \c dc:format.
324 /// If provided and different from an existing dc:format value, an xmpMM:History entry is
325 /// appended to report the change in format.
326 ///
327 /// @param in_filePath An optional disk path of the file, should be an absolute path. Used to
328 /// detect SaveAs operations to a new location.
329 ///
330 /// @param in_options There are no currently defined options.
331
332 void PrepareForSave ( XMP_StringPtr in_mimeType,
333 XMP_StringPtr in_filePath,
334 XMP_OptionBits in_options = kXMP_NoOptions );
335
336 // ---------------------------------------------------------------------------------------------
337 /// @brief \c PrepareForSave() is used to finalize the XMP in preparation for saving the document.
338 ///
339 /// @details This overload of \c PrepareForSave adds an optional file modification time parameter.
340 ///
341 /// @param in_mimeType Optional MIME type string, used to detect changes and to set \c dc:format.
342 /// If provided and different from an existing dc:format value, an xmpMM:History entry is
343 /// appended to report the change in format.
344 ///
345 /// @param in_filePath An optional disk path of the file, should be an absolute path. Used to
346 /// detect SaveAs operations to a new location.
347 ///
348 /// @param in_fileModTime Optional file modification time. Saved in the history for later use to
349 /// detect changes by XMP-unaware applications.
350 ///
351 /// @param in_options There are no currently defined options.
352
353 void PrepareForSave ( XMP_StringPtr in_mimeType,
354 XMP_StringPtr in_filePath,
355 XMP_DateTime & in_fileModTime,
356 XMP_OptionBits in_options = kXMP_NoOptions );
357
358 // ---------------------------------------------------------------------------------------------
359 /// @brief \c NoteChange() is used to report changes to some portion of a document.
360 ///
361 /// @details \c NoteChange() is used to report changes to some portion of a document. This information is
362 /// later recorded in the history by \c PrepareForSave.
363 ///
364 /// @param in_part A string denoting the changed portion of the file. The syntax is extensible,
365 /// consisting of a '/' separated hierarchy with a leading '/'. A set of standard parts is
366 /// defined in XMP_Const.h:
367 /// \li c kXMP_Part_All Indicates "any" or "all"
368 /// \li c kXMP_Part_Metadata Portions of the metadata changed
369 /// \li c kXMP_Part_Content Any/all of the content (non-metadata)
370 /// \li c kXMP_Part_Audio Any/all sound
371 /// \li c kXMP_Part_Visual Any/all image data (video or still)
372 /// \li c kXMP_Part_Video Video or animation (moving image)
373 /// \li c kXMP_Part_Raster Static raster image
374 /// \li c kXMP_Part_Vector Static vector image
375 /// \li c kXMP_Part_FormData Form field data
376 /// \li c kXMP_Part_FormTemplate Form template
377 /// \li c kXMP_Part_Annots Applied annotations (comments)
378
379 void NoteChange ( XMP_StringPtr in_part );
380
381 // ---------------------------------------------------------------------------------------------
382 /// @brief \c NoteChange() is used to report changes to some portion of a document.
383 ///
384 /// @details This overload takes a vector of changed parts. It is equivalent to calling the single part
385 /// form on each of the vector elements.
386 ///
387 /// @param in_parts A vector of strings, each following the part name syntax.
388
389 void NoteChange ( std::vector<XMP_StringPtr> & in_parts );
390
391 /// @}
392
393 // ============================================================================================
394 /// \name File change detection
395 /// @{
396 ///
397 /// Utilities that help applications determine what has changed in a file since last seen. A
398 /// typical use might be in an application that creates a compound document from portions of a
399 /// file, and wants to detect when other applications change those portions.
400
401 // ---------------------------------------------------------------------------------------------
402 /// @brief \c HasPartChanged() is used to determine if a portion of a file has changed.
403 ///
404 /// @details \c HasPartChanged is used to determine if a portion of a file has changed since some
405 /// previous save with a given \c xmpMM:InstanceID property.
406 ///
407 /// @param in_prevInstanceID The \c xmpMM:InstanceID of the file when last seen.
408 ///
409 /// @param in_partName The part name of interest.
410 ///
411 /// @return Returns kXMPTS_Yes if the named part, or any ancestor, or any descendant, has changed.
412 /// Returns kXMPTS_No if it has not changed. Returns kXMPTS_Maybe if yes or no cannot be determined,
413 /// for example if the history has no entry for the given instance ID.
414
415 XMP_TriState HasPartChanged ( XMP_StringPtr in_prevInstanceID,
416 XMP_StringPtr in_partName ) const;
417
418 // ---------------------------------------------------------------------------------------------
419 /// @brief \c HasPartChanged() is used to determine if a portion of a file has changed.
420 ///
421 /// This overload takes a vector of part names.
422 ///
423 /// @param in_prevInstanceID The \c xmpMM:InstanceID of the file when last seen.
424 ///
425 /// @param in_partNames The part names of interest.
426 ///
427 /// @return Returns kXMPTS_Yes if any of the named parts, or any ancestor, or any descendant,
428 /// have changed. Returns kXMPTS_No if none have changed. Returns kXMPTS_Maybe if yes or no
429 /// cannot be determined, for example if the history has no entry for the given instance ID.
430
431 XMP_TriState HasPartChanged ( XMP_StringPtr in_prevInstanceID,
432 std::vector<XMP_StringPtr> & in_partNames ) const;
433
434 // ---------------------------------------------------------------------------------------------
435 /// @brief \c GetPartChangeID() is used to determine the instance ID when a portion of a file changed.
436 ///
437 /// \c GetPartChangeID is used to determine the instance ID when a portion of a file most
438 /// recently changed.
439 ///
440 /// @param in_partName The part name of interest.
441 ///
442 /// @param out_instanceID The instance ID of the file at the last save that changed the part.
443 ///
444 /// @return Returns true if history about the given part changing is found.
445
446 bool GetPartChangeID ( XMP_StringPtr in_partName,
447 tStringObj * out_instanceID ) const;
448
449 // ---------------------------------------------------------------------------------------------
450 /// @brief \c GetPartChangeID() is used to determine the instance ID when a portion of a file changed.
451 ///
452 /// This overload accepts a vector of part names. It returns information about the most recent
453 /// change that affected any of the named parts.
454 ///
455 /// @param in_partNames The part names of interest.
456 ///
457 /// @param out_instanceID The instance ID of the file at the last save that changed any part.
458 ///
459 /// @return Returns true if history about any of the given parts changing is found.
460
461 bool GetPartChangeID ( std::vector<XMP_StringPtr> & in_partNames,
462 tStringObj * out_instanceID ) const;
463
464 // ---------------------------------------------------------------------------------------------
465 /// @brief \c EnsureIDsExist() is a simple utility to make sure standard GUIDs exist.
466 ///
467 /// \c EnsureIDsExist can be used to make sure that the \c xmpMM:InstanceID, \c xmpMM:DocumentID,
468 /// and \c xmpMM:OriginalDocumentID properties exist. The options parameter can be used to limit
469 /// which IDs are ensured.
470 ///
471 /// @param options Flags to control which IDs are ensured. The available values are:
472 /// \li \c kXMPDocOps_IgnoreDocumentID - Don't create \c xmpMM:DocumentID or \c xmpMM:OriginalDocumentID.
473 /// \li \c kXMPDocOps_IgnoreOriginalDocumentID - Don't create \c xmpMM:OriginalDocumentID.
474 ///
475 /// @return Returns true if any new IDs were created.
476
477 /// @}
478
479 // ============================================================================================
480 /// \name Miscellaneous utilities
481 /// @{
482
483 bool EnsureIDsExist ( XMP_OptionBits options = 0 );
484
485 // ---------------------------------------------------------------------------------------------
486 /// @brief \c IsDirty() is used to tell if the document has been changed.
487 ///
488 /// @param reasons Optional bit mask returning reasons why the document is dirty.
489 ///
490 /// @return Returns true if the document has been changed. See also NoteChange.
491
492 bool IsDirty ( XMP_OptionBits * reasons ) const;
493 bool IsDirty() const;
494
495 // ---------------------------------------------------------------------------------------------
496 /// @brief \c Clone() creates a deep copy of an SXMPDocOps object.
497 ///
498 /// Use this function to create an entirely separate copy of an SXMPDocOps object. Associated
499 /// XMP is also cloned. Assignment and copy constructors only increment a reference count, they
500 /// do not do a deep copy.
501 ///
502 /// @param options There are no currently defined options.
503 ///
504 /// @return An SXMPDocOps object cloned from the original.
505
506 TXMPDocOps Clone ( XMP_OptionBits options = 0 ) const;
507
508 // ---------------------------------------------------------------------------------------------
509 /// @brief \c GetMetaRef() returns the internal reference for the associated XMP.
510 ///
511 /// \c GetMetaRef() returns the internal reference for the associated XMP. See \c SXMPMeta::GetInternalRef
512 /// for additional details about why and how to use the internal reference.
513 ///
514 /// @return Returns the internal reference for the associated XMP, 0 if there is none.
515
516 XMPMetaRef GetMetaRef() const;
517
518 #if XMP_AndroidBuild
519
520 // ---------------------------------------------------------------------------------------------
521 /// @brief \c SetJVM() allows client to Set JavaVM for android platform
522 ///
523 ///
524 static void SetJVM(JavaVM* vm);
525 #endif
526 /// @}
527
528 // =============================================================================================
529
530 private:
531
532 XMPDocOpsRef xmpDocRef;
533
534 static void SetClientString ( void * clientPtr, XMP_StringPtr valuePtr, XMP_StringLen valueLen );
535
536 }; // class TXMPDocOps
537
538 // =================================================================================================
539
540 #endif // __TXMPDocOps_hpp__
541
542 #endif // AdobePrivate