1258945Sroberto/* 2258945Sroberto * Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC") 3258945Sroberto * Copyright (C) 1999-2001 Internet Software Consortium. 4258945Sroberto * 5258945Sroberto * Permission to use, copy, modify, and/or distribute this software for any 6258945Sroberto * purpose with or without fee is hereby granted, provided that the above 7258945Sroberto * copyright notice and this permission notice appear in all copies. 8258945Sroberto * 9258945Sroberto * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10258945Sroberto * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11258945Sroberto * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12258945Sroberto * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13258945Sroberto * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14258945Sroberto * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15258945Sroberto * PERFORMANCE OF THIS SOFTWARE. 16258945Sroberto */ 17258945Sroberto 18258945Sroberto/* $Id: bitstring.h,v 1.14 2007/06/19 23:47:18 tbox Exp $ */ 19258945Sroberto 20258945Sroberto#ifndef ISC_BITSTRING_H 21258945Sroberto#define ISC_BITSTRING_H 1 22258945Sroberto 23258945Sroberto/***** 24258945Sroberto ***** Module Info 25258945Sroberto *****/ 26258945Sroberto 27258945Sroberto/*! \file isc/bitstring.h 28258945Sroberto * 29258945Sroberto * \brief Bitstring manipulation functions. 30258945Sroberto * 31258945Sroberto * A bitstring is a packed array of bits, stored in a contiguous 32258945Sroberto * sequence of octets. The "most significant bit" (msb) of a bitstring 33258945Sroberto * is the high bit of the first octet. The "least significant bit" of a 34258945Sroberto * bitstring is the low bit of the last octet. 35258945Sroberto * 36258945Sroberto * Two bit numbering schemes are supported, "msb0" and "lsb0". 37258945Sroberto * 38258945Sroberto * In the "msb0" scheme, bit number 0 designates the most significant bit, 39258945Sroberto * and any padding bits required to make the bitstring a multiple of 8 bits 40258945Sroberto * long are added to the least significant end of the last octet. 41258945Sroberto * 42258945Sroberto * In the "lsb0" scheme, bit number 0 designates the least significant bit, 43258945Sroberto * and any padding bits required to make the bitstring a multiple of 8 bits 44258945Sroberto * long are added to the most significant end of the first octet. 45258945Sroberto * 46258945Sroberto * E.g., consider the bitstring "11010001111". This bitstring is 11 bits 47258945Sroberto * long and will take two octets. Let "p" denote a pad bit. In the msb0 48258945Sroberto * encoding, it would be 49258945Sroberto * 50258945Sroberto * \verbatim 51258945Sroberto * Octet 0 Octet 1 52258945Sroberto * | 53258945Sroberto * 1 1 0 1 0 0 0 1 | 1 1 1 p p p p p 54258945Sroberto * ^ | ^ 55258945Sroberto * | | 56258945Sroberto * bit 0 bit 15 57258945Sroberto * \endverbatim 58258945Sroberto * 59258945Sroberto * In the lsb0 encoding, it would be 60258945Sroberto * 61258945Sroberto * \verbatim 62258945Sroberto * Octet 0 Octet 1 63258945Sroberto * | 64258945Sroberto * p p p p p 1 1 0 | 1 0 0 0 1 1 1 1 65258945Sroberto * ^ | ^ 66258945Sroberto * | | 67258945Sroberto * bit 15 bit 0 68258945Sroberto * \endverbatim 69258945Sroberto */ 70258945Sroberto 71258945Sroberto/*** 72258945Sroberto *** Imports 73258945Sroberto ***/ 74258945Sroberto 75258945Sroberto#include <isc/lang.h> 76258945Sroberto#include <isc/types.h> 77258945Sroberto 78258945SrobertoISC_LANG_BEGINDECLS 79258945Sroberto 80258945Sroberto/*** 81258945Sroberto *** Types 82258945Sroberto ***/ 83258945Sroberto 84258945Srobertostruct isc_bitstring { 85258945Sroberto unsigned int magic; 86258945Sroberto unsigned char * data; 87258945Sroberto unsigned int length; 88258945Sroberto unsigned int size; 89258945Sroberto isc_boolean_t lsb0; 90258945Sroberto}; 91258945Sroberto 92258945Sroberto/*** 93258945Sroberto *** Functions 94258945Sroberto ***/ 95258945Sroberto 96258945Srobertovoid 97258945Srobertoisc_bitstring_init(isc_bitstring_t *bitstring, unsigned char *data, 98258945Sroberto unsigned int length, unsigned int size, isc_boolean_t lsb0); 99258945Sroberto/*!< 100258945Sroberto * \brief Make 'bitstring' refer to the bitstring of 'size' bits starting 101258945Sroberto * at 'data'. 'length' bits of the bitstring are valid. If 'lsb0' 102258945Sroberto * is set then, bit 0 refers to the least significant bit of the 103258945Sroberto * bitstring. Otherwise bit 0 is the most significant bit. 104258945Sroberto * 105258945Sroberto * Requires: 106258945Sroberto * 107258945Sroberto *\li 'bitstring' points to a isc_bitstring_t. 108258945Sroberto * 109258945Sroberto *\li 'data' points to an array of unsigned char large enough to hold 110258945Sroberto * 'size' bits. 111258945Sroberto * 112258945Sroberto *\li 'length' <= 'size'. 113258945Sroberto * 114258945Sroberto * Ensures: 115258945Sroberto * 116258945Sroberto *\li 'bitstring' is a valid bitstring. 117258945Sroberto */ 118258945Sroberto 119258945Srobertovoid 120258945Srobertoisc_bitstring_invalidate(isc_bitstring_t *bitstring); 121258945Sroberto/*!< 122258945Sroberto * \brief Invalidate 'bitstring'. 123258945Sroberto * 124258945Sroberto * Requires: 125258945Sroberto * 126258945Sroberto *\li 'bitstring' is a valid bitstring. 127258945Sroberto * 128258945Sroberto * Ensures: 129258945Sroberto * 130258945Sroberto *\li 'bitstring' is not a valid bitstring. 131258945Sroberto */ 132258945Sroberto 133258945Srobertovoid 134258945Srobertoisc_bitstring_copy(isc_bitstring_t *source, unsigned int sbitpos, 135258945Sroberto isc_bitstring_t *target, unsigned int tbitpos, 136258945Sroberto unsigned int n); 137258945Sroberto/*!< 138258945Sroberto * \brief Starting at bit 'sbitpos', copy 'n' bits from 'source' to 139258945Sroberto * the 'n' bits of 'target' starting at 'tbitpos'. 140258945Sroberto * 141258945Sroberto * Requires: 142258945Sroberto * 143258945Sroberto *\li 'source' and target are valid bitstrings with the same lsb0 setting. 144258945Sroberto * 145258945Sroberto *\li 'sbitpos' + 'n' is less than or equal to the length of 'source'. 146258945Sroberto * 147258945Sroberto *\li 'tbitpos' + 'n' is less than or equal to the size of 'target'. 148258945Sroberto * 149258945Sroberto * Ensures: 150258945Sroberto * 151258945Sroberto *\li The specified bits have been copied, and the length of 'target' 152258945Sroberto * adjusted (if required). 153258945Sroberto */ 154258945Sroberto 155258945SrobertoISC_LANG_ENDDECLS 156258945Sroberto 157258945Sroberto#endif /* ISC_BITSTRING_H */ 158