/*******************************************************************************
 *
 * Copyright (c) 2000, Tortuga Technologies Pty Ltd. All rights reserved.
 * 
 * This is unpublished proprietary source code of Tortuga Technologies.
 * The copyright notice above does not evidence any actual or intended
 * publication of such source code.
 * 
 *******************************************************************************
 * 
 * Filename:    $Id: log.h,v 1.1 2002/04/22 10:10:10 jill Exp $
 * 
 * Description: Provides an interface for a general logging mechanism
 * 
 * History
 * -------
 * $Log: log.h,v $
 * Revision 1.1  2002/04/22 10:10:10  jill
 * Initial import
 *
 * Revision 1.1.1.1  2000/02/18 06:41:35  graham
 * initial import
 *
 ******************************************************************************/

#ifndef _LOG_H
#define _LOG_H


/* system includes */

#include <stdarg.h>


/* definitions of logging level */

#define  LOG           0
#define  INFO          1
#define  FULL          2


/* destinations we can log too */

#define  STDOUT        0
#define  SYSLOG        1
#define  STDERR        2
#define  FLOCAL        3


/* number of log descriptors */

#define  LOG_MODS     21


/* definitions of logging facility */

#define  LOCAL0        0
#define  LOCAL1        1
#define  LOCAL2        2
#define  LOCAL3        3
#define  LOCAL4        4
#define  LOCAL5        5
#define  LOCAL6        6
#define  LOCAL7        7

#define  NO_FACILITY  -1


#ifdef __cplusplus
extern "C" {
#endif


/******************************************************************************/
/*                                                                            */
/* Unit:        log()                                                         */
/*                                                                            */
/* Description: routine to log a message giving the module id and log level   */
/*                                                                            */
/* Parameters:  llid    - id of module logging the message                    */
/*              level   - priority level of the message                       */
/*              format  - message format                                      */
/*              ...     - various parameters                                  */
/*                                                                            */
/* Returns:     None                                                          */
/*                                                                            */
/******************************************************************************/
void log( int lid, int level, char *format, ... );


/******************************************************************************/
/*                                                                            */
/* Unit:        log_module()                                                  */
/*                                                                            */
/* Description: attaches a description to a module id                         */
/*                                                                            */
/* Parameters:  llid    - id of module logging the message                    */
/*              desc    - descriptive module name                             */
/*                                                                            */
/* Returns:     None                                                          */
/*                                                                            */
/******************************************************************************/
void log_module( int lid, char *desc );


/******************************************************************************/
/*                                                                            */
/* Unit:        log_remove()                                                  */
/*                                                                            */
/* Description: removes a description given a module id                       */
/*                                                                            */
/* Parameters:  llid    - id of module logging the message                    */
/*                                                                            */
/* Returns:     None                                                          */
/*                                                                            */
/******************************************************************************/
void log_remove( int llid );


/******************************************************************************/
/*                                                                            */
/* Unit:        log_initialise()                                              */
/*                                                                            */
/* Description: initialises the program doing the logging, the level to log   */
/*              at and the destination of the messages                        */
/*                                                                            */
/* Parameters:  ident   - id of program                                       */
/*              level   - level to log messages at                            */
/*              facil   - facility to log syslog messages to                  */
/*              destn   - destination of log messages                         */
/*                                                                            */
/* Returns:     None                                                          */
/*                                                                            */
/******************************************************************************/
void log_initialise( char *ident, int level, int facil, int destn );


/******************************************************************************/
/*                                                                            */
/* Unit:        log_level_change()                                            */
/*                                                                            */
/* Description: ups the level of the logging                                  */
/*                                                                            */
/* Parameters:  dummy  -  here so this routine can be used with sigaction()   */
/*                                                                            */
/* Returns:     None                                                          */
/*                                                                            */
/******************************************************************************/
void log_level_change( int dummy );


/******************************************************************************/
/*                                                                            */
/* Unit:        log_facility_change()                                         */
/*                                                                            */
/* Description: changes the syslog facility and level                         */
/*                                                                            */
/* Parameters:  new_level     -  new level to log at                          */
/*              new_facility  -  new facility to log at                       */
/*                                                                            */
/* Returns:     None                                                          */
/*                                                                            */
/******************************************************************************/
void log_facility_change( int new_level, int new_facility );


/******************************************************************************/
/*                                                                            */
/* Unit:        log_print_facility()                                          */
/*                                                                            */
/* Description: returns an ascii description of the current log facility      */
/*                                                                            */
/* Parameters:  None                                                          */
/*                                                                            */
/* Returns:     address of print buffer                                       */
/*                                                                            */
/******************************************************************************/
char *log_print_facility( void );


/******************************************************************************/
/*                                                                            */
/* Unit:        log_print_level()                                             */
/*                                                                            */
/* Description: returns an ascii description of the current log level         */
/*                                                                            */
/* Parameters:  None                                                          */
/*                                                                            */
/* Returns:     address of print buffer                                       */
/*                                                                            */
/******************************************************************************/
char *log_print_level( void );


/******************************************************************************/
/*                                                                            */
/* Unit:        log_print_destination()                                       */
/*                                                                            */
/* Description: returns the address of the current log destn (ascii represtn) */
/*                                                                            */
/* Parameters:  None                                                          */
/*                                                                            */
/* Returns:     address of ascii description                                  */
/*                                                                            */
/******************************************************************************/
char *log_print_destination( void );


/******************************************************************************/
/*                                                                            */
/* Unit:        log_print_filename()                                          */
/*                                                                            */
/* Description: returns the current log filename                              */
/*                                                                            */
/* Parameters:  None                                                          */
/*                                                                            */
/* Returns:     address of ascii description or null                          */
/*                                                                            */
/******************************************************************************/
char *log_print_filename( void );


/******************************************************************************/
/*                                                                            */
/* Unit:        log_destroy()                                                 */
/*                                                                            */
/* Description: free's up all allocated memory and stops further logging      */
/*                                                                            */
/* Parameters:  None                                                          */
/*                                                                            */
/* Returns:     None                                                          */
/*                                                                            */
/******************************************************************************/
void log_destroy( void );


/*******************************************************************************
 * 
 * Unit:        log_dump()
 * 
 * Description: dump logging information to current log
 * 
 * Parameters:  none
 * 
 * Globals:     none
 * 
 * Returns:     none
 * 
 ******************************************************************************/
void log_dump( void );


/*******************************************************************************
 * 
 * Unit:        log_next_id()
 * 
 * Description: allocates an available module id and initialises it
 * 
 * Parameters:  desc  --  description of module
 *              lid   --  address of int in which to store allocated id
 *
 * Globals:     none
 * 
 * Returns:     none
 * 
 ******************************************************************************/
void log_next_id( char *desc, int *lid );


#ifdef __cplusplus
}
#endif


#endif /* _LOG_H */