1 /* 2 * Copyright (C) 2006 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 // 18 // Class providing access to a read-only asset. Asset objects are NOT 19 // thread-safe, and should not be shared across threads. 20 // 21 #ifndef __LIBS_ASSET_H 22 #define __LIBS_ASSET_H 23 24 #include <stdio.h> 25 #include <sys/types.h> 26 #include "FileMap.h" 27 #include "String8.h" 28 #include "Errors.h" 29 30 namespace android { 31 32 /* 33 * Instances of this class provide read-only operations on a byte stream. 34 * 35 * Access may be optimized for streaming, random, or whole buffer modes. All 36 * operations are supported regardless of how the file was opened, but some 37 * things will be less efficient. [pass that in??] 38 * 39 * "Asset" is the base class for all types of assets. The classes below 40 * provide most of the implementation. The AssetManager uses one of the 41 * static "create" functions defined here to create a new instance. 42 */ 43 class Asset { 44 public: 45 virtual ~Asset(void); 46 47 static int32_t getGlobalCount(); 48 static String8 getAssetAllocations(); 49 50 /* used when opening an asset */ 51 typedef enum AccessMode { 52 ACCESS_UNKNOWN = 0, 53 54 /* read chunks, and seek forward and backward */ 55 ACCESS_RANDOM, 56 57 /* read sequentially, with an occasional forward seek */ 58 ACCESS_STREAMING, 59 60 /* caller plans to ask for a read-only buffer with all data */ 61 ACCESS_BUFFER, 62 } AccessMode; 63 64 /* 65 * Read data from the current offset. Returns the actual number of 66 * bytes read, 0 on EOF, or -1 on error. 67 */ 68 virtual ssize_t read(void* buf, size_t count) = 0; 69 70 /* 71 * Seek to the specified offset. "whence" uses the same values as 72 * lseek/fseek. Returns the new position on success, or (off_t) -1 73 * on failure. 74 */ 75 virtual off_t seek(off_t offset, int whence) = 0; 76 77 /* 78 * Close the asset, freeing all associated resources. 79 */ 80 virtual void close(void) = 0; 81 82 /* 83 * Get a pointer to a buffer with the entire contents of the file. 84 */ 85 virtual const void* getBuffer(bool wordAligned) = 0; 86 87 /* 88 * Get the total amount of data that can be read. 89 */ 90 virtual off_t getLength(void) const = 0; 91 92 /* 93 * Get the total amount of data that can be read from the current position. 94 */ 95 virtual off_t getRemainingLength(void) const = 0; 96 97 /* 98 * Open a new file descriptor that can be used to read this asset. 99 * Returns -1 if you can not use the file descriptor (for example if the 100 * asset is compressed). 101 */ 102 virtual int openFileDescriptor(off_t* outStart, off_t* outLength) const = 0; 103 104 /* 105 * Return whether this asset's buffer is allocated in RAM (not mmapped). 106 * Note: not virtual so it is safe to call even when being destroyed. 107 */ 108 virtual bool isAllocated(void) const { return false; } 109 110 /* 111 * Get a string identifying the asset's source. This might be a full 112 * path, it might be a colon-separated list of identifiers. 113 * 114 * This is NOT intended to be used for anything except debug output. 115 * DO NOT try to parse this or use it to open a file. 116 */ 117 const char* getAssetSource(void) const { return mAssetSource.string(); } 118 119 protected: 120 Asset(void); // constructor; only invoked indirectly 121 122 /* handle common seek() housekeeping */ 123 off_t handleSeek(off_t offset, int whence, off_t curPosn, off_t maxPosn); 124 125 /* set the asset source string */ 126 void setAssetSource(const String8& path) { mAssetSource = path; } 127 128 AccessMode getAccessMode(void) const { return mAccessMode; } 129 130 private: 131 /* these operations are not implemented */ 132 Asset(const Asset& src); 133 Asset& operator=(const Asset& src); 134 135 /* AssetManager needs access to our "create" functions */ 136 friend class AssetManager; 137 138 /* 139 * Create the asset from a named file on disk. 140 */ 141 static Asset* createFromFile(const char* fileName, AccessMode mode); 142 143 /* 144 * Create the asset from a named, compressed file on disk (e.g. ".gz"). 145 */ 146 static Asset* createFromCompressedFile(const char* fileName, 147 AccessMode mode); 148 149 #if 0 150 /* 151 * Create the asset from a segment of an open file. This will fail 152 * if "offset" and "length" don't fit within the bounds of the file. 153 * 154 * The asset takes ownership of the file descriptor. 155 */ 156 static Asset* createFromFileSegment(int fd, off_t offset, size_t length, 157 AccessMode mode); 158 159 /* 160 * Create from compressed data. "fd" should be seeked to the start of 161 * the compressed data. This could be inside a gzip file or part of a 162 * Zip archive. 163 * 164 * The asset takes ownership of the file descriptor. 165 * 166 * This may not verify the validity of the compressed data until first 167 * use. 168 */ 169 static Asset* createFromCompressedData(int fd, off_t offset, 170 int compressionMethod, size_t compressedLength, 171 size_t uncompressedLength, AccessMode mode); 172 #endif 173 174 /* 175 * Create the asset from a memory-mapped file segment. 176 * 177 * The asset takes ownership of the FileMap. 178 */ 179 static Asset* createFromUncompressedMap(FileMap* dataMap, AccessMode mode); 180 181 /* 182 * Create the asset from a memory-mapped file segment with compressed 183 * data. "method" is a Zip archive compression method constant. 184 * 185 * The asset takes ownership of the FileMap. 186 */ 187 static Asset* createFromCompressedMap(FileMap* dataMap, int method, 188 size_t uncompressedLen, AccessMode mode); 189 190 191 /* 192 * Create from a reference-counted chunk of shared memory. 193 */ 194 // TODO 195 196 AccessMode mAccessMode; // how the asset was opened 197 String8 mAssetSource; // debug string 198 199 Asset* mNext; // linked list. 200 Asset* mPrev; 201 }; 202 203 204 /* 205 * =========================================================================== 206 * 207 * Innards follow. Do not use these classes directly. 208 */ 209 210 /* 211 * An asset based on an uncompressed file on disk. It may encompass the 212 * entire file or just a piece of it. Access is through fread/fseek. 213 */ 214 class _FileAsset : public Asset { 215 public: 216 _FileAsset(void); 217 virtual ~_FileAsset(void); 218 219 /* 220 * Use a piece of an already-open file. 221 * 222 * On success, the object takes ownership of "fd". 223 */ 224 status_t openChunk(const char* fileName, int fd, off_t offset, size_t length); 225 226 /* 227 * Use a memory-mapped region. 228 * 229 * On success, the object takes ownership of "dataMap". 230 */ 231 status_t openChunk(FileMap* dataMap); 232 233 /* 234 * Standard Asset interfaces. 235 */ 236 virtual ssize_t read(void* buf, size_t count); 237 virtual off_t seek(off_t offset, int whence); 238 virtual void close(void); 239 virtual const void* getBuffer(bool wordAligned); 240 virtual off_t getLength(void) const { return mLength; } 241 virtual off_t getRemainingLength(void) const { return mLength-mOffset; } 242 virtual int openFileDescriptor(off_t* outStart, off_t* outLength) const; 243 virtual bool isAllocated(void) const { return mBuf != NULL; } 244 245 private: 246 off_t mStart; // absolute file offset of start of chunk 247 off_t mLength; // length of the chunk 248 off_t mOffset; // current local offset, 0 == mStart 249 FILE* mFp; // for read/seek 250 char* mFileName; // for opening 251 252 /* 253 * To support getBuffer() we either need to read the entire thing into 254 * a buffer or memory-map it. For small files it's probably best to 255 * just read them in. 256 */ 257 enum { kReadVsMapThreshold = 4096 }; 258 259 FileMap* mMap; // for memory map 260 unsigned char* mBuf; // for read 261 262 const void* ensureAlignment(FileMap* map); 263 }; 264 265 266 /* 267 * An asset based on compressed data in a file. 268 */ 269 class _CompressedAsset : public Asset { 270 public: 271 _CompressedAsset(void); 272 virtual ~_CompressedAsset(void); 273 274 /* 275 * Use a piece of an already-open file. 276 * 277 * On success, the object takes ownership of "fd". 278 */ 279 status_t openChunk(int fd, off_t offset, int compressionMethod, 280 size_t uncompressedLen, size_t compressedLen); 281 282 /* 283 * Use a memory-mapped region. 284 * 285 * On success, the object takes ownership of "fd". 286 */ 287 status_t openChunk(FileMap* dataMap, int compressionMethod, 288 size_t uncompressedLen); 289 290 /* 291 * Standard Asset interfaces. 292 */ 293 virtual ssize_t read(void* buf, size_t count); 294 virtual off_t seek(off_t offset, int whence); 295 virtual void close(void); 296 virtual const void* getBuffer(bool wordAligned); 297 virtual off_t getLength(void) const { return mUncompressedLen; } 298 virtual off_t getRemainingLength(void) const { return mUncompressedLen-mOffset; } 299 virtual int openFileDescriptor(off_t* outStart, off_t* outLength) const { return -1; } 300 virtual bool isAllocated(void) const { return mBuf != NULL; } 301 302 private: 303 off_t mStart; // offset to start of compressed data 304 off_t mCompressedLen; // length of the compressed data 305 off_t mUncompressedLen; // length of the uncompressed data 306 off_t mOffset; // current offset, 0 == start of uncomp data 307 308 FileMap* mMap; // for memory-mapped input 309 int mFd; // for file input 310 311 class StreamingZipInflater* mZipInflater; // for streaming large compressed assets 312 313 unsigned char* mBuf; // for getBuffer() 314 }; 315 316 // need: shared mmap version? 317 318 }; // namespace android 319 320 #endif // __LIBS_ASSET_H 321
