CustomData.h

Go to the documentation of this file.

//! @file CustomData.h
//! @brief CCustomData class is a handly class for storing any kind of data
//!
//////////////////////////////////////////////////////////////////////
 
#if !defined(AFX_CUSTOMDATA_H__5D9D5366_1E68_11D3_A381_EA02A046C52E__INCLUDED_)
#define AFX_CUSTOMDATA_H__5D9D5366_1E68_11D3_A381_EA02A046C52E__INCLUDED_
 
#ifdef _MSC_VER
#pragma once
#endif // _MSC_VER
 
#include "XThreadSync.h"
 
BEGIN_MOOTOOLS_NAMESPACE
 
typedef struct CustomPrivateDataOld CustomPrivateDataOld;
 
// Contains the information which is stored on files
// (No pointer reference because the size differs from x32 to x64)
typedef struct CustomPrivateDataInfo
{
    unsigned int id;
    unsigned int size;
    unsigned int kindof;
} CustomPrivateDataInfo;
 
typedef struct CustomPrivateData
{
    CustomPrivateDataInfo info;
    unsigned int beginOfData;
} CustomPrivateData;
 
#define CUSTOMDATA_NODATA           0
#define CUSTOMDATA_UNDEFINED        MAKE_CUSTOM_ID(' ', ' ', ' ', ' ') // Only for compatibility with previous CCustomData storage
#define CUSTOMDATA_ANSI_TEXT        MAKE_CUSTOM_ID('A', 'N', 'S', 'I')
#define CUSTOMDATA_UTF8_TEXT        MAKE_CUSTOM_ID('U', 'T', 'F', '8')
#define CUSTOMDATA_UNICODE_TEXT     MAKE_CUSTOM_ID('U', 'N', 'I', 'C') // Unicode xStringUtf16 only
#define CUSTOMDATA_BOOL             MAKE_CUSTOM_ID('B', 'O', 'O', 'L')
#define CUSTOMDATA_CHAR             MAKE_CUSTOM_ID('C', 'H', 'A', 'R')
#define CUSTOMDATA_UCHAR            MAKE_CUSTOM_ID('U', 'C', 'H', 'R')
#define CUSTOMDATA_FLOAT            MAKE_CUSTOM_ID('F', 'L', 'O', 'A')
#define CUSTOMDATA_DOUBLE           MAKE_CUSTOM_ID('D', 'O', 'U', 'B')
#define CUSTOMDATA_BIN              MAKE_CUSTOM_ID(' ', 'B', 'I', 'N')
#define CUSTOMDATA_OLDCUSTDATA      MAKE_CUSTOM_ID('C', 'D', 'A', 'T')
#define CUSTOMDATA_CUSTDATA         MAKE_CUSTOM_ID('C', 'D', 'A', '2')
#define CUSTOMDATA_UINT             MAKE_CUSTOM_ID('U', 'I', 'N', 'T')
#define CUSTOMDATA_INT              MAKE_CUSTOM_ID(' ', 'I', 'N', 'T')
#define CUSTOMDATA_LONG             MAKE_CUSTOM_ID('L', 'O', 'N', 'G')  // 4 bits
#define CUSTOMDATA_ULONG            MAKE_CUSTOM_ID('U', 'L', 'O', 'N')  // 4 bits
#define CUSTOMDATA_LONGINT          MAKE_CUSTOM_ID('L', 'L', 'O', 'N')  // 8 bits
#define CUSTOMDATA_ULONGINT         MAKE_CUSTOM_ID('U', 'L', 'L', 'O')  // 8 bits
#define CUSTOMDATA_ANSI_STRINGS     MAKE_CUSTOM_ID('A', 'S', 'T', 'R')
#define CUSTOMDATA_UTF8_STRINGS     MAKE_CUSTOM_ID('U', '8', 'T', 'R')
#define CUSTOMDATA_UNICODE_STRINGS  MAKE_CUSTOM_ID('U', 'S', 'T', 'R')
#define CUSTOMDATA_PTR              MAKE_CUSTOM_ID('P', 'T', 'R', ' ')
#define CUSTOMDATA_PTR64            MAKE_CUSTOM_ID('P', 'T', 'R', '6')
#define CUSTOMDATA_ARRAY            MAKE_CUSTOM_ID('A', 'R', 'R', 'A')
#define CUSTOMDATA_UTCTIME          MAKE_CUSTOM_ID('T', 'I', 'M', 'E') // UTC time
#define CUSTOMDATA_XTIME            MAKE_CUSTOM_ID('T', 'I', 'M', 'X') // xTime
 
