nxml.h

libnxml-no-curl-简化版2007-07-01,一个别很不错的XML生成和解析程序。

 *
 * \code
 * nxml_data_t *data1, *data2;
 * data1=NULL;
 * nxml_add(nxml, NULL, &data1);
 *
 * data2=(nxml_data_t *)malloc(sizeof(nxml_data_t));
 * nxml_add(nxml, NULL, &data2);
 * \endcode
 */

/*
nxml_error_t	nxml_add		(nxml_t * nxml,
					 nxml_data_t *parent,
					 nxml_data_t **child);*/

/** 
 * This function removes a nxml_data_t child to a parent in the data 
 * struct. If parent is NULL the child will be removed in the root level of
 * XML document. This function doesn't free the child. If you want you can
 * reinsert the child in another parent tree or use the nxml_free_data 
 * function.
 *
 * \param nxml Pointer to a nxml_t data struct.
 * \param parent The parent of data struct child. If it is NULL, the
 * child will be searched in the root level.
 * \param child It is the pointer to the child that you want remove
 * \return the error code
 */
/*
nxml_error_t	nxml_remove		(nxml_t * nxml,
					 nxml_data_t *parent,
					 nxml_data_t *child);*/

/** 
 * This function creates a new nxml_attr_t data of a element in the data 
 * struct.
 *
 * \param nxml Pointer to a nxml_t data struct.
 * \param element The element of the new data struct attribute.
 * \param attribute The pointer to the your data struct. If it is NULL it will
 * be allocated, else no.
 * \return the error code
 */
/*
nxml_error_t	nxml_add_attribute	(nxml_t *nxml,
					 nxml_data_t *element,
					 nxml_attr_t **attribute);*/

/**
 * This function removes a nxml_attr_t data of a element. It does not free it
 * so you can reinsert o free it with nxml_free_attribute.
 *
 * \param nxml Pointer to a nxml_t data struct.
 * \param element The element that contains the attribute
 * \param attribute The attribute that you want remove.
 * \return the error code
 */
/*
nxml_error_t	nxml_remove_attribute	(nxml_t *nxml,
					 nxml_data_t *element,
					 nxml_attr_t *attribute);
*/
/**
 * This function adds a nxml_namespace_t data in a nxml document.
 *
 * \param nxml Pointer to a nxml_t data struct.
 * \param element The element of the new data struct namespace.
 * \param ns The namespace that you want add
 * \return the error code
 */
/*
nxml_error_t	nxml_add_namespace	(nxml_t *nxml,
		                         nxml_data_t *element,
					 nxml_namespace_t **ns);
*/
/**
 * This function removes a nxml_namespace_t data in a nxml document.
 *
 * \param nxml Pointer to a nxml_t data struct.
 * \param element The element of the new data struct namespace.
 * \param ns The namespace that you want remove
 * \return the error code
 */
/*
nxml_error_t	nxml_remove_namespace	(nxml_t *nxml,
		                         nxml_data_t *element,
					 nxml_namespace_t *ns);
*/
/**
 * This function sets the output function. If you set a your function the
 * parser write the error with this function. As default there is not a
 * function. If you want tou can set 'nxml_print_general' function that
 * print to stderr.
 *
 * \param nxml The struct create with nxml_new.
 * \param func Your function. If you don't want the function, set it to NULL.
 * As default a nxml_t element has not a output function.
 * \return the error code
 */
/*
nxml_error_t	nxml_set_func		(nxml_t * nxml,
					 void (*func) (char *, ...));*/

// void		nxml_print_generic	(char *, ...);

/**
 * This function sets the timeout in seconds for the download of a remote
 *  XML document. Default is 0 and 0 is no timeout.
 */
/*
nxml_error_t	nxml_set_timeout	(nxml_t * nxml,
					 int seconds);*/

/* PARSER FUNCTIONS *********************************************************/

/**
 * This function parses a url. It downloads a url with curl library and
 * parses it.
 *
 * \param nxml the struct create with nxml_new.
 * \param url the url that you want parse.
 * \return the error code
 */
/*******************************************
nxml_error_t	nxml_parse_url		(nxml_t * nxml,
					 char *url);
************************************************/
/** 
 * This function parses a file.
 *
 * \param nxml the struct create with nxml_new.
 * \param file the file that you want parse.
 * \return the error code
 */
nxml_error_t	nxml_parse_file		(nxml_t * nxml,
					 char *file);

/** 
 * This function parses a buffer in memory.
 *
 * \param nxml the struct create with nxml_new.
 * \param buffer the buffer that you want parse.
 * \param size the size of buffer. If size is 0, the function checks the 
 * length of your buffer searching a '\\0'.
 * \return the error code
 */
nxml_error_t	nxml_parse_buffer	(nxml_t * nxml,
					 char *buffer,
					 size_t size);

/* DTD FUNCTIONS ************************************************************/

/**
 * This function valids a XML document with its DTD.
 *
 * \param nxml the struct create with nxml_new.
 * \param flag is a attribute for this function. Use some enum like
 * NXML_DOCTYPEFLAG_DOWNLOAD | NXML_DOCTYPEFLAG_RECURSIVE
 * \return the error code
 */
nxml_error_t	nxml_valid_dtd		(nxml_t * nxml,
					 int flag);

/**
 * This function parses a remote DTD document and checks if the nxml_t
 * document is valid or not.
 *
 * \param nxml the struct of your XML Document
 * \param url the url that you want parse.
 * \param flag is a attribute for this function. Use some enum like
 * NXML_DOCTYPEFLAG_DOWNLOAD | NXML_DOCTYPEFLAG_RECURSIVE
 * \return the error code
 */
