XMP-Toolkit-SDK-4.4.2: TXMPMeta.hpp Source File

00001 #ifndef __TXMPMeta_hpp__
00002 #define __TXMPMeta_hpp__    1
00003 
00004 #if ( ! __XMP_hpp__ )
00005     #error "Do not directly include, use XMP.hpp"
00006 #endif
00007 
00008 // =================================================================================================
00009 // ADOBE SYSTEMS INCORPORATED
00010 // Copyright 2002-2008 Adobe Systems Incorporated
00011 // All Rights Reserved
00012 //
00013 // NOTICE:  Adobe permits you to use, modify, and distribute this file in accordance with the terms
00014 // of the Adobe license agreement accompanying it.
00015 // =================================================================================================
00016 
00017 // =================================================================================================
00027 // =================================================================================================
00028 
00029 // =================================================================================================
00042 // =================================================================================================
00043 
00044 template <class tStringObj> class TXMPIterator;
00045 template <class tStringObj> class TXMPUtils;
00046 
00047 // -------------------------------------------------------------------------------------------------
00048 
00049 template <class tStringObj> class TXMPMeta {
00050 
00051 public:
00052 
00053     // =============================================================================================
00054     // Initialization and termination
00055     // ==============================
00056 
00057     // ---------------------------------------------------------------------------------------------
00061 
00062     // ---------------------------------------------------------------------------------------------
00074 
00075     static void GetVersionInfo ( XMP_VersionInfo * info );
00076 
00077     // ---------------------------------------------------------------------------------------------
00079 
00088     static bool Initialize();
00089     // ---------------------------------------------------------------------------------------------
00095 
00096     static void Terminate();
00097 
00099 
00100     // =============================================================================================
00101     // Constuctors and destructor
00102     // =========================
00103 
00104     // ---------------------------------------------------------------------------------------------
00107 
00108     // ---------------------------------------------------------------------------------------------
00114     TXMPMeta();
00115 
00116     // ---------------------------------------------------------------------------------------------
00125 
00126     TXMPMeta ( const TXMPMeta<tStringObj> & original );
00127 
00128     // ---------------------------------------------------------------------------------------------
00133 
00134     void operator= ( const TXMPMeta<tStringObj> & rhs );
00135 
00136     // ---------------------------------------------------------------------------------------------
00146 
00147     TXMPMeta ( XMPMetaRef xmpRef );
00148 
00149     // ---------------------------------------------------------------------------------------------
00166 
00167     TXMPMeta ( XMP_StringPtr buffer,
00168                XMP_StringLen xmpSize );
00169 
00170     // ---------------------------------------------------------------------------------------------
00172     virtual ~TXMPMeta() throw();
00173 
00175 
00176     // =============================================================================================
00177     // Global state functions
00178     // ======================
00179 
00180     // ---------------------------------------------------------------------------------------------
00185 
00186     // ---------------------------------------------------------------------------------------------
00193 
00194      static XMP_OptionBits GetGlobalOptions();
00195 
00196     // ---------------------------------------------------------------------------------------------
00207 
00208     static void SetGlobalOptions ( XMP_OptionBits options );
00209 
00211 
00212     // ---------------------------------------------------------------------------------------------
00220 
00221     // ---------------------------------------------------------------------------------------------
00234 
00235     static XMP_Status DumpNamespaces ( XMP_TextOutputProc outProc,
00236                                        void *             clientData );
00237 
00238     // ---------------------------------------------------------------------------------------------
00251 
00252     static XMP_Status DumpAliases ( XMP_TextOutputProc outProc,
00253                                     void *             clientData );
00254 
00256 
00257     // ---------------------------------------------------------------------------------------------
00268 
00269     // ---------------------------------------------------------------------------------------------
00290 
00291     static bool RegisterNamespace ( XMP_StringPtr namespaceURI,
00292                                     XMP_StringPtr suggestedPrefix,
00293                                     tStringObj *  registeredPrefix );
00294 
00295     // ---------------------------------------------------------------------------------------------
00309 
00310     static bool GetNamespacePrefix ( XMP_StringPtr namespaceURI,
00311                                      tStringObj *  namespacePrefix );
00312 
00313     // ---------------------------------------------------------------------------------------------
00326 
00327     static bool GetNamespaceURI ( XMP_StringPtr namespacePrefix,
00328                                   tStringObj *  namespaceURI );
00329 
00330     // ---------------------------------------------------------------------------------------------
00339 
00340     static void DeleteNamespace ( XMP_StringPtr namespaceURI );
00341 
00343 
00344     // ---------------------------------------------------------------------------------------------
00360 
00361     // ---------------------------------------------------------------------------------------------
00397 
00398     static void RegisterAlias ( XMP_StringPtr  aliasNS,
00399                                 XMP_StringPtr  aliasProp,
00400                                 XMP_StringPtr  actualNS,
00401                                 XMP_StringPtr  actualProp,
00402                                 XMP_OptionBits arrayForm = kXMP_NoOptions );
00403 
00404     // ---------------------------------------------------------------------------------------------
00431 
00432     static bool ResolveAlias ( XMP_StringPtr    aliasNS,
00433                                XMP_StringPtr    aliasProp,
00434                                tStringObj *     actualNS,
00435                                tStringObj *     actualProp,
00436                                XMP_OptionBits * arrayForm );
00437 
00438     // ---------------------------------------------------------------------------------------------
00451 
00452     static void DeleteAlias ( XMP_StringPtr aliasNS,
00453                               XMP_StringPtr aliasProp );
00454 
00455     // ---------------------------------------------------------------------------------------------
00465 
00466     static void RegisterStandardAliases ( XMP_StringPtr schemaNS );
00467 
00469 
00470     // =============================================================================================
00471     // Basic property manipulation functions
00472     // =====================================
00473 
00474     // *** Should add discussion of schemaNS and propName prefix usage.
00475 
00476     // ---------------------------------------------------------------------------------------------
00491 
00492     // ---------------------------------------------------------------------------------------------
00523 
00524     bool GetProperty ( XMP_StringPtr    schemaNS,
00525                        XMP_StringPtr    propName,
00526                        tStringObj *     propValue,
00527                        XMP_OptionBits * options ) const;
00528 
00529     // ---------------------------------------------------------------------------------------------
00551 
00552     bool GetArrayItem ( XMP_StringPtr    schemaNS,
00553                         XMP_StringPtr    arrayName,
00554                         XMP_Index        itemIndex,
00555                         tStringObj *     itemValue,
00556                         XMP_OptionBits * options ) const;
00557 
00558     // ---------------------------------------------------------------------------------------------
00583 
00584     bool GetStructField ( XMP_StringPtr    schemaNS,
00585                           XMP_StringPtr    structName,
00586                           XMP_StringPtr    fieldNS,
00587                           XMP_StringPtr    fieldName,
00588                           tStringObj *     fieldValue,
00589                           XMP_OptionBits * options ) const;
00590 
00591     // ---------------------------------------------------------------------------------------------
00616 
00617     bool GetQualifier ( XMP_StringPtr    schemaNS,
00618                         XMP_StringPtr    propName,
00619                         XMP_StringPtr    qualNS,
00620                         XMP_StringPtr    qualName,
00621                         tStringObj *     qualValue,
00622                         XMP_OptionBits * options ) const;
00623 
00625 
00626     // =============================================================================================
00627 
00628     // ---------------------------------------------------------------------------------------------
00640 
00654 
00655     // ---------------------------------------------------------------------------------------------
00672 
00673     void SetProperty ( XMP_StringPtr  schemaNS,
00674                        XMP_StringPtr  propName,
00675                        XMP_StringPtr  propValue,
00676                        XMP_OptionBits options = 0 );
00677 
00678     // ---------------------------------------------------------------------------------------------
00683 
00684     void SetProperty ( XMP_StringPtr      schemaNS,
00685                        XMP_StringPtr      propName,
00686                        const tStringObj & propValue,
00687                        XMP_OptionBits     options = 0 );
00688 
00689     // ---------------------------------------------------------------------------------------------
00717 
00718     void SetArrayItem ( XMP_StringPtr  schemaNS,
00719                         XMP_StringPtr  arrayName,
00720                         XMP_Index      itemIndex,
00721                         XMP_StringPtr  itemValue,
00722                         XMP_OptionBits options = 0 );
00723 
00724     // ---------------------------------------------------------------------------------------------
00729 
00730     void SetArrayItem ( XMP_StringPtr      schemaNS,
00731                         XMP_StringPtr      arrayName,
00732                         XMP_Index          itemIndex,
00733                         const tStringObj & itemValue,
00734                         XMP_OptionBits     options = 0 );
00735 
00736     // ---------------------------------------------------------------------------------------------
00762 
00763     void AppendArrayItem ( XMP_StringPtr  schemaNS,
00764                            XMP_StringPtr  arrayName,
00765                            XMP_OptionBits arrayOptions,
00766                            XMP_StringPtr  itemValue,
00767                            XMP_OptionBits itemOptions = 0 );
00768 
00769     // ---------------------------------------------------------------------------------------------
00775 
00776     void AppendArrayItem ( XMP_StringPtr      schemaNS,
00777                            XMP_StringPtr      arrayName,
00778                            XMP_OptionBits     arrayOptions,
00779                            const tStringObj & itemValue,
00780                            XMP_OptionBits     itemOptions = 0 );
00781 
00782     // ---------------------------------------------------------------------------------------------
00807 
00808     void SetStructField ( XMP_StringPtr   schemaNS,
00809                           XMP_StringPtr   structName,
00810                           XMP_StringPtr   fieldNS,
00811                           XMP_StringPtr   fieldName,
00812                           XMP_StringPtr   fieldValue,
00813                           XMP_OptionBits  options = 0 );
00814 
00815     // ---------------------------------------------------------------------------------------------
00821 
00822     void SetStructField ( XMP_StringPtr      schemaNS,
00823                           XMP_StringPtr      structName,
00824                           XMP_StringPtr      fieldNS,
00825                           XMP_StringPtr      fieldName,
00826                           const tStringObj & fieldValue,
00827                           XMP_OptionBits     options = 0 );
00828 
00829     // ---------------------------------------------------------------------------------------------
00854 
00855     void SetQualifier ( XMP_StringPtr  schemaNS,
00856                         XMP_StringPtr  propName,
00857                         XMP_StringPtr  qualNS,
00858                         XMP_StringPtr  qualName,
00859                         XMP_StringPtr  qualValue,
00860                         XMP_OptionBits options = 0 );
00861 
00862     // ---------------------------------------------------------------------------------------------
00867 
00868     void SetQualifier ( XMP_StringPtr      schemaNS,
00869                         XMP_StringPtr      propName,
00870                         XMP_StringPtr      qualNS,
00871                         XMP_StringPtr      qualName,
00872                         const tStringObj & qualValue,
00873                         XMP_OptionBits     options = 0 );
00874 
00876 
00877     // =============================================================================================
00878 
00879     // ---------------------------------------------------------------------------------------------
00885 
00886     // ---------------------------------------------------------------------------------------------
00894 
00895     void DeleteProperty ( XMP_StringPtr schemaNS,
00896                           XMP_StringPtr propName );
00897 
00898     // ---------------------------------------------------------------------------------------------
00911 
00912     void DeleteArrayItem ( XMP_StringPtr schemaNS,
00913                            XMP_StringPtr arrayName,
00914                            XMP_Index     itemIndex );
00915 
00916     // ---------------------------------------------------------------------------------------------
00931 
00932     void DeleteStructField ( XMP_StringPtr schemaNS,
00933                              XMP_StringPtr structName,
00934                              XMP_StringPtr fieldNS,
00935                              XMP_StringPtr fieldName );
00936 
00937     // ---------------------------------------------------------------------------------------------
00953 
00954     void DeleteQualifier ( XMP_StringPtr schemaNS,
00955                            XMP_StringPtr propName,
00956                            XMP_StringPtr qualNS,
00957                            XMP_StringPtr qualName );
00958 
00959     // ---------------------------------------------------------------------------------------------
00967 
00968     bool DoesPropertyExist ( XMP_StringPtr schemaNS,
00969                              XMP_StringPtr propName ) const;
00970 
00971     // ---------------------------------------------------------------------------------------------
00985 
00986     bool DoesArrayItemExist ( XMP_StringPtr schemaNS,
00987                               XMP_StringPtr arrayName,
00988                               XMP_Index     itemIndex ) const;
00989 
00990     // ---------------------------------------------------------------------------------------------
01007 
01008     bool DoesStructFieldExist ( XMP_StringPtr schemaNS,
01009                                 XMP_StringPtr structName,
01010                                 XMP_StringPtr fieldNS,
01011                                 XMP_StringPtr fieldName ) const;
01012 
01013     // ---------------------------------------------------------------------------------------------
01029 
01030     bool DoesQualifierExist ( XMP_StringPtr schemaNS,
01031                               XMP_StringPtr propName,
01032                               XMP_StringPtr qualNS,
01033                               XMP_StringPtr qualName ) const;
01034 
01036 
01037     // =============================================================================================
01038     // Specialized Get and Set functions
01039     // =============================================================================================
01040 
01041     // ---------------------------------------------------------------------------------------------
01050 
01051     // ---------------------------------------------------------------------------------------------
01070 
01071     bool GetProperty_Bool ( XMP_StringPtr    schemaNS,
01072                             XMP_StringPtr    propName,
01073                             bool *           propValue,
01074                             XMP_OptionBits * options ) const;
01075 
01076     // ---------------------------------------------------------------------------------------------
01095 
01096     bool GetProperty_Int ( XMP_StringPtr    schemaNS,
01097                            XMP_StringPtr    propName,
01098                            long *           propValue,
01099                            XMP_OptionBits * options ) const;
01100 
01101     // ---------------------------------------------------------------------------------------------
01120 
01121     bool GetProperty_Int64 ( XMP_StringPtr    schemaNS,
01122                              XMP_StringPtr    propName,
01123                              long long *      propValue,
01124                              XMP_OptionBits * options ) const;
01125 
01126     // ---------------------------------------------------------------------------------------------
01145 
01146     bool GetProperty_Float ( XMP_StringPtr    schemaNS,
01147                              XMP_StringPtr    propName,
01148                              double *         propValue,
01149                              XMP_OptionBits * options ) const;
01150 
01151     // ---------------------------------------------------------------------------------------------
01170 
01171     bool GetProperty_Date ( XMP_StringPtr    schemaNS,
01172                             XMP_StringPtr    propName,
01173                             XMP_DateTime *   propValue,
01174                             XMP_OptionBits * options ) const;
01175 
01176     // ---------------------------------------------------------------------------------------------
01192 
01193     void SetProperty_Bool ( XMP_StringPtr  schemaNS,
01194                             XMP_StringPtr  propName,
01195                             bool           propValue,
01196                             XMP_OptionBits options = 0 );
01197 
01198     // ---------------------------------------------------------------------------------------------
01214 
01215     void SetProperty_Int ( XMP_StringPtr  schemaNS,
01216                            XMP_StringPtr  propName,
01217                            long           propValue,
01218                            XMP_OptionBits options = 0 );
01219 
01220     // ---------------------------------------------------------------------------------------------
01236 
01237     void SetProperty_Int64 ( XMP_StringPtr  schemaNS,
01238                              XMP_StringPtr  propName,
01239                              long long      propValue,
01240                              XMP_OptionBits options = 0 );
01241 
01242     // ---------------------------------------------------------------------------------------------
01258 
01259     void SetProperty_Float ( XMP_StringPtr  schemaNS,
01260                              XMP_StringPtr  propName,
01261                              double         propValue,
01262                              XMP_OptionBits options = 0 );
01263 
01264     // ---------------------------------------------------------------------------------------------
01280 
01281     void SetProperty_Date ( XMP_StringPtr         schemaNS,
01282                             XMP_StringPtr         propName,
01283                             const XMP_DateTime &  propValue,
01284                             XMP_OptionBits        options = 0 );
01285 
01287     // =============================================================================================
01326 
01327     // ---------------------------------------------------------------------------------------------
01368 
01369     bool GetLocalizedText ( XMP_StringPtr    schemaNS,
01370                             XMP_StringPtr    altTextName,
01371                             XMP_StringPtr    genericLang,
01372                             XMP_StringPtr    specificLang,
01373                             tStringObj *     actualLang,
01374                             tStringObj *     itemValue,
01375                             XMP_OptionBits * options ) const;
01376 
01377     // ---------------------------------------------------------------------------------------------
01435 
01436     void SetLocalizedText ( XMP_StringPtr  schemaNS,
01437                             XMP_StringPtr  altTextName,
01438                             XMP_StringPtr  genericLang,
01439                             XMP_StringPtr  specificLang,
01440                             XMP_StringPtr  itemValue,
01441                             XMP_OptionBits options = 0 );
01442 
01443     // ---------------------------------------------------------------------------------------------
01500 
01501     void SetLocalizedText ( XMP_StringPtr      schemaNS,
01502                             XMP_StringPtr      altTextName,
01503                             XMP_StringPtr      genericLang,
01504                             XMP_StringPtr      specificLang,
01505                             const tStringObj & itemValue,
01506                             XMP_OptionBits     options = 0 );
01507 
01509 
01510     // =============================================================================================
01522 
01523     // ---------------------------------------------------------------------------------------------
01547 
01548     void ParseFromBuffer ( XMP_StringPtr  buffer,
01549                            XMP_StringLen  bufferSize,
01550                            XMP_OptionBits options = 0 );
01551 
01552     // ---------------------------------------------------------------------------------------------
01595 
01596     void SerializeToBuffer ( tStringObj *   rdfString,
01597                              XMP_OptionBits options,
01598                              XMP_StringLen  padding,
01599                              XMP_StringPtr  newline,
01600                              XMP_StringPtr  indent = "",
01601                              XMP_Index      baseIndent = 0 ) const;
01602 
01603     // ---------------------------------------------------------------------------------------------
01638 
01639     void SerializeToBuffer ( tStringObj *   rdfString,
01640                              XMP_OptionBits options = 0,
01641                              XMP_StringLen  padding = 0 ) const;
01642 
01644     // =============================================================================================
01645     // Miscellaneous Member Functions
01646     // ==============================
01647 
01648     // ---------------------------------------------------------------------------------------------
01651 
01652     // ---------------------------------------------------------------------------------------------
01684 
01685     XMPMetaRef GetInternalRef() const;
01686 
01687     // ---------------------------------------------------------------------------------------------
01693 
01694     void GetObjectName ( tStringObj * name ) const;
01695 
01696     // ---------------------------------------------------------------------------------------------
01702 
01703     void SetObjectName ( XMP_StringPtr name );
01704 
01705     // ---------------------------------------------------------------------------------------------
01711 
01712     void SetObjectName ( tStringObj name );
01713 
01714     // ---------------------------------------------------------------------------------------------
01725     
01726     void Sort();
01727 
01728     // ---------------------------------------------------------------------------------------------
01730     
01731     void Erase();
01732     
01733     // ---------------------------------------------------------------------------------------------
01757 
01758     TXMPMeta Clone ( XMP_OptionBits options = 0 ) const;
01759 
01760     // ---------------------------------------------------------------------------------------------
01769 
01770     XMP_Index CountArrayItems ( XMP_StringPtr schemaNS,
01771                                 XMP_StringPtr arrayName ) const;
01772 
01773     // ---------------------------------------------------------------------------------------------
01786 
01787     XMP_Status DumpObject ( XMP_TextOutputProc outProc,
01788                             void *             clientData ) const;
01789 
01790     // ---------------------------------------------------------------------------------------------
01792     XMP_OptionBits GetObjectOptions() const;
01793 
01794     // ---------------------------------------------------------------------------------------------
01796     void SetObjectOptions ( XMP_OptionBits options );
01797 
01799 
01800     // =============================================================================================
01801 
01802     XMPMetaRef xmpRef;  // *** Should be private, see below.
01803 
01804 private:
01805 
01806 #if 0   // *** VS.Net and gcc seem to not handle the friend declarations properly.
01807     friend class TXMPIterator <class tStringObj>;
01808     friend class TXMPUtils <class tStringObj>;
01809 #endif
01810 
01811 };  // class TXMPMeta
01812 
01813 #endif  // __TXMPMeta_hpp__