ApplicationTools.h

Go to the documentation of this file.

//! @file ApplicationTools.h
//! @brief A set of function to initialize the SDK, and define the running context.
//! 
///////////////////////////////////////////////////////////////////////////////////
 
#ifndef APPLICATION_TOOLS_H
#define APPLICATION_TOOLS_H
 
BEGIN_MOOTOOLS_NAMESPACE
 
#ifdef __cplusplus
    typedef enum _MOOTOOLS_APPLICATION_FLAGS
    {
        MOOTOOLS_APPLICATION_NONE = 0x00,
        MOOTOOLS_APPLICATION_REGISTER_FILES = 0x01, //!< Register built in file format so there extension will be recognized and parsed
        MOOTOOLS_APPLICATION_CATCH_EXCEPTION = 0x02, //!< Release mode only. Set Mootools signal handler
        MOOTOOLS_APPLICATION_ERROR_HANDLERS = 0x04, //!< windows only: _set_invalid_parameter_handler
        MOOTOOLS_APPLICATION_DISABLE_LEAKS_CHECK = 0x08, //!< Debug only: disables memory leaks checks. Checking memory leaks slow down the application. This settings has no effect in release mode has memory leaks are never checked.
        MOOTOOLS_APPLICATION_CLEAN_MEMORY = 0x010, //!< Clean memory from any preallocated structs and release any service launched (ie socket servive)
        MOOTOOLS_APPLICATION_REGISTER_PLUGINS = 0x020, //!< Load plugins if any. Plugin directory can be set using SetPluginsDirectory
        MOOTOOLS_APPLICATION_DEFAULT = -1,
    } MOOTOOLS_APPLICATION_FLAGS;
    
    DLL_TOOLSFUNCTION void InitMootoolsApplication(const char *licenseKey, LPCTSTR applicationPath = NULL, unsigned int flags = MOOTOOLS_APPLICATION_DEFAULT, LPCTSTR logFilePath = NULL); //!< By default applicationPath is the executable application path. Many internal features use applicationPath to load or save extra information (plugins, preferences...)
    DLL_TOOLSFUNCTION void CloseMootoolsApplication(unsigned int flags = MOOTOOLS_APPLICATION_DEFAULT);
    
#define EXITCALLBACK_CALL_LAST ((unsigned int)(-2)) //!< Maximum order to make the callback being call lastly
#define EXITCALLBACK_IN_PLUGIN ((unsigned int)(-1)) //!< Add application callback from an external plugin. This will be called before unloading plugins
    typedef void(*exitCallback)(void);
    DLL_TOOLSFUNCTION void RemoveApplicationExitCallback(exitCallback callback, unsigned int order = 0); //!< Add a callback for specific cleaning operation that occurs when CloseMootoolsApplication is call
    DLL_TOOLSFUNCTION void AddApplicationExitCallback(exitCallback callback, unsigned int order = 0); //!< Add a callback for specific cleaning operation that occurs when CloseMootoolsApplication is call. Large order are destroyed first. APPLICATION_PLUGIN_CALLBACK are destroyed before releasing plugins 
#endif
 
extern "C"
{
    // Useful to call it from C code
    // General cancel operations
    DLL_TOOLSFUNCTION void SetCancelThread(bool cancel, xThreadID threadID = 0);  //!< Any call to SetCancelThread(TRUE must have a pending call to SetCancelThread(FALSE when thread exit. SetCancelThread(FALSE can be called if you know that thread exit
    DLL_TOOLSFUNCTION bool ShouldCancelThread(xThreadID threadID = 0);
    DLL_TOOLSFUNCTION xThreadID GetApplicationMainThreadID();
 
    // General silent operations
    DLL_TOOLSFUNCTION void SetSilentThread(bool silent, xThreadID threadID = 0);  //!< Any call to SetSilentThread(TRUE must have a pending call to SetSilentThread(FALSE when thread exit.  SetSilentThread(FALSE can be called if you know that thread exit
    DLL_TOOLSFUNCTION bool IsSilentThread(xThreadID threadID = 0);
 
    // Allow to attach a thread to another one, which is useful when using some mechanism such OpenMP through a CXThread object
    DLL_TOOLSFUNCTION void AttachThread(xThreadID newThreadID, xThreadID parentThreadID); //!< newThreadID is attached to parentThreadID and get the silent and cancel status
    DLL_TOOLSFUNCTION void DetachThread(xThreadID threadID); //!< Any call to AttachThread must have a pending call to detach, but DetachThread can be call if you know that the thread exit
    DLL_TOOLSFUNCTION unsigned int GetChildThreads(xThreadID refparentThreadID, CXArray<xThreadID>& childTheads); //!< Retrieve threads attached to a given parent. Return the number of found threads.
 
    DLL_TOOLSFUNCTION void OMPSetMaxThreadCount(unsigned int maxThreadCount); //!< Set OMP max thread count
    DLL_TOOLSFUNCTION unsigned int OMPGetMaxThreadCount(); //!< Get OMP max thread count, which is set to 
    DLL_TOOLSFUNCTION unsigned int OMPGetScheduleChunkSize(unsigned int iterationCount); //!< Return an interesting OMP schedule value, depending on the number of iteration and maximum number of thread
}
 
