/**
 * @file annot.h
 * @brief The annotation set object
 * @class ln_annot annot.h
 *//*
 * Copyright 2011 by Rainer Gerhards and Adiscon GmbH.
 *
 * Modified by Pavel Levshin (pavel@levshin.spb.ru) in 2013
 *
 * This file is meant to be included by applications using liblognorm.
 * For lognorm library files themselves, include "lognorm.h".
 *
 * This file is part of liblognorm.
 *
 * 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
 *
 * A copy of the LGPL v2.1 can be found in the file "COPYING" in this distribution.
 */
#ifndef LIBLOGNORM_ANNOT_H_INCLUDED
#define	LIBLOGNORM_ANNOT_H_INCLUDED
#include <libestr.h>

typedef struct ln_annotSet_s ln_annotSet;
typedef struct ln_annot_s ln_annot;
typedef struct ln_annot_op_s ln_annot_op;
typedef enum {ln_annot_ADD=0, ln_annot_RM=1} ln_annot_opcode;

/**
 * List of annotation operations.
 */
struct ln_annot_op_s {
	ln_annot_op *next;
	ln_annot_opcode opc; /**< opcode */
	es_str_t *name;
	es_str_t *value;
};

/**
 * annotation object
 */
struct ln_annot_s {
	ln_annot *next;	/**< used for chaining annotations */
	es_str_t *tag;	/**< tag associated for this annotation */
	ln_annot_op *oproot;
};

/**
 * annotation set object
 *
 * Note: we do not (yet) use a hash table. However, performance should
 * be gained by pre-processing rules so that tags directly point into
 * the annotation. This is even faster than hash table access.
 */
struct ln_annotSet_s {
	ln_annot *aroot;
	ln_ctx ctx;	/**< save our context for easy dbgprintf et al... */
};

/* Methods */


/**
 * Allocates and initializes a new annotation set.
 * @memberof ln_annot
 *
 * @param[in] ctx current library context. This MUST match the
 * 		context of the parent.
 *
 * @return pointer to new node or NULL on error
 */
ln_annotSet* ln_newAnnotSet(ln_ctx ctx);


/**
 * Free annotation set and destruct all members.
 * @memberof ln_annot
 *
 * @param[in] tree pointer to annot to free
 */
void ln_deleteAnnotSet(ln_annotSet *as);


/**
 * Find annotation inside set based on given tag name.
 * @memberof ln_annot
 *
 * @param[in] as annotation set
 * @param[in] tag tag name to look for
 *
 * @returns NULL if not found, ptr to object otherwise
 */
ln_annot* ln_findAnnot(ln_annotSet *as, es_str_t *tag);


/**
 * Add annotation to set.
 * If an annotation associated with this tag already exists, these
 * are combined. If not, a new annotation is added. Note that the
 * caller must not access any of the objects passed in to this method
 * after it has finished (objects may become deallocated during the
 * method).
 * @memberof ln_annot
 *
 * @param[in] as annotation set
 * @param[in] annot annotation to add
 *
 * @returns 0 on success, something else otherwise
 */
int ln_addAnnotToSet(ln_annotSet *as, ln_annot *annot);


/**
 * Allocates and initializes a new annotation.
 * The tag passed in identifies the new annotation. The caller
 * no longer owns the tag string after calling this method, so
 * it must not access the same copy when the method returns.
 * @memberof ln_annot
 *
 * @param[in] tag tag associated to annot (must not be NULL)
 * @return pointer to new node or NULL on error
 */
ln_annot* ln_newAnnot(es_str_t *tag);


/**
 * Free annotation and destruct all members.
 * @memberof ln_annot
 *
 * @param[in] tree pointer to annot to free
 */
void ln_deleteAnnot(ln_annot *annot);


/**
 * Add an operation to the annotation set.
 * The operation description will be added as entry.
 * @memberof ln_annot
 *
 * @param[in] annot pointer to annot to modify
 * @param[in] op operation
 * @param[in] name name of field, must NOT be re-used by caller
 * @param[in] value value of field, may be NULL (e.g. in remove operation),
 * 		    must NOT be re-used by caller
 * @returns 0 on success, something else otherwise
 */
int ln_addAnnotOp(ln_annot *anot, ln_annot_opcode opc, es_str_t *name, es_str_t *value);


/**
 * Annotate an event.
 * This adds annotations based on the event's tagbucket.
 * @memberof ln_annot
 *
 * @param[in] ctx current context
 * @param[in] event event to annotate (updated with anotations on exit)
 * @returns 0 on success, something else otherwise
 */
int ln_annotate(ln_ctx ctx, struct json_object *json, struct json_object *tags);

#endif /* #ifndef LOGNORM_ANNOT_H_INCLUDED */