00001 00002 //------------------------------------------------------------------------------------------------- 00003 // 00004 // Module Name: ZResource.h 00005 // 00006 // General Description: classes to use and create resource files 00007 // 00008 //------------------------------------------------------------------------------------------------- 00009 // 00010 // Motorola Confidential Proprietary 00011 // Template ID and version: TMP_LFC_50068 Version 1.2 00012 // (c) Copyright Motorola 200{x}, All Rights Reserved 00013 // 00014 //------------------------------------------------------------------------------------------------- 00015 00016 #ifndef Z_RESOURCE_H 00017 #define Z_RESOURCE_H 00018 00019 #ifndef __cplusplus 00020 #error "This is a C++ header file; it requires C++ to compile." 00021 #endif 00022 00023 #include <qstring.h> 00024 #include <qpixmap.h> 00025 #include <qarray.h> 00026 #include <qsortedlist.h> 00027 00028 00029 class QFile; 00030 class ZResEntry; 00031 struct ZResHTEntry; 00032 struct ZResStartBlock; 00033 00034 00035 /** 00036 * Base class for resource readers. A resource reader is used to get icons 00037 * and other resources. Most of the methods of this class are not implemented. 00038 */ 00039 00040 class ZResReader { 00041 00042 public: 00043 00044 /** 00045 * virtual distructor. Derived classes should reimplement if they have 00046 * cleanup to do. 00047 */ 00048 virtual ~ZResReader(); 00049 00050 /** 00051 * return bool indicating whether or not a resource exists 00052 * 00053 * @param ID resource ID to lookup (something.g for a graphic, for example) 00054 * @return bool indicating whether or not the resource exists 00055 * 00056 */ 00057 virtual bool exists(const QString& ID) const = 0; 00058 00059 /** 00060 * get data for a resource. 00061 * 00062 * @param ID the resource ID for the resource 00063 * @param ppOutData out-pointer for the resource data 00064 * @param pOutLength out-integer for the size in bytes of the data 00065 * 00066 * @note Do not delete/de-allocate the pointer returned from this function. 00067 * 00068 */ 00069 virtual bool get(const QString& ID, unsigned char** ppOutData, 00070 int* pOutLength) const = 0; 00071 00072 /** 00073 * get the first resource ID in this resource reader 00074 * 00075 * @note this function is not thread safe 00076 * @return first resource ID 00077 */ 00078 virtual QString getFirstID(); 00079 00080 /** 00081 * get the next resource ID in this resource reader 00082 * 00083 * @note this function in not thread safe 00084 * @return current resource ID, increments iterator 00085 */ 00086 virtual QString getNextID(); 00087 00088 }; 00089 00090 //---------------------------------------------------------------------------- 00091 // CLASS ZResFileReader 00092 //---------------------------------------------------------------------------- 00093 00094 /** 00095 * class to read resource files written by a ZResFileWriter 00096 * 00097 * Use ZResFileReader to read QPixmaps or other data from a single resource 00098 * file. If you want to use the current application skin (which is made of 00099 * a number of resource files, see ZSkin. 00100 * 00101 * @note you can see what resources are in a resource file by opening the 00102 * file with a text editor. The beginning of the file contains an easily 00103 * readable list of resource names. 00104 * 00105 */ 00106 00107 class ZResFileReader : public ZResReader 00108 { 00109 public: 00110 00111 /** 00112 * default constructor 00113 */ 00114 ZResFileReader(); 00115 00116 /** 00117 * constructor taking a file name as an argument 00118 */ 00119 ZResFileReader(const QString& fileName); 00120 00121 00122 /** 00123 * destructor 00124 */ 00125 virtual ~ZResFileReader(); 00126 00127 /** 00128 * sets the filename for this resource reader. This causes any previously 00129 * opened resource file to be closed. 00130 * 00131 * @param fileName the filename to open 00132 * @return true if the file was successfully openend, false otherwise 00133 * 00134 * @note any pointers returned from this object before calling this function 00135 * should be considered invalid 00136 */ 00137 bool setFileName(const QString& fileName); 00138 00139 /** 00140 * return the filename used by this resource reader 00141 */ 00142 const QString& fileName() const; 00143 00144 /** 00145 * return a value indicating whether or not a given string ID exists 00146 * 00147 * @return bool indicating whether or not a resource exists 00148 */ 00149 virtual bool exists(const QString& ID) const; 00150 00151 /** 00152 * get data for a resource. 00153 * 00154 * @param ID the resource ID for the resource 00155 * @param ppOutData out-pointer for the resource data 00156 * @param pOutLength out-integer for the size in bytes of the data 00157 * 00158 * @note Do not delete/de-allocate the pointer returned from this function. 00159 * 00160 */ 00161 virtual bool get(const QString& ID, unsigned char** ppOutData, 00162 int* pOutLength) const; 00163 00164 /** 00165 * get the first resource ID in this resource reader 00166 * 00167 * @note this function is not thread safe 00168 * @return first resource ID 00169 */ 00170 virtual QString getFirstID(); 00171 00172 /** 00173 * get the next resource ID in this resource reader 00174 * 00175 * @note this function in not thread safe 00176 * @return current resource ID, increments iterator 00177 */ 00178 virtual QString getNextID(); 00179 00180 00181 protected: 00182 00183 /** 00184 * init is called by the constructors 00185 */ 00186 void init(const QString& fileName); 00187 00188 /** 00189 * reset resets the object state 00190 */ 00191 void reset(); 00192 00193 /** 00194 * load actually loads the resource table 00195 */ 00196 bool bLoadFailed; 00197 bool load(); 00198 00199 /** 00200 * getID return the resource ID for a given hash table 00201 * entry number 00202 */ 00203 QString getID(unsigned hashTableEntryNum) const; 00204 00205 /** 00206 * returns a pointer to a hashTableEntry for a given ID 00207 */ 00208 const ZResHTEntry *getHashTableEntry(const QString& ID) const; 00209 00210 /** 00211 * returns a pointer to the data at a given file offset 00212 * returns false if an error occurs. 00213 */ 00214 bool getDataAtOffset(unsigned offset, 00215 unsigned char **ppOutData, 00216 int *pOutLength) const; 00217 00218 bool getDataAtOffset(unsigned offset, 00219 QString& resourceFileName, 00220 unsigned char **ppOutData, 00221 int *pOutLength) const; 00222 00223 QString m_fileName; ///< the name of the resource file 00224 00225 bool loaded; 00226 int fd; 00227 unsigned int fileLength; 00228 unsigned char *pResources; 00229 00230 unsigned char *pIDs; 00231 unsigned hashTableSize; 00232 ZResHTEntry *pHashTable; 00233 unsigned char *pData; 00234 unsigned char *pEnd; 00235 00236 unsigned currentIteratorEntry; 00237 00238 }; 00239 00240 00241 /** 00242 * class to create a resource file 00243 */ 00244 00245 class ZResFileWriter { 00246 00247 public: 00248 00249 /** 00250 * constructor 00251 */ 00252 00253 ZResFileWriter(); 00254 00255 /** 00256 * constructor taking an output file name 00257 */ 00258 00259 ZResFileWriter(const QString& fileName); 00260 00261 /** 00262 * set the output filename 00263 * 00264 * @param fileName name of the file to write 00265 */ 00266 00267 void setFileName(const QString& fileName); 00268 00269 /** 00270 * get the current filename being written to 00271 * 00272 * @return reference to the filename being written to 00273 */ 00274 00275 const QString& fileName() const; 00276 00277 /** 00278 * throw away all data and start at the beginning 00279 */ 00280 00281 void reset(); 00282 00283 /** 00284 * add a block of data to the resource file 00285 * 00286 * @param ID resource ID of data to add 00287 * @param data QByteArray of the data to add 00288 */ 00289 00290 void add(const QString& ID, const QByteArray& data); 00291 00292 /** 00293 * write the resource file 00294 * 00295 * @return true if write succeeded 00296 */ 00297 00298 bool write(); 00299 00300 protected: 00301 00302 void init(const QString& fullFileName); 00303 00304 QString m_fileName; ///< file name that we're writing to 00305 00306 bool createTables(); 00307 bool writeHeader(QFile&); 00308 bool writeIDs(QFile&); 00309 bool writeStartBlock(QFile&); 00310 bool writeHashTable(QFile&); 00311 bool writeData(QFile&); 00312 bool deleteTables(); 00313 00314 QSortedList<ZResEntry> list; ///< list of resources before they're written to disk 00315 00316 unsigned int hashTableSize; 00317 ZResHTEntry *hashTable; 00318 bool hash(const QString& ID, const QByteArray& inData); 00319 00320 int nextLabelOffset; 00321 int nextDataOffset; 00322 }; 00323 00324 #endif // Z_RESOURCE_H