#ifdef __cplusplus
    #define UNDEFINED_VERSION_NUMBER -1
 
    // The internal product name is the name used to created some directories ("3DBrowser") used by the software
    // This is not the front user name (ie "3DBrowser for 3D Users", "3DBrowser Light Edition") as these different products share the same preferences folders
    DLL_TOOLSFUNCTION void SetInternalProductName(const CXString& nameWithoutVersion, int version, bool resetPreferencesPath = false);
    DLL_TOOLSFUNCTION CXString GetInternalProductName(bool nameWithVersion = true);
    DLL_TOOLSFUNCTION void SetUserPreferencesPath(const CXString& path);
    DLL_TOOLSFUNCTION CXString GetUserPreferencesPath(bool create = true); //!< The returned path integrates the version
    DLL_TOOLSFUNCTION CXString GetCommonPreferencesPath(bool create = true);  //!< The returned path integrates the version
    DLL_TOOLSFUNCTION CXString GetPreferencesFile();
    DLL_TOOLSFUNCTION void SetApplicationPath(const CXString& path);
    DLL_TOOLSFUNCTION CXString GetApplicationPath(bool pathWithoutApplicationName); //!< Return the exe path and filename of the running application
    DLL_TOOLSFUNCTION CXString GetApplicationName(bool nameWithoutExtension);
    DLL_TOOLSFUNCTION CXString GetCommonApplicationDataPath(bool commonToAllVersion = false, LPCTSTR alternateName = NULL); //!< The SDK version returns GetUserPreferencesPath(), whatever commonToAllVersion value. Otherwise, the returned path integrates the version if commonToAllVersion = false, otherwise it returns a path that can be shared by all version of the application
    DLL_TOOLSFUNCTION CXString GetUserApplicationDataPath(bool commonToAllVersion = false, LPCTSTR alternateName = NULL); //!< The SDK version returns GetUserPreferencesPath(), whatever commonToAllVersion value. The returned path integrates the version if commonToAllVersion = false, otherwise it returns a path that can be shared by all version of the application
 
    DLL_TOOLSFUNCTION void EnablePreferencesSaving(bool enable); //!< Preferences saving is disabled by default
    DLL_TOOLSFUNCTION bool IsPreferencesSavingEnabled(); //!< Preferences saving is disabled by default
    DLL_TOOLSFUNCTION bool CopyFileFromPreviousVersionIfMissing(const CXString& targetPath); //!< Copy a file from a previous version if it is missing from the current version
 
    typedef enum LogFileMode
    {
        LOGFILE_REPLACE_EXISTING = 0,
        LOGFILE_ADD_TO_EXISTING,
        LOGFILE_PREVENT_REPLACE
    } LogFileMode;
 
    #define LOG_ENABLE_ALL ((unsigned int)(-1))
    #define LOG_IS_DISABLED ((unsigned int)(-2))
 
    //! @name Log functions
    //! @brief Convenient functions to log information to an output file.
    //! @details Cf. @ref LOGMACRO for convenient log macros
    //! @{
    DLL_TOOLSFUNCTION bool SetLogFile(const CXString& filename, LogFileMode mode, unsigned int filterLevel = LOG_ENABLE_ALL); //!< a filename for loggin some events. Log is written in the user application data path. The file is automatically closed
    DLL_TOOLSFUNCTION bool CloseLogFile();
    DLL_TOOLSFUNCTION unsigned int SetLogLevel(unsigned int level); //!< Set level to LOG_ENABLE_ALL to enable all log message or LOG_IS_DISABLED
    DLL_TOOLSFUNCTION bool IsLogFileEnabled(); //!< return true if log is enabled
    DLL_TOOLSFUNCTION unsigned int LogFileAddTab(bool addTab); //!< add/remove tabulation for LogFile
    DLL_TOOLSFUNCTION void LogLock(bool lock); //!< Allow lock until write several lines
    DLL_TOOLSFUNCTION void WriteToLogFile(const char *lpszFormat, ...);
    DLL_TOOLSFUNCTION void WriteToLogFile(const wchar_t *lpszFormat, ...);
 
    //! @}
    //! 
    //! @name Useful macro for log files
    //! @anchor LOGMACRO
    //! @brief Convenient macro for writing information in the log file.
    //! @{
    #define XLOG(a, ...) \
        { \
            if (IsLogFileEnabled()) \
                WriteToLogFile(a, __VA_ARGS__); \
        }
 
    #define XLOG_INC_TAB(a) \
        { \
            LogFileAddTab(a); \
        }
 
    #define XLOG_INC(a, ...) \
        { \
            WriteToLogFile(a, __VA_ARGS__); \
            LogFileAddTab(true); \
        }
 
    #define XLOG_DEC(a, ...) \
        { \
                LogFileAddTab(false); \
                WriteToLogFile(a, __VA_ARGS__); \
        }
 
    #define XLOG_IF(cond, ...) \
        { \
            if (cond) \
                XLOG(__VA_ARGS__); \
        }
 
    #define XLOG_LOCK(lock) \
        { \
            LogLock(lock); \
        }
 
    //! @}
 
    #if defined(MOOTOOLS_MFC_PRODUCT_BUILD) && !defined(MOOTOOLS_MINIMAL_BUILD)
    // Log events
    DLL_TOOLSFUNCTION void LogEvents();
    DLL_TOOLSFUNCTION void UnlogEvents();
 
    CXString GetVersionInformation(const CXString& version);
    #ifdef _DEBUG
    DLL_TOOLSFUNCTION void RemoveFirstLaunch();
    #endif
 
    DLL_TOOLSFUNCTION bool IsFirstLaunch(CWinApp *theApp, bool removeIfVersionLower, bool getFromPrefsFile, int *prevVersMajor = NULL, int *prevVersMinor = NULL);
    DLL_TOOLSFUNCTION void SetCommonPreferencesPath(const CXString& path);
    DLL_TOOLSFUNCTION void SetThreadLanguage(LANGID langid);
 
    #endif // !MOOTOOLS_MFC_PRODUCT_BUILD
#endif //#ifdef __cplusplus
 
    END_MOOTOOLS_NAMESPACE
 
#endif // APPLICATION_TOOLS_H