zFileAreaDir
============================================================================

	Summary  Searching for file(s) in a ProBoard file area.

	Remarks  This class is intended to search for physical presence of
	         files in a ProBoard file area. The thing about the class
	         is the full support for FA_<n>.CTL files for the multiple
	         directories per area specifications. This is automatically
	         handled by the class.


	ZFINDFILE::SETPATH
	------------------------------------------------------------------------

		Summary  Set the file location path(s).

		Syntax	 void SetPath(const char *path, int areano, Boolean cdrom);

		Remarks  You should pass the 'filepath' field from the area record
		         definition and the area number (1..last area) to this
		         routine. It is necessary to call it before you search
		         for a file in the particular area. You can call it as
		         many times as needed for any number of areas (meaning
		         that it is not necessary to create separate objects for
		         each area). This supports the FA_<n>.CTL files directly
		         and will parse them as necessary. No additional action
		         on your part is required. If 'cdrom' is set to True, some
		         additional special handling is performed. You should pass
		         the value of the ProBoard confguration here.

		Return   Nothing.

		Example  FILEAREA area;
		         int      areano = 10;

		         ReadFileArea(areano, &area);
		         SetPath(area.filepath, areano, area.copyLocal);


	ZFINDFILE::FIND
	-----------------------------------------------------------------------

		Summary  Look for the physical presence of a file in area.

		Syntax	 char* Find(const char *fileName);

		Remarks	 Look for the 'fileName' in all necessary directories as
		         per the file area specs. You need to call SetPath() before
		         you can use this routine. Note that 'fileName' should be
		         the name of the file only and may not contain any wildcards.
		         If the file is found, the full path will be returned by
		         this function. Since a pointer to an internal static
		         buffer is returned, callers must not assume that it will
		         stay unmodified. You need to copy the result.

		Return   Full path of file if found, or 0 if file not found.



