diff options
| author | Hubert Figuiere <hub@figuiere.net> | 2008-11-17 23:42:00 -0500 |
|---|---|---|
| committer | Hubert Figuiere <hub@figuiere.net> | 2008-11-17 23:42:00 -0500 |
| commit | 88af812fde414aca8f9add90bc800ea3d8e9a281 (patch) | |
| tree | 0403dd1897c0b287d4d710dd422827683c59dfcb /docs/API/index.html | |
| parent | 9d7d7c3caac05db240692ad7e9196fcb7f5a1ce5 (diff) | |
upgrade to XMP-SDK 4.4.2
Diffstat (limited to 'docs/API/index.html')
| -rw-r--r-- | docs/API/index.html | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/docs/API/index.html b/docs/API/index.html new file mode 100644 index 0000000..bf96a3d --- /dev/null +++ b/docs/API/index.html @@ -0,0 +1,178 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> +<title>XMP-Toolkit-SDK-4.4.2: XMP Toolkit API Overview</title> +<link href="xmp.css" rel="stylesheet" type="text/css"> +<link href="tabs.css" rel="stylesheet" type="text/css"> +</head><body> +<img src="xmp_tagline_small.jpg" width="125" height="50" border="0"><p> +<!-- Generated by Doxygen 1.5.6 --> +<script type="text/javascript"> +<!-- +function changeDisplayState (e){ + var num=this.id.replace(/[^[0-9]/g,''); + var button=this.firstChild; + var sectionDiv=document.getElementById('dynsection'+num); + if (sectionDiv.style.display=='none'||sectionDiv.style.display==''){ + sectionDiv.style.display='block'; + button.src='open.gif'; + }else{ + sectionDiv.style.display='none'; + button.src='closed.gif'; + } +} +function initDynSections(){ + var divs=document.getElementsByTagName('div'); + var sectionCounter=1; + for(var i=0;i<divs.length-1;i++){ + if(divs[i].className=='dynheader'&&divs[i+1].className=='dynsection'){ + var header=divs[i]; + var section=divs[i+1]; + var button=header.firstChild; + if (button!='IMG'){ + divs[i].insertBefore(document.createTextNode(' '),divs[i].firstChild); + button=document.createElement('img'); + divs[i].insertBefore(button,divs[i].firstChild); + } + header.style.cursor='pointer'; + header.onclick=changeDisplayState; + header.id='dynheader'+sectionCounter; + button.src='closed.gif'; + section.id='dynsection'+sectionCounter; + section.style.display='none'; + section.style.marginLeft='14px'; + sectionCounter++; + } + } +} +window.onload = initDynSections; +--> +</script> +<div class="navigation" id="top"> + <div class="tabs"> + <ul> + <li class="current"><a href="index.html"><span>Main Page</span></a></li> + <li><a href="annotated.html"><span>Classes</span></a></li> + <li><a href="files.html"><span>Files</span></a></li> + </ul> + </div> +</div> +<div class="contents"> +<h1>XMP Toolkit API Overview</h1> +<p> +The XMPCore component provides the tools that allow you to parse, manipulate, and serialize XMP data, according to the Data Model and Serialization Model given in the XMP Specification. XMPCore has no knowledge of files. <br> +<br> + The client view of the XMPCore API is provided through these C++ class templates:<p> +<ul> +<li><code><a class="el" href="classTXMPMeta.html" title="API for access to the XMP Toolkit core services.">TXMPMeta</a></code> provides the fundamental methods for manipulating XMP metadata. </li> +<li><code><a class="el" href="classTXMPIterator.html" title="API for access to the XMP Toolkit iteration services.">TXMPIterator</a></code> provides methods to iterate over existing XMP metadata. </li> +<li><code><a class="el" href="classTXMPUtils.html" title="API for access to the XMP Toolkit utility services.">TXMPUtils</a></code> provides additional utilities layered on top of <code><a class="el" href="classTXMPMeta.html" title="API for access to the XMP Toolkit core services.">TXMPMeta</a></code>.</li> +</ul> +The XMPFiles component provides support for locating the XMP in a file, adding XMP to a file, or updating the XMP in a file. Use it to retrieve an entire XMP packet from a file, which you can either manipulate directly or use to create a <code><a class="el" href="classTXMPMeta.html" title="API for access to the XMP Toolkit core services.">TXMPMeta</a></code> object, so that you can use the XMPCore component to manipulate the individual XMP properties. XMPFiles contains a number of format-specific file handlers that know how to efficiently access the XMP in particular formats. It also includes a fallback packet scanner that can be used for unknown file formats.<p> +<ul> +<li>The client view of the XMPFiles API is provided through <code><a class="el" href="classTXMPFiles.html" title="API for access to the main (document-level) metadata in a file.">TXMPFiles</a></code>.</li> +</ul> +The <code>TXMP*</code> classes are C++ template classes. The templates must be instantiated for use. You can read the template header files, <a class="el" href="TXMPMeta_8hpp.html" title="API for access to the XMP Toolkit core services.">TXMPMeta.hpp</a>, and so on, for detailed information, but do not include them directly in your code.<br> +<br> + There is one overall header file, XMP.hpp, which is the only one that C++ clients should include with the <code>include</code> directive. Read the instructions in this file for instantiating the template classes. When you have done this, the API is available through the concrete classes <code>SXMPMeta</code>, <code>SXMPUtils</code>, <code>SXMPIterator</code>, and <code>SXMPFiles</code>. <br> +<br> + You should also read <a class="el" href="XMP__Const_8h.html" title="Common C/C++ types and constants for the XMP toolkit.">XMP_Const.h</a> for detailed information about types and constants for namespace URIs and option flags.<h2><a class="anchor" name="second-sec"> +Using of the XMP Toolkit API</a></h2> +Developers should understand the XMP Data Model before working with the XMP Toolkit. The data model is documented in the XMP Specification. The XMPCoverage sample in the SDK provides an in-depth illustration of the use of the XMP Toolkit. An XMP Programmer's Guide with tutorial examples is provided in the docs folder within the SDK. <br> +<br> + Use of the XMP Toolkit is reasonably straightforward once you understand the XMP Data Model. An XMP property tree that conforms to the Data Model is encapsulated by a <a class="el" href="classTXMPMeta.html" title="API for access to the XMP Toolkit core services.">TXMPMeta</a> object, and the functions of that class allow you to manipulate the namespaces, properties, and values.<br> +<br> + To prepare XMP data for output (transferring it or embedding it in a file), it must be serialized as XML text (specifically, RDF conforming to the Serialization Model).<p> +<ul> +<li>Use <code><a class="el" href="classTXMPMeta.html#2774a6f15ae22f0002201b58c46bfb49" title="SerializeToBuffer() serializes metadata in this XMP object into a string as RDF.">TXMPMeta::SerializeToBuffer()</a></code> to creates the serialized XML for the data contained in the object.</li> +</ul> +<ul> +<li>Use the XMPFiles component (<code><a class="el" href="classTXMPFiles.html#fcd21cfe5d6f13c648c5541e161919cb" title="OpenFile() opens a file for metadata access.">TXMPFiles::OpenFile()</a></code> and <code><a class="el" href="classTXMPFiles.html#d3f7babdc07c7de0d0cd9a3362b4710a" title="PutXMP() updates the XMP metadata in this object without writing out the file.">TXMPFiles::PutXMP()</a></code>)to write out the serialized XMP as an XMP packet embedded in a file.</li> +</ul> +Similarly, you use the XMPFiles component (<code><a class="el" href="classTXMPFiles.html#42ca0bbc5ac66a8de1710e03a7ff17b3" title="GetXMP() retrieves the XMP metadata from an open file.">TXMPFiles::GetXMP()</a></code>) to extract an XMP packet from a file. To work with the XMP, create a <a class="el" href="classTXMPMeta.html" title="API for access to the XMP Toolkit core services.">TXMPMeta</a> object and populate it with the data using <code><a class="el" href="classTXMPMeta.html#7b383f5b357fff040cdbde82f4f43f26" title="ParseFromBuffer() parses RDF from a series of input buffers into this XMP object...">TXMPMeta::ParseFromBuffer()</a></code>. <br> +<br> + You can use the XMPCore component to generate new XMP data.<p> +<ul> +<li>You can create your own private namespaces, but must register them before use, using <code><a class="el" href="classTXMPMeta.html#c0368ddbaa4d689cd5b1aff1c88bb0e1" title="RegisterNamespace() registers a namespace URI with a suggested prefix.">TXMPMeta::RegisterNamespace()</a></code>.</li> +</ul> +<ul> +<li>Property accessor functions of various kinds allow you to retrieve and set existing property values, and to create new properties.</li> +</ul> +<ul> +<li>You can get and set property values as strings, or as binary types. <a class="el" href="classTXMPUtils.html" title="API for access to the XMP Toolkit utility services.">TXMPUtils</a> provides functions for converting between types.</li> +</ul> +<ul> +<li>Use <code><a class="el" href="classTXMPMeta.html#eefe49bbf669770d769f4fe0ea566bd0" title="GetLocalizedText() retrieves information about a selected item in an alt-text array...">TXMPMeta::GetLocalizedText()</a></code> and <code><a class="el" href="classTXMPMeta.html#f9531b949a462f5663b1f3fd99464c19" title="SetLocalizedText() modifies the value of a selected item in an alt-text array.">TXMPMeta::SetLocalizedText()</a></code> when dealing with language alternative (alt-text) arrays.</li> +</ul> +<ul> +<li>Use the path composition functions provided by <a class="el" href="classTXMPUtils.html" title="API for access to the XMP Toolkit utility services.">TXMPUtils</a> to construct complex paths with nested structs or arrays. It is recommended that you not depend on specific namespace prefixes; rather than hard-coding the prefixes for struct fields, use functions like <code><a class="el" href="classTXMPUtils.html#706eb85b8401b8682a01348f7e25ee3d" title="ComposeStructFieldPath() composes the path expression for a field in a struct.">TXMPUtils::ComposeStructFieldPath()</a></code> and <code><a class="el" href="classTXMPMeta.html#0e44c30e7527064909e5f7035d53c4f5" title="SetStructField() creates or sets the value of a field within a nested structure.">TXMPMeta::SetStructField()</a></code>.</li> +</ul> +<ul> +<li>Create a <a class="el" href="classTXMPIterator.html" title="API for access to the XMP Toolkit iteration services.">TXMPIterator</a> object to operate on all or a subset of the properties in the metadata tree contained in a <a class="el" href="classTXMPMeta.html" title="API for access to the XMP Toolkit core services.">TXMPMeta</a> object.</li> +</ul> +<h2><a class="anchor" name="third-sec"> +Overview of XMP Toolkit Internal Architecture.</a></h2> +The XMP Toolkit is implemented in three layers, which isolate the return of string values, synchronization for multi-threaded use, and exception propagation. While the SDK as provided from Adobe builds a static library, this layering can easily be adapted to build a DLL.<p> +<ul> +<li>The top layer is the implementation of the client template classes. This layer is for copying string results and releasing the threading lock if necessary.</li> +</ul> +<ul> +<li>The middle layer consists of the three classes <code>WXMPMeta</code>, <code>WXMPIterator</code>, and <code>WXMPUtils</code>. They provide wrappers between the top client layer and the actual implementation. The middle layer is responsible for acquiring the threading lock, basic parameter checking, catching propagated exceptions, and releasing the threading lock when appropriate.</li> +</ul> +<ul> +<li>The inner layer is the actual implementation, contained in the three classes <code>XMPMeta</code>, <code>XMPIterator</code>, and <code>XMPUtils</code>.</li> +</ul> +<h3><a class="anchor" name="callchain"> +Implementation Call Chain</a></h3> +The implementation of <code>GetProperty</code> provides a good illustration of the toolkit layering. The declaration below for <code><a class="el" href="classTXMPMeta.html#06a3241c7fa5df87f61dff02fca23a0c" title="GetProperty() reports whether a property exists, and retrieves its value.">TXMPMeta::GetProperty</a></code> is simplified by hardwiring <code>std::string</code>. The <code>XMP_StringPtr</code> type is simply <code>const char *</code>.<p> +<div class="fragment"><pre class="fragment"> <span class="keywordtype">bool</span> <a class="code" href="classTXMPMeta.html#06a3241c7fa5df87f61dff02fca23a0c" title="GetProperty() reports whether a property exists, and retrieves its value.">TXMPMeta::GetProperty</a> ( <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6" title="The type for input string parameters. A const char *, a null-terminated UTF-8 string...">XMP_StringPtr</a> schemaNS, + <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6" title="The type for input string parameters. A const char *, a null-terminated UTF-8 string...">XMP_StringPtr</a> propName, + std::string * propValue, + <a class="code" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8" title="The type for a collection of 32 flag bits. Individual flags are defined as enum value...">XMP_OptionBits</a> * options )<span class="keyword"> const</span> +<span class="keyword"> </span>{ + <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6" title="The type for input string parameters. A const char *, a null-terminated UTF-8 string...">XMP_StringPtr</a> resultPtr = 0; + <a class="code" href="XMP__Const_8h.html#9f7dcc184f901c713274edfdac5bcc9a" title="The type for string length parameters. A 32-bit unsigned integer, as big as will...">XMP_StringLen</a> resultLen = 0; + + <span class="keywordtype">bool</span> found = this->xmpObj.GetProperty ( schemaNS, propName, + &resultPtr, &resultLen, options ); + + <span class="keywordflow">if</span> ( found ) { + <span class="keywordflow">if</span> ( propValue != 0 ) propValue->assign ( resultPtr, resultLen ); + this->xmpObj.UnlockObject ( <a class="code" href="XMP__Const_8h.html#ff1df9f3cf050f8b8d3a574db3c3326b" title="Options macro clears all property-type bits.">kXMP_NoOptions</a> ); + } + <span class="keywordflow">return</span> found; + + } +</pre></div><p> +The template object contains a data member pointer to the underlying <code>WXMPMeta</code> object. This is used to dispatch the call to the middle layer. The actual implementation of the XMP toolkit returns string values as a pointer and length, the pointer references private internal storage of the toolkit. The client code copies the string value to the client's string object. This minimizes the amount of string copying, and should the XMP toolkit be built as a DLL ensures that any memory allocation for the client's value is done on the client side. The call to <code>WXMPMeta::UnlockObject</code> is explained below.<p> +<div class="fragment"><pre class="fragment"> <span class="keywordtype">bool</span> WXMPMeta::GetProperty ( <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6" title="The type for input string parameters. A const char *, a null-terminated UTF-8 string...">XMP_StringPtr</a> schemaNS, + <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6" title="The type for input string parameters. A const char *, a null-terminated UTF-8 string...">XMP_StringPtr</a> propName, + <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6" title="The type for input string parameters. A const char *, a null-terminated UTF-8 string...">XMP_StringPtr</a> * propValue, + <a class="code" href="XMP__Const_8h.html#9f7dcc184f901c713274edfdac5bcc9a" title="The type for string length parameters. A 32-bit unsigned integer, as big as will...">XMP_StringLen</a> * valueSize, + <a class="code" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8" title="The type for a collection of 32 flag bits. Individual flags are defined as enum value...">XMP_OptionBits</a> * options )<span class="keyword"> const</span> +<span class="keyword"> </span>{ + XMP_Bool found; + XMP_ENTER_WRAPPER ( <span class="stringliteral">"WXMPMeta::GetProperty"</span> ) + + if ( (schemaNS == 0) || (*schemaNS == 0) ) { + XMP_Throw ( <span class="stringliteral">"Empty schema namespace URI"</span>, <a class="code" href="XMP__Const_8h.html#db49720dc49f7d4e4cf9adbf2948e4092bc66eec6ce830979089d5c336f75539" title="Bad schema parameter.">kXMPErr_BadSchema</a> ); + } + <span class="keywordflow">if</span> ( (propName == 0) || (*propName == 0) ) { + XMP_Throw ( <span class="stringliteral">"Empty property name"</span>, <a class="code" href="XMP__Const_8h.html#db49720dc49f7d4e4cf9adbf2948e4093f1efec0aa5452f43c55c05aba616ef7" title="Bad XPath parameter.">kXMPErr_BadXPath</a> ); + } + + <span class="keywordflow">if</span> ( propValue == 0 ) propValue = &voidStringPtr; + <span class="keywordflow">if</span> ( valueSize == 0 ) valueSize = &voidStringLen; + <span class="keywordflow">if</span> ( options == 0 ) options = &voidOptionBits; + + <span class="keyword">const</span> XMPMeta & meta = WtoXMPMeta_Ref ( *<span class="keyword">this</span> ); + found = meta.GetProperty ( schemaNS, propName, propValue, valueSize, options ); + + XMP_EXIT_WRAPPER_KEEP_LOCK ( found ) + return found; + } +</pre></div><p> +The entry and exit macros in the <code>WXMPMeta</code> layer acquire the threading lock on entry and usually release it on exit. The lock is kept on exit whenever a string value is returned. Since a pointer to internal data is returned, the threading lock can't be released until after the template code in the client copies the string. The entry and exit macros also prevent uncontrolled exception propagation from the lower layer back to the client. This is not critical for use of the XMP Toolkit as a static library. But it is generally not safe to propagate C++ exceptions across DLL boundaries. </div> +<hr size="1"><address style="text-align: right;"><small> +XMP-Toolkit-SDK-4.4.2 documentation generated by <a href="http://www.doxygen.org/index.html">doxygen</a> 1.5.6</small></address> +</body> +</html> |