/**

 * @file samples.h

 * @brief Object to process log samples.

 * @author Rainer Gerhards

 *

 * This object handles log samples, and in actual log sample files.

 * It co-operates with the ptree object to build the actual parser tree.

 *//*

 *

 * liblognorm - a fast samples-based log normalization library

 * Copyright 2010 by Rainer Gerhards and Adiscon GmbH.

 *

 * 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_V1_SAMPLES_H_INCLUDED

#define	LIBLOGNORM_V1_SAMPLES_H_INCLUDED

#include <stdio.h>	/* we need es_size_t */

#include <libestr.h>

/**

 * A single log sample.

 */

struct ln_v1_samp {

	es_str_t *msg;

};

/**

 * Reads a sample stored in buffer buf and creates a new ln_v1_samp object

 * out of it.

 *

 * @note

 * It is the caller's responsibility to delete the newly

 * created ln_v1_samp object if it is no longer needed.

 *

 * @param[ctx] ctx current library context

 * @param[buf] cstr buffer containing the string contents of the sample

 * @param[lenBuf] length of the sample contained within buf

 * @return Newly create object or NULL if an error occured.

 */

struct ln_v1_samp *

ln_v1_processSamp(ln_ctx ctx, const char *buf, es_size_t lenBuf);

/**

 * Read a sample from repository (sequentially).

 *

 * Reads a sample starting with the current file position and

 * creates a new ln_v1_samp object out of it.

 *

 * @note

 * It is the caller's responsibility to delete the newly

 * created ln_v1_samp object if it is no longer needed.

 *

 * @param[in] ctx current library context

 * @param[in] repo repository descriptor

 * @param[out] isEof must be set to 0 on entry and is switched to 1 if EOF occured.

 * @return Newly create object or NULL if an error or EOF occured.

 */

struct ln_v1_samp *

ln_v1_sampRead(ln_ctx ctx, FILE *repo, int *isEof);

/**

 * Free ln_v1_samp object.

 */

void

ln_v1_sampFree(ln_ctx ctx, struct ln_v1_samp *samp);

/**

 * Parse a given sample

 *

 * @param[in] ctx current library context

 * @param[in] rule string (with prefix and suffix '%' markers)

 * @param[in] offset in rule-string to start at (it should be pointed to

 *  starting character: '%')

 * @param[in] temp string buffer(working space),

 *  externalized for efficiency reasons

 * @param[out] return code (0 means success)

 * @return newly created node, which can be added to sample tree.

 */

ln_fieldList_t*

ln_v1_parseFieldDescr(ln_ctx ctx, es_str_t *rule, es_size_t *bufOffs,

				   es_str_t **str, int* ret);

#endif /* #ifndef LIBLOGNORM_V1_SAMPLES_H_INCLUDED */