mi32/filefind.h

Go to the documentation of this file.

/****
 * \file filefind.h <mi32/filefind.h>
 * \brief Class FILEFIND - Methods to locate files
 *
 * Path searching management class, replaces MioSearchList...() functions
 *
 * 1.  This class is not thread safe.  Most of the time the instance is specific to a 
 *    thread therefore the recouse sharing issues are not involved.  If this class is
 *    a shared resource, it is up to the user of the class to guard it using the 
 *    appropriate semaphore method.
 *
 * \if NODOC
 * $Id: filefind.h_v 1.45 2012/05/09 21:04:14 mju Exp $
 *
 * $Log: filefind.h_v $
 * Revision 1.45  2012/05/09 21:04:14  mju
 * Add some private methods, remove some long-obsolete ones.
 *
 * Revision 1.44  2010/03/23 15:26:35  mju
 * Rename createFile as createPath so not changed by windows macro.
 *
 * Revision 1.42  2008/07/24 21:15:21  mju
 * Add location_installation and add to locations_reference and locations_executable.
 *
 * Revision 1.41  2007/10/09 21:46:08  dwilliss
 * Added optional extension parameter to make temp file
 *
 * Revision 1.40  2007/05/10 12:44:13  mju
 * Fwd-declare filepath/list so don't need header.
 *
 * Revision 1.38  2007/01/24 23:44:03  dwilliss
 * Added static method to GetDefaultTempFolder
 *
 * Revision 1.36  2007/01/03 22:56:40  mju
 * Add locations_Temporary so can setup in ctor.
 * Add needWritable parm to addEnv/Path/String.
 *
 * Revision 1.34  2006/10/05 17:39:27  mju
 * Add registerMountDelegate.
 *
 * Revision 1.33  2006/10/05 14:59:37  mju
 * Add missingFilePromptDisable/Enable and missingfilepromptdisabler class.
 *
 * Revision 1.31  2006/10/05 12:57:14  mju
 * Add clearMissingFileList.
 *
 * Revision 1.30  2006/10/04 21:49:29  mju
 * Add locateRelatedPath and relatedorder enum.
 * Add v_prompt to filter.
 *
 * Revision 1.18  2003/05/22 21:28:18  mju
 * MakeSettings now requires one or more of listed locations to be specified.
 *
 * Revision 1.15  2003/05/19 16:51:06  mju
 * In LocateSettingsFile allow to specifed legacy locations separately.
 *
 * Revision 1.13  2003/05/16 17:50:29  mju
 * Add LOCATION_Settings and Locate/MakeSettingsFile methods.
 *
 * Revision 1.10  2003/04/10 14:06:27  mju
 * Search locale folders first if LOCATION_Locale specified.
 *
 * Revision 1.7  2003/02/21 20:53:06  mju
 * Add AddLocale method.
 * Expand and clarify documentation on search order.
 *
 * Revision 1.2  2002/01/09 13:48:35  mju
 * Add default parm for LocateReferenceFile.
 *
 * Revision 1.1  2001/12/06 17:43:44  scowan
 * Initial revision
 * \endif
****/
 
#ifndef  INC_MI32_FILEFIND_H
#define  INC_MI32_FILEFIND_H

#ifndef  INC_MI32_DELEGATE_H
   #include <mi32/delegate.h>
#endif

#ifdef MISYSTEMDLL
   #define CLASSLIBEXPORT MI_DLLCLASSEXPORT
#else
   #define CLASSLIBEXPORT MI_DLLCLASSIMPORT
#endif

#ifndef GENERATING_DOXYGEN_OUTPUT
class FILEPATH;
class FILEPATHLIST;
#endif


class CLASSLIBEXPORT FILEFIND {
   public:

      enum ADDPOSN {
         ADDPOSN_ToFront,
         ADDPOSN_ToBack
         };

