Home | History | Annotate | Download | only in android 
      1 /*
      2  * Copyright (C) 2010 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 #ifndef ANDROID_ASSET_MANAGER_H
     19 #define ANDROID_ASSET_MANAGER_H
     20 
     21 #include <sys/types.h>
     22 
     23 #ifdef __cplusplus
     24 extern "C" {
     25 #endif
     26 
     27 struct AAssetManager;
     28 typedef struct AAssetManager AAssetManager;
     29 
     30 struct AAssetDir;
     31 typedef struct AAssetDir AAssetDir;
     32 
     33 struct AAsset;
     34 typedef struct AAsset AAsset;
     35 
     36 /* Available modes for opening assets */
     37 enum {
     38     AASSET_MODE_UNKNOWN      = 0,
     39     AASSET_MODE_RANDOM       = 1,
     40     AASSET_MODE_STREAMING    = 2,
     41     AASSET_MODE_BUFFER       = 3
     42 };
     43 
     44 
     45 /**
     46  * Open the named directory within the asset hierarchy.  The directory can then
     47  * be inspected with the AAssetDir functions.  To open the top-level directory,
     48  * pass in "" as the dirName.
     49  *
     50  * The object returned here should be freed by calling AAssetDir_close().
     51  */
     52 AAssetDir* AAssetManager_openDir(AAssetManager* mgr, const char* dirName);
     53 
     54 /**
     55  * Open an asset.
     56  *
     57  * The object returned here should be freed by calling AAsset_close().
     58  */
     59 AAsset* AAssetManager_open(AAssetManager* mgr, const char* filename, int mode);
     60 
     61 /**
     62  * Iterate over the files in an asset directory.  A NULL string is returned
     63  * when all the file names have been returned.
     64  *
     65  * The returned file name is suitable for passing to AAssetManager_open().
     66  *
     67  * The string returned here is owned by the AssetDir implementation and is not
     68  * guaranteed to remain valid if any other calls are made on this AAssetDir
     69  * instance.
     70  */
     71 const char* AAssetDir_getNextFileName(AAssetDir* assetDir);
     72 
     73 /**
     74  * Reset the iteration state of AAssetDir_getNextFileName() to the beginning.
     75  */
     76 void AAssetDir_rewind(AAssetDir* assetDir);
     77 
     78 /**
     79  * Close an opened AAssetDir, freeing any related resources.
     80  */
     81 void AAssetDir_close(AAssetDir* assetDir);
     82 
     83 /**
     84  * Attempt to read 'count' bytes of data from the current offset.
     85  *
     86  * Returns the number of bytes read, zero on EOF, or < 0 on error.
     87  */
     88 int AAsset_read(AAsset* asset, void* buf, size_t count);
     89 
     90 /**
     91  * Seek to the specified offset within the asset data.  'whence' uses the
     92  * same constants as lseek()/fseek().
     93  *
     94  * Returns the new position on success, or (off_t) -1 on error.
     95  */
     96 off_t AAsset_seek(AAsset* asset, off_t offset, int whence);
     97 
     98 /**
     99  * Close the asset, freeing all associated resources.
    100  */
    101 void AAsset_close(AAsset* asset);
    102 
    103 /**
    104  * Get a pointer to a buffer holding the entire contents of the assset.
    105  *
    106  * Returns NULL on failure.
    107  */
    108 const void* AAsset_getBuffer(AAsset* asset);
    109 
    110 /**
    111  * Report the total size of the asset data.
    112  */
    113 off_t AAsset_getLength(AAsset* asset);
    114 
    115 /**
    116  * Report the total amount of asset data that can be read from the current position.
    117  */
    118 off_t AAsset_getRemainingLength(AAsset* asset);
    119 
    120 /**
    121  * Open a new file descriptor that can be used to read the asset data.
    122  *
    123  * Returns < 0 if direct fd access is not possible (for example, if the asset is
    124  * compressed).
    125  */
    126 int AAsset_openFileDescriptor(AAsset* asset, off_t* outStart, off_t* outLength);
    127 
    128 /**
    129  * Returns whether this asset's internal buffer is allocated in ordinary RAM (i.e. not
    130  * mmapped).
    131  */
    132 int AAsset_isAllocated(AAsset* asset);
    133 
    134 
    135 
    136 #ifdef __cplusplus
    137 };
    138 #endif
    139 
    140 #endif      // ANDROID_ASSET_MANAGER_H
    141