cocos2d-x节点（CCFileUtils.h)API

本文来自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__