directory.c

   File         : directory.c
   Description  : Obtains all files contained in a directory
   Category     : Utility
   Author       : Charles Yates
  
   This is one of the really annoying quirks of NT and UNIX compatability;
   no standard API exists on both platforms to return the file names
   contained in a directory - hence this API has been constructed.
  
   Stranger still is that the UNIX API (diropen etc) does not allow wild
   card input, while the NT API (FindFirstFile etc) does - one of the few 
   times where NT does something better than UNIX... only it lets itself 
   down by not behaving in the standard open, read, close manner (the 
   'open' also returns the first file, which is quite frankly a 
   nuisance...). 
  
   UNIX further screws up by sorting the files by i-node (I think), rather 
   than file name (which of course would be more useful). 
  
   Both implementations read all the files in to an array during the Init, 
   sorts them by their name and returns each one through subsequent calls to 
   get.
  
   Anyway, all of these problems are resolved in this solution and it 
   works in the same way as all the other APIs in this project. There's 
   an Init which returns a pointer to an initialised DIR_STRUCT, a Get 
   which obtains each of the file names and a close which closes the 
   structure, ie:
  
    DIR_STRUCT Dir;
    char *Name;
    Dir = DIR_Init( "/path/*.dat" );
    while ( ( Name = DIR_Get( Dir ) ) != NULL )
        printf( "%s\n", Name );
    DIR_Close( Dir );
  
   Care should be taken with hard coded paths (the WIN32 and UNIX macros
   can be used in #ifdef code). 

   DIR_STRUCT DLLEXP DIR_Init( char *dirSpec )
 
   Function     : DIR_Init
   Description  : Opens a directory for reading
   PRECONDITIONS: None
   INPUT        : char *DirSpec - Directory specifcation
                    Values:
                      Accepts either / or  separators
                      Wildcards can only be specified at end of string
                      Default wildcards are to obtain all files
   OUTPUT       : void
   RETURNS      : DIR_STRUCT *Dir - Directory structure
   SPECIAL LOGIC: Loads... see usage at top of source code.

   void DIR_SetIgnoreHidden( DIR_STRUCT dir )
 
   Function     : DIR_SetIgnoreHidden
   Description  : Ignores all hidden files and directories
   Preconditions: Directory must be opened using DIR_Init and no Get has been
                  requested.
   INPUT        : DIR_STRUCT dir - Open Directory structure
   OUTPUT       : dir is informed to ignore hidden files and directories
   RETURNS      : void

   void DLLEXP DIR_SetRecursion( DIR_STRUCT dir, int level )
 
   Function     : DIR_SetRecursion
   Description  : Sets the number of levels of recursion
   Preconditions: Directory must be opened using DIR_Init
   Input        : DIR_STRUCT dir - Open Directory structure
                  int level - number of levels of recursion
   Output       : void
   Returns      : char * - Address of file name or NULL
   Special Logic: None.

   char * DLLEXP DIR_Get( DIR_STRUCT dir, int index )
 
   Function     : DIR_Get
   Description  : Reads the next contents of the directory
   Preconditions: Directory must be opened using DIR_Init
   Input        : DIR_STRUCT *Dir - Open Directory structure
   Output       : void
   Returns      : char * - Address of file name or NULL
   Special Logic: None.

   int DLLEXP DIR_EntryIsDirectory( DIR_STRUCT dir, int index )
 
   Function     : DIR_EntryIsDirectory
   Description  : Indicates if the entry at the index is a directory or not
   Preconditions: Directory must be opened using DIR_Init
   Input        : DIR_STRUCT *Dir - Open Directory structure
                  int index - index to enquire upon
   Output       : void
   Returns      : int - 0 if not a directory, 1 otherwise
   Special Logic: None.

   char * DLLEXP DIR_GetRelative( DIR_STRUCT dir, int index )
 
   Function     : DIR_GetRelative
   Description  : Reads the next contents of the directory and returns the file
                  relative to the orginal path given.
   Preconditions: Directory must be opened using DIR_Init
   Input        : DIR_STRUCT *Dir - Open Directory structure
   Output       : void
   Returns      : char * - Address of file name or NULL
   Special Logic: None.

   int DLLEXP DIR_Count( DIR_STRUCT dir )
 
   Function     : DIR_Count
   Description  : Returns the number of items in the list.
   Preconditions: Directory must be opened using DIR_Init
   Input        : DIR_STRUCT *Dir - Open Directory structure
   Output       : void
   Returns      : int - the number of files in the directory
   Special Logic: None.

   void DLLEXP DIR_Close( DIR_STRUCT dir )
 
   Function     : DIR_Close
   Description  : Closes the directory
   Preconditions: Directory must be opened using DIR_Init
   Input        : DIR_STRUCT *Dir - Open Directory structure
   Output       : DIR_STRUCT *Dir - Directory structure closed
   Returns      : void
   Special Logic: None.

   static void DIR_Refresh( DIR_STRUCT dir )
 
   Function     : DIR_Refresh
   Description  : Refreshes the parts that other things cannot reach
   Preconditions: Directory must be opened using DIR_Init
   Input        : DIR_STRUCT *Dir - Open Directory structure
   Output       : void
   Returns      : void
   Special Logic: None.