/*!
  @header ECNSLogLoggingWriter
  @abstract Module of Encore
 
  @availability OS X, GNUstep
  @copyright 2004, 2005, 2006 Oliver Langer

  Author: Oliver Langer

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA

  <pre>
  -------------------------------------------------------------------------
  Modification history

  03.02.06 ola     initial version
  22.08.06 ola     license changed
  -------------------------------------------------------------------------
  </pre>
*/

#if !defined(__ECFileLoggingWriter_H)
#define __ECFileLoggingWriter_H

#include <Foundation/Foundation.h>
#include <Encore/ECObject.h>
#include <Encore/ECLoggingWriter.h>

/*!
 * @define ECFileLoggingWriter_DEFAULT_MAXFILESIZE
 * @discussion defines the default maximum file size
 */
#define ECFileLoggingWriter_DEFAULT_MAXFILESIZE 4096 * 1024


/*!
 * @define ECFileLoggingWriter_DEFAULT_BACKUSUFFIX
 * @discussion The default filename suffix used to create a backup of
 *   the logging file when rotating. Refer to NSDate for further information
 *   regarding the format
 */
#define ECFileLoggingWriter_DEFAULT_BACKUSUFFIX @"%Y%m%d%H%M%S"


/*!
 * @class ECFileLoggingWriter
 * @abstract Writes logging entries into a file. Supports logging roation.
 * @discussion The implementation allows the configuration of 
 * <ul>
 *   <li>filename</li>
 *   <li>scheme for the suffix used to copy the current logging file due
 *     to rotation. The scheme allows the usage of date formatting 
 *     entries. Refer to NSDate for describtion of the specifiers</li>
 *   <li>limitation of the size of a logging file</li>
 */
@interface ECFileLoggingWriter : ECObject <ECLoggingWriter> {
  @private
    NSString *logBaseFilename;
    NSString *logBackupFilenameSuffix;
    unsigned long long maxFilesize;
    NSLock *lock;
    NSStringEncoding encoding;

    NSFileHandle *fileHandle;
}


- init;
- (void) dealloc;


/*!
 * @method checkFilestatus
 * @abstract Internal method used to open/create files or to look for
 *   log rotation
 * @result self
 */
- checkFilestatus;


/*!
 * @method closeAndMoveFile
 * @abstract Internal method used to close and move the current logging file
 * @result self
 */
- closeAndMoveFile;


/*!
 * @method createBackupFilename
 * @abstract Internal method used create a non-existing backup file name
 * @result non-existing backup file name
 */
- (NSString *) createBackupFilename;


/*!
 * @method openFile
 * @abstract Internal method used to open or create and open a file if necessary
 * @result self
 */
- openFile;


/*!
 * @method setEncoding
 * @abstract Specifies the encoding for the logging file.
 *   By default the encoding NSASCIIStringEncoding is being used.
 *   Refer to the documentation of NSString for further information about
 *   encodings
 * @result self
 */
- setEncoding: (NSStringEncoding) anEncoding;


/*!
 * @method setBaseFilename
 * @abstract speficies the fully qualified name for the logging file
 * @param aBaseFilename fully qualified name for the logging file
 * @result self
 */
- setBaseFilename: (NSString *) aBaseFilename;


/*!
 * @method setLogBackzpFilename
 * @abstract Specifies the suffix which is used when renaming the
 *   logging file due to rotation. 
 *   By default "%Y%m%d%H%M%S" ECFileLoggingWriter_DEFAULT_BACKUSUFFIX is used.
 * @param aBackupFilename may contain date formatting specifiers. Internally
 *   this string is passed to [NSDate descriptionWithCalendarFormat::]
 * @result self
 */
- setBackupFilenameSuffix: (NSString *) aBackupFilename;


/*!
 * @method setMaxFilesize
 * @abstract Specifies the maximum number of bytes per logging file
 * @discussion By default a maximum size of 
 *   4KB (ECFileLoggingWriter_DEFAULT_MAXFILESIZE) is assumed.
 * @param nrBytes the file writer will create the next file after have been
 *   written more then nrBytes.
 * @result self
 */
- setMaxFilesize: (unsigned int) nrBytes;


/*!
 * @method writeLog
 * @abstract called in order to write the given string somewhere on mother earth
 * @result self
 */
- writeLog: (NSString *) logEntry;

@end
#endif