iec103/confrw.h

#if	!defined(__CONFRW_H__QWERUOIPUADFJHAFKLHADSFHADSFVCMBVZXCVQOEWIRADSHJKXZJVBLWQERYO)
#define	__CONFRW_H__QWERUOIPUADFJHAFKLHADSFHADSFVCMBVZXCVQOEWIRADSHJKXZJVBLWQERYO

/*!
 *	\if developer_doc
 *		\file 
 *	
 *		\brief  读配置文件的调用接口头文件,包括:系统限值常量, 外部接口函数声明头文件。
 *
 *		id: $Id: confrw.h,v 1.2 2006/08/04 03:37:33 zhuzhenhua Exp $
 *
 *		\author 杨小波 prcharold@sina.com.cn develop1@szscada.com 
 *	\endif
*/


//#include <util/util.h>
#include "confrw_errno.h"

#ifndef _WIN32
#define CONFRWLIB_API
#else
#ifdef CONFRWLIB_EXPORTS
	#define CONFRWLIB_API __declspec(dllexport)
#else
	#define CONFRWLIB_API __declspec(dllimport)
#endif// CONFRWLIB_EXPORTS
#endif// _WIN32

/*!
*	\if by_group
*		\addtogroup grp_config_rw
*		@{
*	\endif
*/

/*!
 *	\brief	打开配置文件, 返回表示配置文件的句柄
 *
 *	\param	pszfname	--[in]	配置文件的全路径名(默认为 char [MAX_PATH]类型)
 *	\param	ppvhandle	--[in]	在函数执行成功的情况下, 返回配置文件(的上下文环境)句柄
 *
 *	\retval	返回值
 *	\retval	SUCCESS	--	成功的执行了该函数, 并打开了给定的配置文件
 *	\retval	其它	--	失败代码
 *
 */
CONFRWLIB_API int conf_open ( const char * pszfname, void ** ppvhandle );






/*!
 *	\brief	关闭配置文件句柄
 *
 *	\param	handle	--[in]	配置文件句柄
 *	
 *	\retval	SUCCESS	--	成功的关闭了指定的配置文件句柄(包括资源释放等工作)
 *	\retval	ERROR_CONF_HANLDE	--	错误的配置文件读写句柄
 *	\retval	其它	--	失败代码
 *
 *	\note
 *		如果输入的参数非配置文件(上下文)句柄, 则不作任何事.
 *
 */
CONFRWLIB_API int	conf_close ( void * handle );





/*!
 *	\brief	根据指定的 [段]及键的名称, 获取配置文件中的配置项
 *
 *	\param	handle		--[in]	配置文件句柄
 *	\param	pszsec_name	--[in]	段名, 以null字符结尾的字符串
 *	\param	pszkey_name	--[in]	键名称, 以null字符结尾的字符串
 *	\param	pszdefault	--[in]	键的默认值, 以null字符结尾的字符串,如果配置文件中没有该键的配置, 同时, 该参数不为空, 则返回该值
 *	\param	pbuf		--[out]	返回值的缓冲区
 *	\param	buffer_length	--[in]	缓冲区长度
 *	
 *	\retval	SUCCESS	--	配置的键值存在, 且成功地读出
 *	\retval	如果给出默认值, 则在欲读取的键值/键不存在地情况下, 同样返回SUCCESS
 *	\retval	ERROR_CONF_SECTION	--	欲读取的键所在的段不存在
 *	\retval	ERROR_CONF_KEY		--	欲读取的键不存在
 *	\retval	其它	--	失败代码
 */
CONFRWLIB_API int conf_read_key ( void * handle, 
					const char * pszsec_name, 
					const char * pszkey_name,
					const char * pszdefault,
					char * pbuf,
					int buffer_length );






/*!
 *	\brief	修改/添加一个新的配置项
 *
 *	\param	handle			--[in]	配置文件句柄
 *	\param	pszsec_name		--[in]	段名
 *	\param	pszkey_name		--[in]	键名
 *	\param	pszkey_value	--[in]	键的值
 *	\param	force_insert	--[in]	如果(段, 键)不存在, 是否需要插入该(段, 键)的配置值,
 *							如果该参数等于0, 则不插入该配置项, 否则, 插入该配置项.
 *	
 *	\retval	SUCCESS	--	成功
 *	\retval	其它	--	失败代码
 *	
 *	\note
 *		如果 force_insert 为0, 则当配置文件中不存在指定段时, 返回 ERROR_CONF_SECTION;
 *		如果不存在指定(段/键)组合时, 返回 ERROR_CONF_KEY.
 */
CONFRWLIB_API int conf_write_key ( void * handle,
					const char * pszsec_name,
					const char * pszkey_name,
					const char * pszkey_value,
					int force_insert );

 



/*!
 *	\brief	从配置文件中删除一个指定的配置项(段, 键)
 *
 *	\param	handle		--[in]	配置文件句柄
 *	\param	pszsec_name	--[in]	段名
 *	\param	pszkey_name	--[in]	键名
 *	
 *	\retval	SUCCESS	--	成功的删除了指定的配置项
 *	\retval	其它	--	失败代码
 *
 *	\note
 *		如果指定的段不存在, 则返回 ERROR_CONF_SECTION
 *		如果指定(段, 键名称)组合不存在, 则返回 ERROR_CONF_KEY
 */
CONFRWLIB_API int conf_delete_key ( void * handle,
						const char * pszsec_name,
						const char * pszkey_name );





/*!
 *	\brief	删除配置文件中一个整段的配置
 *
 *	\param	handle		--[in]	配置文件句柄
 *	\param	pszsec_name	--[in]	希望删除的段的名称, 以null字符结尾的字符串
 *
 *	\retval	SUCCESS	--	成功的删除了配置文件中的指定的段
 *	\retval	其它	--	失败代码
 *
 *	\note
 *		如果指定的段不存在, 则返回 ERROR_CONF_SECTION
 */
CONFRWLIB_API int conf_delete_section ( void * handle,
							const char * pszsec_name );

/*!
*	\if by_group
*		@}
*	\endif
*/


#endif	//!defined(__CONFRW_H__QWERUOIPUADFJHAFKLHADSFHADSFVCMBVZXCVQOEWIRADSHJKXZJVBLWQERYO)