/***********************************************
nxml_error_t	nxml_dtd_parse_url	(nxml_t * nxml,
					 char *url,
					 int flag);
************************************************/
/** 
 * This function parses a local DTD document and checks if the nxml_t
 * document is valid or not.
 *
 * \param nxml the struct of your XML Document
 * \param file the file that you want parse.
 * \param flag is a attribute for this function. Use some enum like
 * NXML_DOCTYPEFLAG_DOWNLOAD | NXML_DOCTYPEFLAG_RECURSIVE
 * \return the error code
 */
nxml_error_t	nxml_dtd_parse_file	(nxml_t * nxml,
					 char *file,
					 int flag);

/** 
 * This function parses a buffer in memory as a DTD document and checks
 * if the nxml_t document is valid or not.
 *
 * \param nxml the struct of your XML Document
 * \param buffer the buffer that you want parse.
 * \param size the size of buffer. If size is 0, the function checks the 
 * length of your buffer searching a '\\0'.
 * \param flag is a attribute for this function. Use some enum like
 * NXML_DOCTYPEFLAG_DOWNLOAD | NXML_DOCTYPEFLAG_RECURSIVE
 * \return the error code
 */
nxml_error_t	nxml_dtd_parse_buffer	(nxml_t * nxml,
					 char *buffer,
					 size_t size,
					 int flag);

/* WRITE FUNCTIONS **********************************************************/

/**
 * This function writes the data struct in a local file.
 * \param nxml the nxml data strut
 * \param file the local file
 * \return the error code
 */
nxml_error_t	nxml_write_file		(nxml_t *nxml,
					 char *file);

/**
 * This function writes the data struct in a buffer.
 * \code
 * char *buffer;
 * buffer=NULL; // This is important!
 * nxml_write_buffer(nxml, &buffer);
 * \endcode
 *
 * The buffer must be NULL.
 *
 * \param nxml
 * \param buffer the memory buffer
 * \return the error code
 *//*
nxml_error_t	nxml_write_buffer	(nxml_t *nxml,
					 char **buffer);*/

/* FREE FUNCTIONS ************************************************************/

/**
 * This function removes the data in a structure nxml_t and makes it clean for
 * another usage.
 * \param nxml the pointer to you data struct.
 * \return the error code.
 */
nxml_error_t	nxml_empty		(nxml_t * nxml);

/** 
 * This function frees the memory of a nxml_t *element. After the free,
 * your data struct is not useful. If you want erase the internal data, use
 * nxml_empty function
 *
 * \param nxml the pointer to your data struct.
 * \return the error code.
 */
nxml_error_t	nxml_free		(nxml_t * nxml);

/**
 * This function removes the data in a structure nxml_doctype_t and makes 
 * it clean for another usage (another parsing action).
 *
 * \param doctype the pointer to you data struct.
 * \return the error code.
 */
nxml_error_t	nxml_empty_doctype	(nxml_doctype_t * doctype);

/** 
 * This function frees the memory of a nxml_doctype_t *element. After the free,
 * your data struct is not useful. If you want erase the internal data, use
 * nxml_empty_doctype function
 *
 * \param doctype the pointer to you data struct.
 * \return the error code.
 */
nxml_error_t	nxml_free_doctype	(nxml_doctype_t *doctype);

/**
 * This function frees the memory of a nxml_data_t *element and any its
 * children and its attributes.
 *
 * \param data the pointer to you data struct.
 * \return the error code
 */
nxml_error_t	nxml_free_data		(nxml_data_t *data);

/**
 * This function frees the memory of a nxml_attr_t *element.
 *
 * \param data the pointer to you data struct.
 * \return the error code
 */
nxml_error_t	nxml_free_attribute	(nxml_attr_t *data);

/**
 * This function frees the memory of a nxml_namespace_t *element.
 *
 * \param data the pointer to you data struct.
 * \return the error code
 */
nxml_error_t	nxml_free_namespace	(nxml_namespace_t *data);

/* EDIT FUNCTIONS ***********************************************************/
//
/**
 * This function returns the root element of xml data struct.
 * \code
 * nxml_t *nxml;
 * nxml_data_t *root;
 *
 * nxml_new(&nxml);
 * nxml_parser_file(nxml, "file.xml");
 * nxml_root_element(nxml, &root);
 * printf("%p\n",root);
 * nxml_free(nxml);
 * \endcode
 *
 * \param nxml the data struct
 * \param element the pointer to your nxml_data_t struct
 * \return the error code
 */
nxml_error_t	nxml_root_element	(nxml_t *nxml,
					 nxml_data_t **element);

/**
 * This function searchs the request element in the children of the data struct.
 * \code
 * nxml_t *nxml;
 * nxml_data_t *root;
 *
 * nxml_new(&nxml);
 * nxml_parser_file(nxml, "file.xml");
 * nxml_find_element(nxml, NULL, "hello_world", &root);
 * printf("%p\n",root);
 * nxml_free(nxml);
 * \endcode
 *
 * \param nxml the data struct
 * \param parent the data struct nxml_data_t of parent. If it is NULL, this 
 * function searchs in the root element level.
 * \param name the name of the node that you want.
 * \param element the pointer to your nxml_data_t struct. If element will be
 * NULL, the item that you want does not exist.
 * \return the error code
 */
nxml_error_t	nxml_find_element	(nxml_t *nxml,
					 nxml_data_t *parent,
					 char *name, 
					 nxml_data_t **element);

/**
 * This function searchs the first doctype element in the nxml_t document.
 *
 * \param nxml the data struct
 * \param doctype the pointer to your nxml_doctype_t struct. If element will be
 * NULL, the item that you want does not exist.
 * \return the error code
 *//*
nxml_error_t	nxml_doctype_element	(nxml_t *nxml,