bloom.h

Go to the documentation of this file.
00001 /**
00002  * @file ccn/bloom.h
00003  *
00004  * Bloom filters.
00005  *
00006  * Part of the CCNx C Library.
00007  *
00008  * Copyright (C) 2008, 2009 Palo Alto Research Center, Inc.
00009  *
00010  * This library is free software; you can redistribute it and/or modify it
00011  * under the terms of the GNU Lesser General Public License version 2.1
00012  * as published by the Free Software Foundation.
00013  * This library is distributed in the hope that it will be useful,
00014  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00015  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
00016  * Lesser General Public License for more details. You should have received
00017  * a copy of the GNU Lesser General Public License along with this library;
00018  * if not, write to the Free Software Foundation, Inc., 51 Franklin Street,
00019  * Fifth Floor, Boston, MA 02110-1301 USA.
00020  */
00021 
00022 #ifndef CCN_BLOOM_DEFINED
00023 #define CCN_BLOOM_DEFINED
00024 
00025 #include <stddef.h>
00026 
00027 struct ccn_bloom;
00028 
00029 /*
00030  * Create an empty Bloom filter, sized appropriately for the estimated
00031  * number of members.
00032  */
00033 struct ccn_bloom *ccn_bloom_create(int estimated_members,
00034                                    const unsigned char seed[4]);
00035 
00036 /*
00037  * Create an updatable Bloom filter from a wire representation.
00038  * Result does not share storage with the input.
00039  */
00040 struct ccn_bloom *ccn_bloom_from_wire(const void *data, size_t size);
00041 
00042 /*
00043  * Deallocation.
00044  */
00045 void ccn_bloom_destroy(struct ccn_bloom **);
00046 
00047 /*
00048  * Add an element.
00049  * Returns the number of bits changed in the filter.
00050  */
00051 int ccn_bloom_insert(struct ccn_bloom *b, const void *key, size_t size);
00052 
00053 /*
00054  * Test for membership. False positives are possible.
00055  */
00056 int ccn_bloom_match(struct ccn_bloom *b, const void *key, size_t size);
00057 
00058 /*
00059  * Fetch the number of elements in the filter.  If b was created
00060  * from a wire representation, this will be approximate.
00061  */
00062 int ccn_bloom_n(struct ccn_bloom *b);
00063 
00064 /*
00065  * Return the number of bytes needed for the on-wire representation.
00066  */
00067 int ccn_bloom_wiresize(struct ccn_bloom *b);
00068 
00069 /*
00070  * Store the on-wire representation.
00071  */
00072 int ccn_bloom_store_wire(struct ccn_bloom *b,
00073                          unsigned char *dest, size_t destsize);
00074 
00075 /*
00076  * This structure reflects the on-wire representation of the Bloom filter.
00077  */
00078 struct ccn_bloom_wire {
00079     unsigned char lg_bits;  /* 13 maximum (8 kilobits), 3 minimum (one byte) */
00080     unsigned char n_hash;   /* number of hash functions to employ */
00081     unsigned char method;   /* allow for various hashing algorithms */
00082     unsigned char reserved; /* must be 0 for now */
00083     unsigned char seed[4];  /* can seed hashes differently */
00084     unsigned char bloom[1024]; /* 8 kilobits maximum */
00085 };
00086 
00087 /*
00088  * ccn_bloom_validate_wire: Check for a valid on-wire representation
00089  * If not valid, returns NULL.
00090  * If valid, returns buf cast to the new pointer type.
00091  */
00092 const struct ccn_bloom_wire *
00093     ccn_bloom_validate_wire(const void *buf, size_t size);
00094 /*
00095  * ccn_bloom_match_wire: Test membership using on-wire representation
00096  * Caller is expected to have validated f.
00097  * Returns true to indicate a match.
00098  */
00099 int ccn_bloom_match_wire(const struct ccn_bloom_wire *f,
00100                          const void *key, size_t size);
00101 
00102 #endif

Generated on Thu Feb 16 00:43:59 2012 for Content-Centric Networking in C by  doxygen 1.5.6