resources.h

Go to the documentation of this file.
00001 /*
00002  * resources.h
00003  *
00004  * Copyright 2002,2010 Thomas A. Vaughan
00005  * All rights reserved.
00006  *
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *     * Redistributions of source code must retain the above copyright
00011  *       notice, this list of conditions and the following disclaimer.
00012  *     * Redistributions in binary form must reproduce the above copyright
00013  *       notice, this list of conditions and the following disclaimer in the
00014  *       documentation and/or other materials provided with the distribution.
00015  *     * Neither the name of the <organization> nor the
00016  *       names of its contributors may be used to endorse or promote products
00017  *       derived from this software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
00020  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
00023  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00026  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  *
00030  * Support for resources (strings, binary objects, etc.) built into the
00031  * executable.
00032  */
00033 
00034 #ifndef WAVEPACKET_RESOURCES_H__
00035 #define WAVEPACKET_RESOURCES_H__
00036 
00037 
00038 // includes --------------------------------------------------------------------
00039 #include "common/common.h"
00040 
00041 
00042 ////////////////////////////////////////////////////////////////////////////////
00043 ///
00044 /// \ingroup common
00045 ///
00046 /// \defgroup common_resources Resource APIs
00047 ///
00048 /// These APIs support the ability to build resources (strings, binary
00049 /// objects, etc.) directly into the binary for later reference.
00050 ///
00051 /// At the moment support is somewhat hacky, but can be improved over time.
00052 ///
00053 /// Some limitations (aka design features) of the current API:
00054 ///
00055 ///  - A "resource" is defined as the full contents of a specified file.
00056 ///
00057 ///  - Only string resources are supported for now.
00058 ///
00059 ///  - The build system will create a local source file named "resources-CODEGEN.cpp",
00060 ///     so don't use that name for another source file!  It will be destroyed.
00061 ///
00062 /// \n
00063 /// To use resources in your binary, add resource definitions to the config
00064 /// file.  As an example:
00065 /// \code
00066 ///     resource {
00067 ///             namespace       foo             # must specify namespace
00068 ///             type            string          # this is the only type supported
00069 ///             name            my-resource     # any text will do
00070 ///             file            foobar.txt      # local file
00071 ///     }
00072 /// \endcode
00073 /// That will create a resource named "my-resource" whose value is the contents
00074 /// of the file "foobar.txt".
00075 ///
00076 /// A namespace is just a string identifier, which should be reasonably unique
00077 /// so you won't have collisions with other libraries that are declaring their
00078 /// own resources.
00079 ///
00080 /// \b NOTE: this is the same config file that is used by the \ref build.
00081 /// See that documentation for more information.
00082 ///
00083 /// Once a resource has been declared and named in the config file, and the
00084 /// application is rebuilt, the resource can be retrieved within the application
00085 /// code by calling getStringResource().
00086 ///
00087 /// Notes on the \p resource entry:
00088 ///  - \p file is a required tag
00089 ///  - if no \p type is supplied, \p string is assumed.
00090 ///  - if no \p name is supplied, it is assumed to be the same name as the
00091 ///     \p file.
00092 ///
00093 /// For example, this resource entry:
00094 /// \code
00095 ///     resource {
00096 ///             namespace       foo
00097 ///             file            license.txt
00098 ///     }
00099 /// \endcode
00100 /// is equivalent to:
00101 /// \code
00102 ///     resource {
00103 ///             namespace       foo
00104 ///             type            string          # type 'string' is assumed as default
00105 ///             name            license.txt     # name is assumed to be filename
00106 ///             file            license.txt
00107 ///     }
00108 /// \endcode
00109 /// \n
00110 /// That is, within the application code you can now call
00111 /// \b getStringResource("foo", "license.txt") to retrieve
00112 /// a string containing the full contents of license.txt.
00113 ///
00114 /// \n
00115 /// TODO: support other resource types.
00116 ///
00117 ////////////////////////////////////////////////////////////////////////////////
00118 
00119 /*@{*/
00120 
00121 
00122 /// retrieve the number of namespaces
00123 int getResourceNamespaceCount(void) throw();
00124 
00125 
00126 /// retrieve the indexed namespace name.  Returns NULL on invalid input
00127 const char * getResourceNamespaceName(IN int index) throw();
00128 
00129 
00130 /// retrieve the number of string resources in the specified namespace
00131 int getStringResourceCount(IN const char * nameSpace) throw();
00132 
00133 
00134 /// retrieve the name of a given string resource
00135 const char * getStringResourceName(IN const char * nameSpace,
00136                                 IN int index) throw();
00137 
00138 
00139 /// retrieve a string resource by name (returns NULL if not found)
00140 const char * getStringResource(IN const char * nameSpace,
00141                                 IN const char * name) throw();
00142 
00143 
00144 /// register a new string resource in the given namespace
00145 void registerStringResource(IN const char * nameSpace,
00146                                 IN const char * name,
00147                                 IN const char * value);
00148 
00149 
00150 #endif  // WAVEPACKET_RESOURCES_H__
00151