From: Ryan Bloom Date: Tue, 8 Aug 2000 05:39:09 +0000 (+0000) Subject: Document util_xml using ScanDoc X-Git-Tag: APACHE_2_0_ALPHA_6~75 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=c41c099ff1b9e17f75bec415e017df33cd5dcc93;p=thirdparty%2Fapache%2Fhttpd.git Document util_xml using ScanDoc git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@86023 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/include/util_xml.h b/include/util_xml.h index 7d302360cce..6864ffafbf9 100644 --- a/include/util_xml.h +++ b/include/util_xml.h @@ -68,18 +68,34 @@ extern "C" { /* ### these will need to move at some point to a more logical spot */ /* simple strutures to keep a linked list of pieces of text */ -typedef struct ap_text -{ +typedef struct ap_text ap_text; + +/** Structure to keep a linked list of pieces of text */ +struct ap_text { + /** The current piece of text */ const char *text; + /** a pointer to the next piece of text + * @defvar ap_text *next */ struct ap_text *next; -} ap_text; +}; + +typedef struct ap_text_header ap_text_header; -typedef struct -{ +/** A list of pieces of text */ +struct ap_text_header { + /** The first piece of text in the list */ ap_text *first; + /** The last piece of text in the list */ ap_text *last; -} ap_text_header; - +}; + +/** + * Append a piece of text to the end of a list + * @param p The pool to allocate out of + * @param hdr The text header to append to + * @param text The new text to append + * @deffunc void ap_text_append(apr_pool_t *p, ap_text_header *hdr, const char *text) + */ API_EXPORT(void) ap_text_append(apr_pool_t *p, ap_text_header *hdr, const char *text); @@ -142,57 +158,104 @@ API_EXPORT(void) ap_text_append(apr_pool_t *p, ap_text_header *hdr, #define AP_XML_NS_ERROR_BASE -100 /* used only during processing */ #define AP_XML_NS_IS_ERROR(e) ((e) <= AP_XML_NS_ERROR_BASE) -/* -** ap_xml_doc: holds a parsed XML document -** ap_xml_elem: holds a parsed XML element -** ap_xml_attr: holds a parsed XML attribute -*/ - -typedef struct ap_xml_attr -{ - const char *name; /* attribute name */ - int ns; /* index into namespace array */ - - const char *value; /* attribute value */ - - struct ap_xml_attr *next; /* next attribute */ -} ap_xml_attr; - -typedef struct ap_xml_elem -{ - const char *name; /* element name */ - int ns; /* index into namespace array */ - const char *lang; /* xml:lang for attrs/contents */ - - ap_text_header first_cdata; /* cdata right after start tag */ - ap_text_header following_cdata; /* cdata after MY end tag */ - struct ap_xml_elem *parent; /* parent element */ - struct ap_xml_elem *next; /* next (sibling) element */ - struct ap_xml_elem *first_child; /* first child element */ - struct ap_xml_attr *attr; /* first attribute */ +typedef struct ap_xml_attr ap_xml_attr; +typedef struct ap_xml_elem ap_xml_elem; +typedef struct ap_xml_doc ap_xml_doc; + +/** ap_xml_attr: holds a parsed XML attribute */ +struct ap_xml_attr { + /** attribute name */ + const char *name; + /** index into namespace array */ + int ns; + + /** attribute value */ + const char *value; + + /** next attribute + * @defvar ap_xml_attr *next */ + struct ap_xml_attr *next; +}; + +/** ap_xml_elem: holds a parsed XML element */ +struct ap_xml_elem { + /** element name */ + const char *name; + /** index into namespace array */ + int ns; + /** xml:lang for attrs/contents */ + const char *lang; + + /** cdata right after start tag */ + ap_text_header first_cdata; + /** cdata after MY end tag */ + ap_text_header following_cdata; + + /** parent element + * @defvar ap_xml_elem *parent */ + struct ap_xml_elem *parent; + /** next (sibling) element + * @defvar ap_xml_elem *next */ + struct ap_xml_elem *next; + /** first child element + * @defvar ap_xml_elem *first_child */ + struct ap_xml_elem *first_child; + /** first attribute + * @defvar ap_xml_attr *attr */ + struct ap_xml_attr *attr; /* used only during parsing */ - struct ap_xml_elem *last_child; /* last child element */ - struct ap_xml_ns_scope *ns_scope; /* namespaces scoped by this elem */ + /** last child element + * @defvar ap_xml_elem *last_child */ + struct ap_xml_elem *last_child; + /** namespaces scoped by this elem + * @defvar ap_xml_ns_scope *ns_scope */ + struct ap_xml_ns_scope *ns_scope; /* used by modules during request processing */ + /** Place for modules to store private data */ void *private; -} ap_xml_elem; +}; #define AP_XML_ELEM_IS_EMPTY(e) ((e)->first_child == NULL && \ (e)->first_cdata.first == NULL) -typedef struct ap_xml_doc -{ - ap_xml_elem *root; /* root element */ - apr_array_header_t *namespaces; /* array of namespaces used */ -} ap_xml_doc; - +/** ap_xml_doc: holds a parsed XML document */ +struct ap_xml_doc { + /** root element */ + ap_xml_elem *root; + /** array of namespaces used */ + apr_array_header_t *namespaces; +}; + +/** + * Get XML post data and parse it + * @param r The current request + * @param pdoc The XML post data + * @return HTTP status code + * @deffunc int ap_xml_parse_input(request_rec *r, ap_xml_doc **pdoc) + */ API_EXPORT(int) ap_xml_parse_input(request_rec *r, ap_xml_doc **pdoc); -/* Converts an XML element tree to flat text */ +/** + * Converts an XML element tree to flat text + * @param p The pool to allocate out of + * @param elem The XML element to convert + * @param style How to covert the XML. One of: + * 
+ *     AP_XML_X2T_FULL                start tag, contents, end tag 
+ *     AP_XML_X2T_INNER               contents only 
+ *     AP_XML_X2T_LANG_INNER          xml:lang + inner contents 
+ *     AP_XML_X2T_FULL_NS_LANG        FULL + ns defns + xml:lang 
+ *
+ * @param namespaces The namespace of the current XML element + * @param ns_map Namespace mapping + * @param pbuf Buffer to put the converted text into + * @param psize Size of the converted text + * @deffunc void ap_xml_to_text(apr_pool_t *p, const ap_xml_elem *elem, int style, apr_array_header_t *namespaces, int *ns_map, const char **pbuf, size_t *psize); + */ API_EXPORT(void) ap_xml_to_text(apr_pool_t *p, const ap_xml_elem *elem, int style, apr_array_header_t *namespaces, int *ns_map, const char **pbuf, size_t *psize); @@ -203,18 +266,51 @@ API_EXPORT(void) ap_xml_to_text(apr_pool_t *p, const ap_xml_elem *elem, #define AP_XML_X2T_LANG_INNER 2 /* xml:lang + inner contents */ #define AP_XML_X2T_FULL_NS_LANG 3 /* FULL + ns defns + xml:lang */ +/** + * empty XML element + * @param p The pool to allocate out of + * @param elem The XML element to empty + * @return the string that was stored in the XML element + * @deffunc const char *ap_xml_empty_elem(apr_pool_t *p, const ap_xml_elem *elem) + */ API_EXPORT(const char *) ap_xml_empty_elem(apr_pool_t *p, const ap_xml_elem *elem); +/** + * quote an XML string + * Replace '<', '>', and '&' with '<', '>', and '&'. + * @param p The pool to allocate out of + * @param s The string to quote + * @param quotes If quotes is true, then replace '"' with '"'. + * @return The quoted string + * @deffunc const char *ap_xml_quote_string(apr_pool_t *p, const char *s, int quotes) + */ API_EXPORT(const char *) ap_xml_quote_string(apr_pool_t *p, const char *s, int quotes); + +/** + * Quote an XML element + * @param p The pool to allocate out of + * @param elem The element to quote + * @deffunc void ap_xml_quote_elem(apr_pool_t *p, ap_xml_elem *elem) + */ API_EXPORT(void) ap_xml_quote_elem(apr_pool_t *p, ap_xml_elem *elem); /* manage an array of unique URIs: ap_xml_insert_uri() and AP_XML_URI_ITEM() */ -/* return the URI's (existing) index, or insert it and return a new index */ +/** + * return the URI's (existing) index, or insert it and return a new index + * @param uri_array array to insert into + * @param uri The uri to insert + * @return int The uri's index + * @deffunc int ap_xml_insert_uri(apr_array_header_t *uri_array, const char *uri) + */ API_EXPORT(int) ap_xml_insert_uri(apr_array_header_t *uri_array, const char *uri); #define AP_XML_GET_URI_ITEM(ary, i) (((const char * const *)(ary)->elts)[i]) +#ifdef __cplusplus +} +#endif + #endif /* UTIL_XML_H */