      enum LOCATIONS {
         LOCATION_None =                        0x0000,
         LOCATION_Locale =                      0x0001,  
         LOCATION_Home =                        0x0002,  
         LOCATION_Current =                     0x0004,  
         LOCATION_Process =                     0x0008,  
         LOCATION_PATH =                        0x0010,  
         LOCATION_Installation =                0x0020,  
         LOCATION_Settings_CurInst_CurUser =    0x0100,  
         LOCATION_Settings_CurInst_AllUsers =   0x0200,  
         LOCATION_Settings_AllInst_CurUser =    0x0400,  
         LOCATION_Settings_AllInst_AllUsers =   0x0800,  
         LOCATIONS_Executable =  (LOCATION_Installation | LOCATION_Process | LOCATION_Current | LOCATION_PATH),   
         LOCATIONS_Reference =   (LOCATION_Installation | LOCATION_Process | LOCATION_Current), 
         LOCATIONS_Temporary =                  0x1000,  
         #ifndef GENERATING_DOXYGEN_OUTPUT
         #ifdef MISYSTEMDLL
         LOCATIONS_Settings_Mask =              0x0F00,
         #endif
         #endif // GENERATING_DOXYGEN_OUTPUT
         };

      enum RELATEDORDER {
         #ifndef GENERATING_DOXYGEN_OUTPUT
         SUBORDER_Original =  0x01,
         SUBORDER_Media =     0x02,
         SUBORDER_Source =    0x03,
         SUBORDER_Tree =      0x04,
         SUBORDER_Mask =      0x0F,
         #endif
         RELATEDORDER_SourceOriginalMediaTree = ((SUBORDER_Source) | (SUBORDER_Original << 4) | (SUBORDER_Media << 8) | (SUBORDER_Tree << 12)),
         RELATEDORDER_OriginalSourceMediaTree = ((SUBORDER_Original) | (SUBORDER_Source << 4) | (SUBORDER_Media << 8) | (SUBORDER_Tree << 12)),
         RELATEDORDER_SourceMediaOriginalTree = ((SUBORDER_Source) | (SUBORDER_Media << 4) | (SUBORDER_Original << 8) | (SUBORDER_Tree << 12)),
         RELATEDORDER_MediaSourceOriginalTree = ((SUBORDER_Media) | (SUBORDER_Source << 4) | (SUBORDER_Original << 8) | (SUBORDER_Tree << 12)),
         RELATEDORDER_MediaTreeSourceOriginal = ((SUBORDER_Media) | (SUBORDER_Tree << 4) | (SUBORDER_Source << 8) | (SUBORDER_Original << 12)),
         RELATEDORDER_NoPrompt = 0x80000000  
         };
         
      class CLASSLIBEXPORT FILTER {
         public:

            virtual bool v_Filter (
               const FILEPATH& path
               ) = 0;

            virtual bool v_Prompt (
               FILEPATH& path,                     
               const MISTRING *pPromptStr          
               );
         };

      class MISSINGFILEPROMPTDISABLER {
         public:
            MISSINGFILEPROMPTDISABLER (
               ) { FILEFIND::MissingFilePromptDisable(); }
            ~MISSINGFILEPROMPTDISABLER (
               ) { FILEFIND::MissingFilePromptEnable(); }

         private:
            #ifndef GENERATING_DOXYGEN_OUTPUT
            MISSINGFILEPROMPTDISABLER (const MISSINGFILEPROMPTDISABLER&);
            MISSINGFILEPROMPTDISABLER& operator= (const MISSINGFILEPROMPTDISABLER&);
            #endif // GENERATING_DOXYGEN_OUTPUT
         };

      typedef FastDelegate<bool(FILEPATH&, FILEFIND::FILTER*, const MISTRING*)> DELEGATE_PROMPT;

      typedef FastDelegate<void(FILEPATH&)> DELEGATE_MOUNT;

      static void ClearMissingFileList ();

      static ERRVALUE GetDefaultTempFolder (
         FILEPATH& Folder,
         bool bCreateIfMissing
         );

      static bool LocateExecutableFile (
         const char* ExecutableFileName,           
         FILEPATH& ExecutableFilePath              
         );

      static bool LocateReferenceFile (
         const char* ReferenceFileName,            
         FILEPATH& ReferenceFilePath,              
         LOCATIONS locations = LOCATION_None       
         );

      static bool LocateReferenceFile (
         const MISTRING& ReferenceFileName,        
         FILEPATH& ReferenceFilePath,              
         LOCATIONS locations = LOCATION_None       
         );

      static bool LocateRelatedFile (
         const FILEPATH& SourcePath,               
         FILEPATH& RelatedPath,                    
         RELATEDORDER order,                       
         FILTER *pFilter = 0                       
         );