zFileBbsLine
============================================================================

	Syntax  A complex class for parsing FILES.BBS style lines.

	Remarks	This class is used for parsing FILES.BBS style description
	        lines. The class will automatically determine the format of
	        the listing, whether the line contains a file name. Also,
	        it fully supports normal and extended formats, as well as
	        listings with or without file counters. Also, the extended
	        format can have the date and size reversed. Since this class
	        is intended for usage within the ProBoard environment, full
	        support is provided for the FA_<n>.CTL filepath specification
	        as well as the date format field in the configuration.

	Notes   The regular way of using this class is to create an instance
	        for each file area being processed. The constructor will set
	        up the date format from the area configuration. Then you will
	        need to call SetPath() to setup the file area location path.
	        Next, for each line in the description file, you would call
	        SetLine(). This routine will parse the line and will all
	        necessary fields of the object. It will also set up the internal
	        flags to indicate which fields are present in the line. You
	        would retrieve the flags with GetFlags() and test which of
	        the GetFile??? methods to use. You can also retrieve a formatted
	        line with GetLine(). Note that whenever a file line is parsed
	        (i.e. there is a file name on the line), the date and size
	        information will only be retrieved from the disk if it is not
	        already present in the file. Also, files that do not exist on
	        the disk are treated as description lines!


	ZFILEBBSLINE::ZFILEBBSLINE
	-----------------------------------------------------------------------

		Summary  Constructs the object and sets the date format.

		Syntax   zFileBbsLine(int date_format_t fmt = american,
		                      char lct = '[', char rct = ']');

		Remarks  The constructor is used to initialize the internal flags
		         and variables, as well as for setting the date format. The
		         date format 'fmt' can be any of the following:

		           enum date_format_t { american, european, japanese };

		         These will be used if the date is requested and needs to
		         be retrieved from the file on disk. If the date is already
		         present in the listing, this parameter will be ignored.
		         This depends on your locale. The default format is american.
		         The 'lct' and 'rct' parameters control what characters to
		         use for the left and right bracket for the download
		         counters, if any.


	ZFILEBBSLINE::SETPATH
	------------------------------------------------------------------------

		Summary  Set the file location path(s).

		Syntax	 void SetPath(const char *path, int areano, Boolean cdrom);

		Remarks  You should pass the 'filepath' field from the area record
		         definition and the area number (1..last area) to this
		         routine. This supports the FA_<n>.CTL files directly
		         and will parse them as necessary. No additional action
		         on your part is required. This is a direct interface to
		         the internal zFileFind object. Must be called for each
		         area before you begin processing. Special care must be
		         taken for CD-ROM areas. Set the 'cdrom' argument to True
		         if the area resides on a CD-ROM.

		Return   Nothing.

		Example  SetPath("C:\\PB\\FA_3.CTL", 3, False);


	ZFILEBBSLINE::SETLINE
	-----------------------------------------------------------------------

		Summary  Parse the line and set the internal variables.

		Syntax   void SetLine(const char *line);

		Remarks  This is the function you need to call for each line read
		         from the listing file. There are a couple of caveats that
		         you need to be aware of. If the line contains a file name
		         (i.e. the first character is not blank and the string
		         forms a valid filename which can be located in the file
		         path(s)), the line will be parsed for size, date, download
		         counter and description. If the date and size exist (in
		         any order after the name), they are stored, otherwise, they
		         will be retrieved from the disk. If the counter exists, it
		         will be stored, otherwise a "[00]" is initialized there.
		         Note that this means that if a file does not exist (or
		         cannot be found for any reason), it will be treated as
		         a description line. Depending on the parsing, the internal
		         flags will be set accordingly. Use the GetFlags() member
		         function to retrieve them. Note that this routine will
		         treat any line that begins with whitespace or a backspace
		         as a non-file line.

		Return   Nothing.

		See also zFileBbsLine::GetFlags, zFileBbsLine::GetLine


	ZFILEBBSLINE::GETLINE
	-----------------------------------------------------------------------

		Summary  Retrieves a formatted line.

		Syntax   char *GetLine();

		Remarks  This function creates a valid description line, in extended
		         format (i.e. size and date included). You can use this
		         routine if you don't want to re-create the line yourself.
		         The internal buffer will be overwritten with each call.

		Return   Line string.

		See also zFileBbsLine::SetLine, zFileBbsLine::GetFlags


	ZFILEBBSLINE::GETFILENAME
	-----------------------------------------------------------------------

		Summary  Retrieve the file name.

		Syntax   const char *GetFileName() const;

		Remarks  This routine returns the file name portion of the
		         description line or "" if none. You can check if such
		         a name has been successfully parsed by examining the
		         value returned by the GetFlags() function. The pointer
		         returned is to a local buffer that must not be modified.

		Return   Filename or empty string, if none.

		See also zFileBbsLine::GetFlags


	ZFILEBBSLINE::GETFILESIZE
	-----------------------------------------------------------------------

		Summary  Return a string with the file size.

		Syntax	 const char GetFileSize() const;

		Remarks  If a file name exists, this routine will return the file
		         size formatted as a string. The pointer is to a static
		         buffer that should not be modified. You should call and
		         examine the flags returned by GetFlags() to see if the
		         size is available.

		Return   File size string or "" if none.

		See also zFileBbsLine::GetFlags


	ZFILEBBSLINE::GETFILEDATE
	-----------------------------------------------------------------------

		Summary  Return formatted string with the file date.

		Syntax   const char *GetFileDate() const;

		Remarks  This routine returns the file date as parsed from the
		         line or retrieved from the disk. If the date was not in
		         the line, the formatting will follow the 'dateFormat'
		         requested in the constructor. You should examine the
		         value returned by GetFlags() to see of this is available.

		Return   Date string or empty ("") if not available.

		See also zFileBbsLine::GetFlags


	ZFILEBBSLINE::GETFILECOUNT
	-----------------------------------------------------------------------

		Summary  Return a string with the file download counter.

		Syntax   const char *GetFileCount() const;

		Remarks  This routine will return the string containing the file
		         download counters, if such is available in the listing
		         or "[00]" if not. Note that the brackets are preserved
		         in the string. Examine the value returned by GetFlags()
		         to determine if this field is available.

		Return   File download counter string.

		See also zFileBbsLine::GetFlags


	ZFILEBBSLINE::GETFILEDESC
	-----------------------------------------------------------------------

		Summary  Return the file description.

		Syntax   const char *GetFileDesc() const;

		Remarks  This routine returns the description for the file. Note
		         that this may return the whole line if the parsing routine
		         determines that the line does not contain a valid filename
		         for an existing file. If it is a file line, this will
		         return any description that follows the (optional) date,
		         size, and counters. This description will not be formatted
		         (i.e. the trailing newline will not be removed and leading
		         whitespace will be left there too).

		Return   File description string.

		See also zFileBbsLine::GetFlags


	ZFILEBBSLINE::GETFLAGS
	-----------------------------------------------------------------------

		Summary  Return flag setting to indicate the parsed line parts.

		Syntax	 int GetFlags() const;

		Remarks  This routine returns a bitmapped flag to indicate which
		         fields have been successfully parsed by the SetLine()
		         function. Those should be used to determine which fields
		         are safe for retrieval with the GetFile??? member function.
		         You can examine the returned value with the following
		         enumeration constants (members of the class too):

                 enum line_content_t
                 {  // flags for detected line parts
                     name       = 0x01, // file name is present
                     size       = 0x02, // file size is present
                     date       = 0x04, // file date is present
                     text       = 0x08, // file description is present
                     count      = 0x10, // file download counter is present
                     disk_date  = 0x20, // file date was retrieved from disk
                     disk_size  = 0x40, // file size was retrieved from disk
                     fake_count = 0x80  // fake download counter added
                 };

                 The distinction between the disk/fake date/size/counters
                 versions and the normal ones is that the normal flags will
                 be set if the fields exist in the file description line in
                 the listing. The others are used if the information was
                 retrieved from the disk (or faked).

		Return   Bitmapped flag value.

