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/XMPToolkit/index.html | |
| parent | 9d7d7c3caac05db240692ad7e9196fcb7f5a1ce5 (diff) | |
upgrade to XMP-SDK 4.4.2
Diffstat (limited to 'docs/XMPToolkit/index.html')
| -rw-r--r-- | docs/XMPToolkit/index.html | 112 |
1 files changed, 0 insertions, 112 deletions
diff --git a/docs/XMPToolkit/index.html b/docs/XMPToolkit/index.html deleted file mode 100644 index 492a6ce..0000000 --- a/docs/XMPToolkit/index.html +++ /dev/null @@ -1,112 +0,0 @@ -<!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: Overview XMP Toolkit Overview</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 id="current"><a href="index.html"><span>Main Page</span></a></li> - <li><a href="modules.html"><span>Modules</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> -<h1>Overview XMP Toolkit Overview</h1> -<p> -<h2><a class="anchor" name="intro-sec"> -This XMP Toolkit Release</a></h2> -This release provides the following features: <ul> -<li>Improved, simpler API. If you need to port code from a previous version, see the <a class="el" href="group__Transition.html">XMP API Transition Guide</a> (under Modules). </li> -<li>Updates to make the code compatible with Adobe Acrobat 7 and Adobe Creative Suite 2. </li> -<li>Improved performance, in some cases significantly improved. </li> -<li>Code cleanup that makes the source more readable and easier to maintain. </li> -<li>Single source with UNIX-style newlines; this version works in all operating systems </li> -<li>Improved namespace handling. </li> -<li>Numerous bug fixes.</li> -</ul> -<h2><a class="anchor" name="first-sec"> -General Overview of the XMP API and Internal Architecture.</a></h2> -The client view of the XMP API is provided through three C++ class templates: <ul> -<li><code><a class="el" href="classTXMPMeta.html">TXMPMeta</a></code> provides the fundamental methods for manipulating XMP metadata. </li> -<li><code><a class="el" href="classTXMPIterator.html">TXMPIterator</a></code> provides methods to iterate over existing XMP metadata. </li> -<li><code><a class="el" href="classTXMPUtils.html">TXMPUtils</a></code> provides additional utilities layered on top of <code><a class="el" href="classTXMPMeta.html">TXMPMeta</a></code>. Use a string class to instantiate the templates; you can use <code>std::string</code>. The string class is a template parameter, which simplifies its use for clients that have an existing string model different from <code>std::string</code>.</li> -</ul> -Developers should understand the XMP data model before working with the XMP Toolkit. The data model is documented in chapter 2 of the XMP Specification. The XMPCoverage sample provides an in-depth illustration of the use of the XMP Toolkit.<p> -<dl class="note" compact><dt><b>Note:</b></dt><dd>Earlier versions of the Adobe XMP Toolkit had a different API and implementation. See the <a class="el" href="group__Transition.html">XMP API Transition Guide</a> page for information about adapting to the new API.</dd></dl> -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. <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> -<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> -<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> -<h2><a class="anchor" name="second-sec"> -Use of the XMP API</a></h2> -Client code obtains access to the XMP API by including a single header, XMP.hpp. You should read the template header files, <a class="el" href="TXMPMeta_8hpp.html">TXMPMeta.hpp</a>, and so on, for detailed information, but do not #include them. You should also read <a class="el" href="XMP__Const_8h.html">XMP_Const.h</a> for detailed information about types and constants for namespace URIs and option flags. The client templates are instantiated by including <a class="el" href="XMP_8incl__cpp.html">XMP.incl_cpp</a> in exactly one source file. The macro <code>TXMP_STRING_TYPE</code> must be defined first to provide the string class.<p> -The string class used to instantiate the templates must have the following member functions, which match those of <code>std::string:</code> <div class="fragment"><pre class="fragment"> assign ( <span class="keyword">const</span> <span class="keywordtype">char</span> * str, size_t len ) - size_t size() const - const <span class="keywordtype">char</span> * c_str() const -</pre></div> The result type of <code>assign</code> does not matter, it is always ignored.<p> -Use of the XMP Toolkit is reasonably straightforward once you understand the XMP data model. Some tips to keep in mind:<p> -<ul> -<li>All strings passed as parameters must be UTF-8. </li> -<li>All strings returned will be UTF-8. </li> -<li>Register private namespaces before use. </li> -<li>Don't depend on specific namespace prefixes. Don't hardwire the prefixes for struct fields, use functions like <code>Get/SetStructField</code> or <code>ComposeStructFieldPath</code>. </li> -<li>Use the path composition functions for complex paths with nested structs or arrays. </li> -<li>Use <code>Get/SetLocalizedText</code> when dealing with language alternative (alt-text) arrays.</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">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">TXMPMeta::GetProperty</a> ( <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6">XMP_StringPtr</a> schemaNS, - <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6">XMP_StringPtr</a> propName, - std::string * propValue, - <a class="code" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">XMP_OptionBits</a> * options )<span class="keyword"> const</span> -<span class="keyword"> </span>{ - <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6">XMP_StringPtr</a> resultPtr = 0; - <a class="code" href="XMP__Const_8h.html#9f7dcc184f901c713274edfdac5bcc9a">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 ( kXMP_NoOptions ); - } - <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">XMP_StringPtr</a> schemaNS, - <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6">XMP_StringPtr</a> propName, - <a class="code" href="XMP__Const_8h.html#d439e3ceeb4590d310f6125aa12c6df6">XMP_StringPtr</a> * propValue, - <a class="code" href="XMP__Const_8h.html#9f7dcc184f901c713274edfdac5bcc9a">XMP_StringLen</a> * valueSize, - <a class="code" href="XMP__Const_8h.html#eb865118433be92d88e5f49ed11487c8">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>, kXMPErr_BadSchema ); - } - <span class="keywordflow">if</span> ( (propName == 0) || (*propName == 0) ) { - XMP_Throw ( <span class="stringliteral">"Empty property name"</span>, kXMPErr_BadXPath ); - } - - <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. <hr size="1"><address style="align: right;"><small>Generated on Thu May 3 14:54:57 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> |