#ifdef __64BITS__
#define PREFERENCE_DATA_ID MAKE_CUSTOM_ID('S', 'E', '6', '4')
#else
#define PREFERENCE_DATA_ID MAKE_CUSTOM_ID('S', 'E', 'T', 'T')
#endif
 
//! @enum CUSTOMDATA_COPY_FLAGS
//! Flags for controling the way custom data are copied
typedef enum CUSTOMDATA_COPY_FLAGS
{
    CUSTOMDATA_COPY_DEFAULT = 0x00,     //!< Same has operator =
    CUSTOMDATA_COPY_NEWID = 0x01,       //!< Copy only id from source that are not in destination
    CUSTOMDATA_COPY_KEEP_CONTENT = 0x02,//!< Keep content of destination when copying 
} CUSTOMDATA_COPY_FLAGS;
 
class CCustomData;
 
//! @class CCustomDataClass
//! @brief CCustomDataClass can be derived to use CCustomData::GetCustomClass / CCustomData::SetCustomClass
class CCustomDataClass
{
    friend CCustomData;
 
protected:
    virtual void InitData() = 0;
    virtual bool SetData(CCustomData& data) const = 0;
    virtual bool GetData(const CCustomData& data) = 0;
};
 
 
//! @class CCustomData
//! @brief CCustomData is a handly class for storing any kind of data.
//! @par
//! Each data is defined by its identifier. This identifier can be constructed using the #MAKE_CUSTOM_ID macro.\n
//! Using your own identifiers, you can associate your own data to any classes that give access to a CCustomData object (which is the case of many classes in the SDK)\n
//! These data follow the classes and you can retrieve them after different operations that might occur on the classes data.
//! @par
//! A data store in CCustomData has a type. If you use CCustomData::SetString with an id and use that's id to retrieve an int using CCustomData::GetInt, you'll get nothing.\n
//! This is why, when some data are store in CCustomData, you'll find the type of the data.\n
//! For example, #FBX_IO_OPTION_PASSWORD defines in #io3dmgr.h specifies that the data is a CXString. You must use CCustomData::SetString to define the fbx password through the CSceneImportOptions / CSceneExportOptions.
//! @par
//! The CCustomData data can be read/save through the CCustomData::Serialize process\n
//! CCustomData::LoadFromPrefs / CCustomData::SaveToPrefs allow to load/store the data on disk
class DLL_TOOLSFUNCTION CCustomData
{
private:
    // To be deleted, as it dangerous to use
    CCustomData *operator=(const CCustomData *) const
    {
        XASSERT(0);
        return NULL;
    }
 
    inline CustomPrivateData *GetNewChunkEntry() const;
    inline CustomPrivateData *GetNextChunk(CustomPrivateData *parsedata) const;
    inline CustomPrivateData *GetLastChunk() const;
 
    typedef CHashMap<unsigned int, unsigned int, unsigned int> CCustomDataHashID;
    CCustomDataHashID *id2offset;
    void UpdateOffsetMap(unsigned int defaultSize = 0);
 
protected:
    enum _stringmode
    {
        STRING_DEFAULT = 0x00,
        STRING_UNICODE = 0x01,
        STRING_ANSI = 0x02,
    } stringmode;
 
    mutable CXCriticalSection threadlock;
    CustomPrivateData *data;
    unsigned int cursize, totalsize;
 
