/*
 * Copyright 2005-2009 Nicolas Bernard <http://www.lafraze.net/nbernard/>
 *
 * 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.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

#ifndef _BLOOM_H_
#define _BLOOM_H_

/**
 * newbloom create a new bloom filter.
 * parameters:
 *    first: size of the filter in bits.
 *    second: number of hashes to use. must be in [1, 16]
 *    last: should we use a random salt for this filter?
 *      if set, it is harder for a malicious user to polute
 *      the filter. The drawback is that a same value won't
 *      be hashed in the same value in to different filter.
 * returned value:
 *    an int which is a bloom filter descriptor or a value < 0
 *      in case of error.
 *
 * WARNING: OpenSSL should have been initialized beforehand.
*/
extern int newbloom(unsigned long, unsigned int, unsigned int);

/**
 * destroybloom destroy a bloom filter.
 * parameters:
 *    int bd, where bd is the descriptor of the filter to destroy
 * returned value:
 *    0 if successful, < 0 otherwise.
 */
extern int destroybloom(int);

/**
 * add: add some data in a filter.
 * parameters:
 *    int bd, the descriptor of the filter in which the data will be
 *      registered;
 *    void* data, a buffer with the data;
 *    unsigned long datasize, the size of the data buffer.
 * returned value:
 *    0 if successful, < 0 otherwise.
 */
extern int add(int, const void*, unsigned long);


/**
 * isin: match some data against a filter.
 * parameters:
 *    int bd, the descriptor of the filter in which the data will be
 *      searched;
 *    void* data, a buffer with the data;
 *    unsigned long datasize, the size of the data buffer.
 * returned value:
 *    0 if the data match the filter, 0 if not, < 0 if an error occured
 */
extern int isin(int, const void*, unsigned long);


/**
 *
 * The struct blhashes, combined with the bloomhash, addhash and isinbloom
 * functions allow finer grained operations (compared to add and isin).
 *
 * nb: this should be considered as an opaque type.
 *
 */
struct blhashes {
	int bloomid;
	unsigned long int hashes[16];
};

/**
 * bloomhash: compute the hash of some data (for the given bloomfilter bd)
 * and return it in a struct blhashes.
 *
 * parameters:
 *    int bd, the descriptor of the filter for which hash will be computed;
 *    struct blhashes* blh, the structure in which the hash will be stored.
 *            if NULL, it will be allocated dynamically.
 *    void* data, the data to be hashed. They are not modified;
 *    unsigned long datasize, the size of the data in octets.
 *
 * returned value:
 */
extern struct blhashes* bloomhash(int bd, struct blhashes* blh, const void* data, unsigned long datasize);

/**
 * addhash: same as add, but for pre-hashed data.
 *
 * parameters:
 *    int bd, the descriptor of the filter in which the data will be
 *        registered;
 *    struct blhashes *blh, the hash of the data to be registered.
 *
 * returned value:
 *    0 if all is well;
 *    <0 if an error occures (consult sources or guru).
 */
extern int addhash(int bd, const struct blhashes *blh);

/**
 * isinbloom: takes a bloom descriptor and a struct blhashes and tell whether
 *     the corresponding data are already in the bloom filter or not.
 *
 * parameters:
 *     int bd, the bloom filter descriptor to search;
 *     struct blhashes *blh, the hash of the data to search for.
 *
 * returned value:
 *     < 0 in case of error;
 *     0 if there is no match;
 *     1 if there is a match (remember, this is probabilistic!).
 */
extern int isinbloom(int bd, const struct blhashes *blh);

/**
 * displayhash: (for debug purpose only): displays the content of a
 *   struct blhashes.
 * parameters:
 *    struct blhashes *blh, the structure to display;
 *    FILE* out, the stream on which the data have to be sent.
 */
extern void displayhash(struct blhashes *blh, FILE* out);

#ifdef WITH_DATALOC

#include "dataloc.h"

extern int bloompack(struct dataloc *loc, int bd);
extern int bloomunpack(struct dataloc *loc);

#endif /* WITH_DATALOC */

#endif /* _BLOOM_H_ */