WebSVN – HelenOS – Blame – /branches/network/uspace/srv/net/structures/char_map.h

Rev	Author	Line No.	Line
3666	mejdrech	1	/*
		2	* Copyright (c) 2008 Lukas Mejdrech
		3	* All rights reserved.
		4	*
		5	* Redistribution and use in source and binary forms, with or without
		6	* modification, are permitted provided that the following conditions
		7	* are met:
		8	*
		9	* - Redistributions of source code must retain the above copyright
		10	* notice, this list of conditions and the following disclaimer.
		11	* - Redistributions in binary form must reproduce the above copyright
		12	* notice, this list of conditions and the following disclaimer in the
		13	* documentation and/or other materials provided with the distribution.
		14	* - The name of the author may not be used to endorse or promote products
		15	* derived from this software without specific prior written permission.
		16	*
		17	* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
		18	* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
		19	* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
		20	* IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
		21	* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
		22	* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
		23	* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
		24	* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
		25	* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
		26	* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
		27	*/
		28
		29	/** @addtogroup net
		30	* @{
		31	*/
		32
		33	/** @file
3846	mejdrech	34	* A character string to integer map header file.
3666	mejdrech	35	*/
		36
		37	#ifndef __CHAR_MAP_H__
		38	#define __CHAR_MAP_H__
		39
3846	mejdrech	40	/** An invalid assigned value used also if an entry does not exist.
		41	*/
3666	mejdrech	42	#define CHAR_MAP_NULL ( -1 )
		43
3846	mejdrech	44	/** A type definition of a character string to integer map.
		45	* @see char_map
		46	*/
3666	mejdrech	47	typedef struct char_map char_map_t;
3846	mejdrech	48
		49	/** A type definition of a character string to integer map pointer.
		50	* @see char_map
		51	*/
3666	mejdrech	52	typedef char_map_t * char_map_ref;
		53
3846	mejdrech	54	/** A character string to integer map item.
		55	* This structure recursivelly contains itself as a character by character tree.
		56	* The actually mapped character string consists o fall the parent characters and the actual one.
		57	*/
3666	mejdrech	58	struct char_map{
3846	mejdrech	59
		60	/** An actually mapped character.
		61	*/
		62	char c;
		63
		64	/** A stored integral value.
		65	*/
		66	int value;
		67
		68	/** A next character array size.
		69	*/
		70	int size;
		71
		72	/** The first free position in the next character array.
		73	*/
		74	int next;
		75
		76	/** The next character array.
		77	*/
3666	mejdrech	78	char_map_ref * items;
3846	mejdrech	79
		80	/** The consistency check magic value.
		81	*/
		82	int magic;
3666	mejdrech	83	};
		84
3846	mejdrech	85	/** Adds the value with the key to the map.
		86	* @param map The character string to integer map. Input/output parameter.
		87	* @param identifier The key zero ('\0') terminated character string. The key character string is processed until the first terminating zero ('\0') character after the given length is found. Input parameter.
		88	* @param length The key character string length. The parameter may be zero (0) which means that the string is processed until the terminating zero ('\0') character is found. Input parameter.
		89	* @param value The integral value to be stored for the key character string. Input parameter.
		90	* @returns EOK on success.
		91	* @returns EINVAL if the map is not valid.
		92	* @returns EINVAL if the identifier parameter is NULL.
		93	* @returns EINVAL if the length parameter zero (0) and the identifier parameter is an empty character string (the first character is the terminating zero ('\0) character.
		94	* @returns EEXIST if the key character string is already used.
		95	* @returns Other error codes as defined for the char_map_add_item() function.
		96	*/
		97	int char_map_add( char_map_ref map, const char * identifier, size_t length, const int value );
		98
		99	/** Clears and destroys the map.
		100	* @param map The character string to integer map. Input/output parameter.
		101	*/
3666	mejdrech	102	void char_map_destroy( char_map_ref map );
3846	mejdrech	103
		104	/** Excludes the value assigned to the key from the map.
		105	* The entry is cleared from the map.
		106	* @param map The character string to integer map. Input/output parameter.
		107	* @param identifier The key zero ('\0') terminated character string. The key character string is processed until the first terminating zero ('\0') character after the given length is found. Input parameter.
		108	* @param length The key character string length. The parameter may be zero (0) which means that the string is processed until the terminating zero ('\0') character is found. Input parameter.
		109	* @returns The integral value assigned to the key character string.
		110	* @returns CHAR_MAP_NULL if the key is not assigned a value.
		111	*/
		112	int char_map_exclude( char_map_ref map, const char * identifier, size_t length );
		113
		114	/** Returns the value assigned to the key from the map.
		115	* @param map The character string to integer map. Input parameter.
		116	* @param identifier The key zero ('\0') terminated character string. The key character string is processed until the first terminating zero ('\0') character after the given length is found. Input parameter.
		117	* @param length The key character string length. The parameter may be zero (0) which means that the string is processed until the terminating zero ('\0') character is found. Input parameter.
		118	* @returns The integral value assigned to the key character string.
		119	* @returns CHAR_MAP_NULL if the key is not assigned a value.
		120	*/
		121	int char_map_find( const char_map_ref map, const char * identifier, size_t length );
		122
		123	/** Returns the value assigned to the map.
		124	* @param map The character string to integer map. Input parameter.
		125	* @returns The integral value assigned to the map.
		126	* @returns CHAR_MAP_NULL if the map is not assigned a value.
		127	*/
		128	int char_map_get_value( const char_map_ref map );
		129
		130	/** Initializes the map.
		131	* @param map The character string to integer map. Input/output parameter.
		132	* @returns EOK on success.
		133	* @returns EINVAL if the map parameter is NULL.
		134	* @returns ENOMEM if there is no memory left.
		135	*/
3666	mejdrech	136	int char_map_initialize( char_map_ref map );
		137
3846	mejdrech	138	/** Adds or updates the value with the key to the map.
		139	* @param map The character string to integer map. Input/output parameter.
		140	* @param identifier The key zero ('\0') terminated character string. The key character string is processed until the first terminating zero ('\0') character after the given length is found. Input parameter.
		141	* @param length The key character string length. The parameter may be zero (0) which means that the string is processed until the terminating zero ('\0') character is found. Input parameter.
		142	* @param value The integral value to be stored for the key character string. Input parameter.
		143	* @returns EOK on success.
		144	* @returns EINVAL if the map is not valid.
		145	* @returns EINVAL if the identifier parameter is NULL.
		146	* @returns EINVAL if the length parameter zero (0) and the identifier parameter is an empty character string (the first character is the terminating zero ('\0) character.
		147	* @returns EEXIST if the key character string is already used.
		148	* @returns Other error codes as defined for the char_map_add_item() function.
		149	*/
		150	int char_map_update( char_map_ref map, const char * identifier, size_t length, const int value );
		151
3666	mejdrech	152	#endif
		153
		154	/** @}
		155	*/

Subversion Repositories HelenOS

(root)/branches/network/uspace/srv/net/structures/char_map.h – Rev 3886