    void ConvertPreviousData(CCustomData& data, CustomPrivateDataOld* olddata, unsigned int totalsize) const;
#ifndef MOOTOOLS_NO_ARCHIVE_SUPPORT
    void ReadPreviousVersion(CXArchive& archive);
#endif // !MOOTOOLS_NO_ARCHIVE_SUPPORT
 
 
    bool ReplaceCustom(unsigned int id, const void *ptr, unsigned int size, unsigned int kindof);
    void SetCustom(unsigned int id, const void *ptr, unsigned int size, unsigned int kindof);
    unsigned int GetCustom(unsigned int id, void *ptr, unsigned int size, unsigned int kindof) const;
 
    void SetStrings(unsigned int id, const void *strings, bool array);
    int GetStrings(unsigned int id, void *strings, bool array) const;
 
public:
    unsigned int CopyID(const CCustomData *, unsigned int firstid, ...);
    void Copy(const CCustomData *, unsigned int copyFlags);
    CCustomData *Copy() const;
    CCustomData& operator=(const CCustomData& refdata);
    bool IsEqual(const CCustomData& data) const;
 
    // id can be any value (0 is allowed)
    void SetBinary(unsigned int id, const void *ptr, unsigned int size);
    void SetCustomData(unsigned int id, const CCustomData& data);
    void SetCustomClass(unsigned int id, const CCustomDataClass& value);
    void SetFloat(unsigned int id, float value);
    void SetDouble(unsigned int id, double value);
    void SetChar(unsigned int id, char value);
    void SetUChar(unsigned int id, unsigned char value);
    void SetBool(unsigned int id, BOOL value);
    void SetPtr(unsigned int id, const void *ptr);
    void SetInt(unsigned int id, int value);
    void SetUInt(unsigned int id, unsigned int value);
    void SetLong(unsigned int id, long value); // warning: long is stored using 4 bytes whatever the OS size of long
    void SetULong(unsigned int id, unsigned long value);  // warning: long is stored using 4 bytes whatever the OS size of long
    void SetSizet(unsigned int id, SIZET value);
    void SetLongInt(unsigned int id, longint value);
    void SetULongInt(unsigned int id, longuint value);
    bool SetArray(unsigned int id, const void *ptr, unsigned int elementCount, unsigned int sizeOfElement);
    void SetString(unsigned int id, const CXString& string);
    void SetStringA(unsigned int id, const CXStringA& string);
    void SetStringW(unsigned int id, const CXStringW& string);
#ifdef MOOTOOLS_MFC_PRODUCT_BUILD
    void SetStringList(unsigned int id, const CStringList& strings);
#endif
    void SetStringArray(unsigned int id, const CXStringArray& strings);
    void SetUTCTime(unsigned int id, const CXTime& time); // CXTime is converted to UTC time
    void SetXTime(unsigned int id, const CXTime& time); // store CXTime value (without conversion and with full time precision)
 
    void AddToCustomData(unsigned int id, const CCustomData& newdata, BOOL copyNewIDOnly);
 
    bool HasData() const;
    bool HasData(unsigned int id) const;
    unsigned int GetDataKindOf(unsigned int id) const;
    bool ChangeID(unsigned int srcid, unsigned int newid);
    
    // Allocate/Free a block of memory that can be used with Attach methods
    static void *Alloc(unsigned int size); // Allocate memory for CCustomData. Alloc uses xmalloc.
    static void Free(void *data); // Free CCustomData memory. Free uses xfree
    void FreeExtra();
 
    void *Detach(unsigned int& size);
    void Attach(void *data, unsigned int size); // Attach a memory block (must have been allocated with Alloc (or xmalloc)
    const void *GetData(unsigned int& totalsize) const;
    void SetData(const void *data, unsigned int totalsize);
 
    unsigned int GetDataSize(unsigned int id) const;
    const void *GetCustomPtr(unsigned int id, unsigned int& size) const; // Return directly the data associated to the ID. GetCustomPtr requires to lock the custom data to prevent change of the data in an external thread.
    unsigned int GetChecksum(unsigned int id) const;
 
