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