/*
**  L2 - OSSP Logging Library
**  Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
**  Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/)
**
**  This file is part of OSSP L2, a flexible logging library which
**  can be found at http://www.ossp.com/pkg/l2/.
**
**  Permission to use, copy, modify, and distribute this software for
**  any purpose with or without fee is hereby granted, provided that
**  the above copyright notice and this permission notice appear in all
**  copies.
**
**  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
**  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
**  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
**  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
**  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
**  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
**  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
**  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
**  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
**  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
**  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
**  SUCH DAMAGE.
**
**  l2.h: C API
*/

#ifndef __L2_H__
#define __L2_H__

/* include standard environment we are based on */
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
#include <string.h>

/* counterbalance poor standard environments */ 
#ifndef NULL
#define NULL (void *)0
#endif
#ifndef FALSE
#define FALSE (0)
#endif
#ifndef TRUE
#define TRUE (!FALSE)
#endif

/* forward declarations for opaque data structures */
union  l2_context_un;
struct l2_param_st;
struct l2_stream_st;
struct l2_channel_st;
struct l2_handler_st;

/* corresponding data types for data structures */
typedef union  l2_context_un l2_context_t;
typedef struct l2_param_st   l2_param_t;
typedef struct l2_handler_st l2_handler_t;
typedef struct l2_stream_st  l2_stream_t;
typedef struct l2_channel_st l2_channel_t;

/* list of logging levels */
typedef enum {
    L2_LEVEL_DEBUG,
    L2_LEVEL_TRACE,
    L2_LEVEL_INFO,
    L2_LEVEL_NOTICE,
    L2_LEVEL_WARNING,
    L2_LEVEL_ERROR,
    L2_LEVEL_CRITICAL,
    L2_LEVEL_PANIC
} l2_level_t;

/* list of return values */
typedef enum {
    L2_OK,
    L2_ERROR
} l2_result_t;

/* context union for storing data */
union l2_context_un {
    char    c;
    short   s;
    int     i;
    long    l;
    float   f;
    double  d;
    char   *cp;
    void   *vp;
};

/* list of types for storing data */
typedef enum {
    L2_TYPE_CHAR,
    L2_TYPE_SHORT,
    L2_TYPE_INT,
    L2_TYPE_LONG,
    L2_TYPE_FLOAT,
    L2_TYPE_DOUBLE,
    L2_TYPE_CHARPTR,
    L2_TYPE_VOIDPTR
} l2_type_t;

/* parameter specification */
struct l2_param_st {
    char     *name;
    l2_type_t type;
    void     *store;
};

/* parameter constructors */
#define L2_PARAM_SET(pa,n,t,s) \
    pa.name = #n, pa.type = L2_TYPE_##t, pa.store = s
#define L2_PARAM_END(pa) \
    pa.name = NULL

/* channel handler specification structure */
struct l2_handler_st {
    int (*create)   (l2_context_t *ctx);
    int (*configure)(l2_context_t *ctx, const char *fmt, va_list ap);
    int (*open)     (l2_context_t *ctx, l2_channel_t *downstream);
    int (*write)    (l2_context_t *ctx, l2_channel_t *downstream, const char *buf, size_t buf_size);
    int (*flush)    (l2_context_t *ctx, l2_channel_t *downstream);
    int (*close)    (l2_context_t *ctx, l2_channel_t *downstream);
    int (*destroy)  (l2_context_t *ctx);
};

/* type of formatter callback function */
typedef int (*l2_formatter_t)(
    l2_context_t *context, 
    const char   *name, 
    const char   *param, 
    char         *buf, 
    size_t        bufsize, 
    va_list       ap
);

/* list of shipped (output) channel handlers */
extern l2_handler_t l2_handler_null;
extern l2_handler_t l2_handler_fd;
extern l2_handler_t l2_handler_file;
extern l2_handler_t l2_handler_pipe;
extern l2_handler_t l2_handler_socket;
extern l2_handler_t l2_handler_syslog;

/* list of shipped (filter) channel handlers */
extern l2_handler_t l2_handler_filter;
extern l2_handler_t l2_handler_prefix;
extern l2_handler_t l2_handler_buffer;

/* parameter operations */

/* channel operations */
l2_channel_t *l2_channel_create   (l2_handler_t *h);
int           l2_channel_configure(l2_channel_t *ch, const char *fmt, ...);
int           l2_channel_open     (l2_channel_t *ch);
int           l2_channel_write    (l2_channel_t *ch, const char *buf, size_t bufsize);
int           l2_channel_flush    (l2_channel_t *ch);
int           l2_channel_close    (l2_channel_t *ch);
int           l2_channel_destroy  (l2_channel_t *ch);
l2_channel_t *l2_channel_stack    (l2_channel_t *ch1, l2_channel_t *ch2);
int           l2_channel_setparams(l2_param_t p[], const char *fmt, va_list ap);

/* stream operations */
l2_stream_t  *l2_stream_create    (void);
l2_stream_t  *l2_stream_channel   (l2_stream_t *st, l2_channel_t *ch, unsigned int levelmask);
l2_stream_t  *l2_stream_formatter (l2_stream_t *st, l2_formatter_t *cb, l2_context_t *ctx);
unsigned int  l2_stream_levels    (l2_stream_t *st, unsigned int levelmask);
void          l2_stream_log       (l2_stream_t *st, unsigned int log_level, const char *fmt, ...);
void          l2_stream_vlog      (l2_stream_t *st, unsigned int log_level, const char *fmt, va_list ap);
void          l2_stream_destroy   (l2_stream_t *st);

#endif /* __L2_H__ */