本文来自http://blog.csdn.net/runaying ，引用必须注明出处！
cocos2d-x节点（CCFileUtils.h)API
温馨提醒：为了大家能更好学习，强烈推荐大家看看本人的这篇博客 Cocos2d-X权威指南笔记
辅助类来处理文件操作，各种平台文件的搜索
///cocos2d-x-3.0alpha0/cocos2dx/platform
//辅助类来处理文件操作，各种平台文件的搜索
#ifndef __CC_FILEUTILS_H__
#define __CC_FILEUTILS_H__
#include <string>
#include <vector>
#include <map>
#include "CCPlatformMacros.h"
#include "ccTypes.h"
NS_CC_BEGIN
class Dictionary;
class Array;
/**
* @addtogroup platform
* @{
*/
//! @brief 辅助类来处理文件操作
class CC_DLL FileUtils
{
friend class Array;
friend class Dictionary;
public:
/**
* Gets FileUtils 实例.
*/
static FileUtils* getInstance();
/**
* 销毁 FileUtils 实例.
*/
static void destroyInstance();
/** @过时不再需要建议使用新的 API ，可以使用 getInstance() 代替 */
CC_DEPRECATED_ATTRIBUTE static FileUtils* sharedFileUtils() { return getInstance(); }
/** @过时不再需要建议使用新的 API ，可以使用 destroyInstance() 代替 */
CC_DEPRECATED_ATTRIBUTE static void purgeFileUtils() { destroyInstance(); }
/**
* FileUtils 的析构函数.
* @js NA
* @lua NA
*/
virtual ~FileUtils();
/**
* 清除文件搜索缓存.
*
* @note 更新资源后应该被调用.
* 例如，在 CocosPlayer sample, 每次你从 CocosBuilder 里面运行应用程序 ,
* 新的JS应用程序启动之前,所有的资源将被下载到可写文件夹
* 调用这个方法用来清理文件搜索缓存.
*/
virtual void purgeCachedEntries();
/**
* 获取资源文件中的数据
*
* @param[in] filename 包含资源文件名文件名的路径
* @param[in] pszMode 该文件的阅读模式.
* @param[out] pSize 如果该文件的读操作成功，这将是数据的大小, otherwise 0.
* @return 一旦成功，则返回一个指向数据的指针, otherwise NULL.
* @warning Recall（记得）: 返回任何非空指针时，你是负责调用delete[].
*/
virtual unsigned char* getFileData(const char* filename, const char* mode, unsigned long * size);
/**
* 从一个zip文件，获取资源文件数据.
*
* @param[in] filename 包含zip文件相对路径的资源文件名.
* @param[out] size 如果该文件的读操作成功，这将是数据的大小,, otherwise 0.
* @return Upon success, a pointer to the data is returned, otherwise NULL.
* @warning Recall（记得）: 返回任何非空指针时，你是负责调用delete[].
*/
virtual unsigned char* getFileDataFromZip(const char* zipFilePath, const char* filename, unsigned long *size);
/** 返回一个给定的文件名的完整路径。
首先，它会尝试从“filenameLookup”字典，得到一个新的文件名
如果不能从字典里找到一个新的文件名，它会使用原来的文件名
然后，它会尝试使用 FileUtils 搜索规则：搜索文件名的完整路径
文件搜索是基于解析目录和搜索路径的数组元素的顺序.
例如:
使用 setSearchPaths 的搜索路径向量，设置了两个元素 ("/mnt/sdcard/", "internal_dir/"),
and 使用 setSearchResolutionsOrder 的解析向量，来设置三个元素("resources-ipadhd/", "resources-ipad/", "resources-iphonehd")
"internal_dir"是相对于 "Resources/".
如果我们有一个名为'sprite.png'，映射 fileLookup 字典包含 `key: sprite.png -> value: sprite.pvr.gz`.
首先，它会使用'sprite.pvr.gz'替换 'sprite.png' , 然后搜索文件 sprite.pvr.gz 如下:
/mnt/sdcard/resources-ipadhd/sprite.pvr.gz (if not found, search next)
/mnt/sdcard/resources-ipad/sprite.pvr.gz (if not found, search next)
/mnt/sdcard/resources-iphonehd/sprite.pvr.gz (if not found, search next)
/mnt/sdcard/sprite.pvr.gz (if not found, search next)
internal_dir/resources-ipadhd/sprite.pvr.gz (if not found, search next)
internal_dir/resources-ipad/sprite.pvr.gz (if not found, search next)
internal_dir/resources-iphonehd/sprite.pvr.gz (if not found, search next)
internal_dir/sprite.pvr.gz (if not found, return "sprite.png")
如果文件名包含相对路径，如 "gamescene/uilayer/sprite.png",
and 映射 fileLookup 字典包含 `key: gamescene/uilayer/sprite.png -> value: gamescene/uilayer/sprite.pvr.gz`.
文件搜索顺序将是:
/mnt/sdcard/gamescene/uilayer/resources-ipadhd/sprite.pvr.gz (if not found, search next)
/mnt/sdcard/gamescene/uilayer/resources-ipad/sprite.pvr.gz (if not found, search next)
/mnt/sdcard/gamescene/uilayer/resources-iphonehd/sprite.pvr.gz (if not found, search next)
/mnt/sdcard/gamescene/uilayer/sprite.pvr.gz (if not found, search next)
internal_dir/gamescene/uilayer/resources-ipadhd/sprite.pvr.gz (if not found, search next)
internal_dir/gamescene/uilayer/resources-ipad/sprite.pvr.gz (if not found, search next)
internal_dir/gamescene/uilayer/resources-iphonehd/sprite.pvr.gz (if not found, search next)
internal_dir/gamescene/uilayer/sprite.pvr.gz (if not found, return "gamescene/uilayer/sprite.png")
如果无法找在文件系统上到新的文件，它会直接返回 filename 参数.
加入这个方法来简化多平台支持。无论您使用的cocos2d-js或任何交叉编译工具像StellaSDK或Apportable的，
对于一个给定的文件在不同的平台，您可能需要加载不同的资源，
@since v2.1
*/
virtual std::string fullPathForFilename(const std::string &filename);
/**
* 从 filename 内容上，加载 filenameLookup（文件名查找）字典.
*
* @note plist文件名应该遵循下面的格式:
*
* @code
* <?xml version="1.0" encoding="UTF-8"?>
* <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
* <plist version="1.0">
* <dict>
* <key>filenames</key>
* <dict>
* <key>sounds/click.wav</key>
* <string>sounds/click.caf</string>
* <key>sounds/endgame.wav</key>
* <string>sounds/endgame.caf</string>
* <key>sounds/gem-0.wav</key>
* <string>sounds/gem-0.caf</string>
* </dict>
* <key>metadata</key>
* <dict>
* <key>version</key>
* <integer>1</integer>
* </dict>
* </dict>
* </plist>
* @endcode
* @param filename plist文件名
*
@since v2.1
* @js loadFilenameLookup
* @lua loadFilenameLookup
*/
virtual void loadFilenameLookupDictionaryFromFile(const std::string &filename);
/**
* Sets the filenameLookup dictionary.
*
* @param pFilenameLookupDict The dictionary for replacing(替换) filename.
* @since v2.1
*/
virtual void setFilenameLookupDictionary(Dictionary* filenameLookupDict);
/**
* 获取相对于路径的完整路径的文件名和路径.
* @param filename The file name.
* @param pszRelativeFile 相对文件的路径.
* @return The full path.
* e.g. filename: hello.png, pszRelativeFile: /User/path1/path2/hello.plist
* Return: /User/path1/path2/hello.pvr (If there a a key(hello.png)-value(hello.pvr) in FilenameLookup dictionary. )
*
*/
virtual std::string fullPathFromRelativeFile(const std::string &filename, const std::string &relativeFile);
/** 设置包含资源搜索顺序的 array
*
* @param searchResolutionsOrder 这个原始的 array 包含资源搜索顺序.
* @see getSearchResolutionsOrder(void), fullPathForFilename(const char*).
* @since v2.1
* In js:var setSearchResolutionsOrder(var jsval)
* @lua NA
*/
virtual void setSearchResolutionsOrder(const std::vector<std::string>& searchResolutionsOrder);
/**
* 追加资源搜索顺序。
*
* @see setSearchResolutionsOrder(), fullPathForFilename().
* @since v2.1
*/
virtual void addSearchResolutionsOrder(const std::string &order);
/**
* 获取包含资源搜索顺序的 array.
*
* @see setSearchResolutionsOrder(const std::vector<std::string>&), fullPathForFilename(const char*).
* @since v2.1
* @lua NA
*/
virtual const std::vector<std::string>& getSearchResolutionsOrder();
/**
* 设置搜索路径数组.
*
* 您可以使用此数组来修改资源的搜索路径.
* 如果你希望在在 "cache" 里面使用 "themes" 、搜索资源, 你可以在这个数组中添加新条目轻松地做到这一点
*
* @note 此方法可以访问相对路径和绝对路径.
* 如果相对路径传递的 vector(矢量)，FileUtils 在添加默认的资源目录前添加相对路径.
* 例如:
* 在Android上，默认的资源根路径 "assets/".
* 如果 "/mnt/sdcard/" 、 "resources-large" 被设置为搜索路径矢量
* "resources-large" 将转化为 "assets/resources-large" 因为它是一个相对路径.
*
* @param searchPaths 该数组包含搜索路径.
* @see fullPathForFilename(const char*)
* @since v2.1
* In js:var setSearchPaths(var jsval);
* @lua NA
*/
virtual void setSearchPaths(const std::vector<std::string>& searchPaths);
/**
* Add search path.
*
* @since v2.1
*/
void addSearchPath(const std::string & path);
/**
* 获取数组的搜索路径
*
* @return 搜索路径 array .
* @see fullPathForFilename(const char*).
* @lua NA
*/
virtual const std::vector<std::string>& getSearchPaths() const;
/**
* 获取可写的路径.
* @return 在路径里面可以 write/read 文件
*/
virtual std::string getWritablePath() const = 0;
/**
* 检查文件是否存在。
*
* @note 如果使用相对路径传递，它会在开始的时候插入了一个默认的根路径
* @param strFilePath 文件的路径，它可能是一个相对或绝对路径
* @return true if the file exists, otherwise it will return false.
*/
virtual bool isFileExist(const std::string& filePath) const = 0;
/**
* 检查路径是否是绝对路径。
*
* @note 在Android上，如果传入的参数是相对于 "assets/", 这个方法将把它作为一个绝对路径。.
* Blackberry(黑莓),也开始以 "app/native/Resources/" 路径作为一个绝对路径
*
* @param strPath 这个路径需要进行检查
* @return true if it's an absolute path, otherwise it will return false.
*/
virtual bool isAbsolutePath(const std::string& path) const;
/**
* Sets/Gets 失败时是否加载图像弹出一个消息框.
*/
virtual void setPopupNotify(bool notify);
virtual bool isPopupNotify();
protected:
/**
* 默认构造函数。
*/
FileUtils();
/**
* 初始化 FileUtils 实例. 将设置 set _searchPathArray 、 _searchResolutionsOrderArray 为默认值.
*
* @note 当你移植 Cocos2D-X 到一个新的平台你可能需要小心使用这个方法.
* 你可以为 FileUtils 子类的 _defaultResRootPath 指定一个默认值(e.g. FileUtilsAndroid). 然后调用 FileUtils::init().
* @return true if successed, otherwise it returns false.
*
*/
virtual bool init();
/**
* Gets 文件名查找字典获取新的文件名.
* 它可能会有一个 override names.
* @param filename 原来的文件名.
* @return 文件名查找字典搜索到的新的文件名.
* 如果原来的文件名是字典中没有的，它会返回原来的文件名.
*/
virtual std::string getNewFilename(const std::string &filename);
/**
* 使用 resolution directory 、 search path 获取 filename 的完整路径
*
* @param filename 文件名.
* @param resolutionDirectory 解析字典.
* @param searchPath 搜索路径.
* @return file 的完整路径. 如果这个file 的完整路径不存在它会返回一个 empty string
*/
virtual std::string getPathForFilename(const std::string& filename, const std::string& resolutionDirectory, const std::string& searchPath);
/**
* 使用 the directory 、 the filename 获取完整的路径.
*
* @note 只有iOS和Mac的需要重写此方法，因为他们使用的是
* `[[NSBundle mainBundle] pathForResource: ofType: inDirectory:]` 来查找完整路径.
* 其他的平台都使用了默认实现的这种方法
* @param strDirectory 这个目录包含我们正在寻找的文件.
* @param strFilename The name of the file.
* @return file 的完整路径. 如果这个file 的完整路径不存在它会返回一个 empty string
*/
virtual std::string getFullPathForDirectoryAndFilename(const std::string& directory, const std::string& filename);
/**
* 使用文件内容创建一个字典.
* @note 此方法是在内部使用.
*/
virtual Dictionary* createDictionaryWithContentsOfFile(const std::string& filename);
/**
* 把一个字典写入到 plist file.
* @note 此方法是在内部使用.
*/
virtual bool writeToFile(Dictionary *dict, const std::string& fullPath);
/**
* 使用文件内容创建一个 array.
* @note 此方法是在内部使用.
*/
virtual Array* createArrayWithContentsOfFile(const std::string& filename);
/** 使用一个 key 来查找字典中的文件名
* 它是在内部使用，通过下面的方法:
*
* std::string fullPathForFilename(const char*);
*
* @since v2.1
*/
Dictionary* _filenameLookupDict;
/**
* 该矢量包含解析文件夹.
* 在这个 vector（矢量）里面 较低的 index（索引），在这个解析字典里面有较高的优先级
*/
std::vector<std::string> _searchResolutionsOrderArray;
/**
* 该矢量包含搜索路径.
* 在这个 vector（矢量）里面 较低的 index（索引），在这个搜索路径里面有较高的优先级
*/
std::vector<std::string> _searchPathArray;
/**
* 默认资源的根路径。
* 如果默认的资源根路径需要改变，可以在 FileUtils's 子类的 `init` 方法里面修改它
* 例如:
* 在Android上，默认的资源根路径，会在 FileUtilsAndroid::init() 里面分配给他 "assets/" .
* 同样，黑莓，我们在 FileUtilsBlackberry::init() 指定这个变量为 "app/native/Resources/"
*/
std::string _defaultResRootPath;
/**
* 完整路径缓存. 当一个文件被找到，它会被添加到这个缓存
* 此变量用于提高文件搜索的性能
*/
std::map<std::string, std::string> _fullPathCache;
/**
* 这个单例指向 FileUtils.
*/
static FileUtils* s_sharedFileUtils;
};
// end of platform group
/// @}
NS_CC_END
#endif // __CC_FILEUTILS_H__