    bool GetBinary(unsigned int id, void *ptr, unsigned int size) const;
    bool GetCustomData(unsigned int id, CCustomData& data) const;
    bool GetCustomClass(unsigned int id, CCustomDataClass& data) const;
    bool GetFloat(unsigned int id, float& value, float defaultvalue) const;
    bool GetDouble(unsigned int id, double& value, double defaultvalue) const;
    bool GetBool(unsigned int id, bool& value, bool defaultvalue) const;
    bool GetBool(unsigned int id, BOOL& value, BOOL defaultvalue) const;
    bool GetChar(unsigned int id, char& value, char defaultvalue) const;
    bool GetUChar(unsigned int id, unsigned char& value, unsigned char defaultvalue) const;
    bool GetPtr(unsigned int id, void *&value) const;
    void *GetPtr(unsigned int id) const;
    bool GetInt(unsigned int id, int& value, int defaultvalue) const;
    bool GetUInt(unsigned int id, unsigned int& value, unsigned int defaultvalue) const;
    bool GetLong(unsigned int id, long& value, long defaultvalue) const; // warning: long is stored using 4 bytes whatever the OS size of long
    bool GetLongInt(unsigned int id, longint& value, longint defaultvalue) const;
    bool GetSizet(unsigned int id, SIZET& value, SIZET defaultvalue) const; // 32 / 64 bits independent. SIZET is stored as a unsigned long long. return defaultvalue if too big on 32 bits system
    bool GetULong(unsigned int id, unsigned long& value, unsigned long defaultvalue) const; // warning: long is stored using 4 bytes whatever the OS size of long
    bool GetULongInt(unsigned int id, longuint& value, longuint defaultvalue) const;
    const void *GetArray(unsigned int id, unsigned int& elementCount, unsigned int sizeOfElement, CXSingleLock *safeThreadGuard) const; // Release array must be called if the return data is not null (can be also called when null)
    bool GetString(unsigned int id, CXString& string, const CXString& = CXString()) const;
    bool GetStringA(unsigned int id, CXStringA& string, const CXStringA& = CXStringA()) const;
    bool GetStringW(unsigned int id, CXStringW& string, const CXStringW& = CXStringW()) const;
#ifdef MOOTOOLS_MFC_PRODUCT_BUILD
    int GetStringList(unsigned int id, CStringList &strings) const;
#endif
    int GetStringArray(unsigned int id, CXStringArray& strings) const;
    bool GetUTCTime(unsigned int id, CXTime& time, const CXTime& = CXTime::GetCurrentTime().GetTime()) const; // The time is initialized from UTC time (_time_t) which is cross platform. Comparison with CXTime possible if CXTime also initialized with UTC time
    bool GetXTime(unsigned int id, CXTime& time, const CXTime & = CXTime::GetCurrentTime().GetTime()) const; // The time is initialized from xTime which allows comparison if CXTime object is initialized standardly with full time precision
 
    void RemoveAll();
    bool RemoveCustom(unsigned int id);
 
    unsigned int GetIDCount() const;
    unsigned int GetIDByIndex(unsigned int index, unsigned int& kindof) const;
 
    CXString DumpCustomData(bool tabify, int level = 0) const;
 
#ifndef MOOTOOLS_NO_ARCHIVE_SUPPORT
    virtual void Serialize(CXArchive& archive);
    virtual bool SerializeFromData( const void *rawdata, fileuint size);
    virtual void *SerializeToData(fileuint& size) const; // Use CCustomData::Free to free the returned memory
    static bool SerializeFromData(CCustomData& data, const void *rawdata, fileuint size);
#else // !MOOTOOLS_NO_ARCHIVE_SUPPORT
    static bool SerializeFromData(CCustomData& data, const void *rawdata, fileuint size);
#endif
 
    // the following are not supported (return false) if CCUSTOMDATA_NO_PREFS_SUPPORT is defined
    bool SaveToPrefs(const CXString& filename, unsigned int paramName1, unsigned int paramName2) const;
    bool LoadFromPrefs(const CXString filename, unsigned int paramName1, unsigned int paramName2, bool copyPreviousVersion = false);
 
#ifdef _DEBUG
    void Dump();
#endif
 
    CCustomData();
    CCustomData(const CCustomData& data);
    virtual ~CCustomData();
};
 
END_MOOTOOLS_NAMESPACE
 
#endif // !defined(AFX_CUSTOMDATA_H__5D9D5366_1E68_11D3_A381_EA02A046C52E__INCLUDED_)