      static bool LocateSettingsFile (
         const char* SettingsFileName,             
         FILEPATH& SettingsFilePath,               
         LOCATIONS PreferredLocation,              
         LOCATIONS LegacyLocations = LOCATION_None 
         );
         
      static ERRVALUE LocateTrueTypeFontFiles (
         FILEPATHLIST& TrueTypeFiles               
         );

      static ERRVALUE MakeSettingsFilePath (
         const char* SettingsFileName,             
         FILEPATH& SettingsFilePath,               
         LOCATIONS locations                       
         );

      static ERRVALUE MakeTempFile (
         FILEPATH& TempFilePath,                   
         INT64 MinSize,                            
         bool LargestPath,                         
         const MISTRING& basename,                 
         const char *extn = "tmp"                  
         );

      static ERRVALUE MakeTempFile (
         FILEPATH& TempFilePath,                   
         INT64 MinSize,                            
         bool LargestPath                          
         );

      static void MissingFilePromptDisable ();

      static void MissingFilePromptEnable ();

      static void RegisterMountDelegate (
         DELEGATE_MOUNT delegate                
         );

      static void RegisterPromptDelegate (
         DELEGATE_PROMPT delegate                  
         );

      explicit FILEFIND (
         LOCATIONS locations = LOCATION_None       
         );

      FILEFIND (
         const FILEFIND& rhs
         );

      ~FILEFIND (
         );

      FILEFIND& operator= (
         const FILEFIND& rhs
         );
         
      void AddEnvVar (
         const char* EnvTag,
         ADDPOSN AddPosn = ADDPOSN_ToBack,
         bool NeedWritable = false
         );

      void AddLocale (
         bool IncludeDefault = true,            
         ADDPOSN AddPosn = ADDPOSN_ToBack
         );

      void AddPath (
         const FILEPATH& path,
         ADDPOSN AddPosn = ADDPOSN_ToBack,
         bool NeedWritable = false
         );

      void AddString (
         const MISTRING& mpath,
         ADDPOSN AddPosn = ADDPOSN_ToBack,
         bool NeedWritable = false,
         MIUNICODE Separator = 0xFFFF
         );

      bool CreatePath (                   
         const MISTRING& name,
         FILEPATH& path                         
         ) const;

      bool CreatePath (                   
         const char* name,
         FILEPATH& path                         
         ) const;

      const FILEPATHLIST& GetPathList (
         ) const { return (*m_pPathList); }
         
      bool IsEmpty (
         ) const;

      bool LocateFile (                   
         const char* name,                      
         FILEPATH& path                         
         ) const;

      bool LocateFile (
         const MISTRING& relfile,               
         FILEPATH& path                         
         ) const;

      bool LocateFiles (
         const MISTRING& pattern,
         FILEPATHLIST& PathList                 
         ) const;

      bool LocatePath (
         FILTER& filter,
         FILEPATH& path                      
         ) const;

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      FILEPATHLIST *m_pPathList;          // The list of FILEPATH's to search
      static const MIUNICODE s_SepMark;
      static FILEPATH& GetLocaleDir();
      static DELEGATE_MOUNT s_DelegateMount;
      static DELEGATE_PROMPT s_DelegatePrompt;
      static UINT32 s_PromptDisabledCount;

      void AddTempEnvVar (const char *EnvTag);

      bool CreatePathLow (
         const MISTRING& name,
         FILEPATH& path,
         MISTRING& errdetails
         ) const;

      bool CreatePathLow (
         const char *name,
         FILEPATH& path,
         MISTRING& errdetails
         ) const;

      void MoveOldTemp (
         const FILEPATH& FolderPathNew,
         const FILEPATH& FolderPathOld,
         const char *name
         );

      friend class FILEFIND::FILTER;

      #endif // GENERATING_DOXYGEN_OUTPUT
      
   };

#ifndef GENERATING_DOXYGEN_OUTPUT
DEFINE_ENUM_OP_BITWISE(FILEFIND::LOCATIONS);
DEFINE_ENUM_OP_BITWISE(FILEFIND::RELATEDORDER);
#endif

#undef   CLASSLIBEXPORT
#endif   // INC_MI32_FILEFIND_H

---