reportxml.h 6.98 KB
Newer Older
1 2 3 4 5 6 7 8
/* Icecast
 *
 * This program is distributed under the GNU General Public License, version 2.
 * A copy of this license is included with this source.
 *
 * Copyright 2018,      Philipp "ph3-der-loewe" Schafft <lion@lion.leolix.org>,
 */

9 10
/* This file contains the API for report XML document parsing, manipulation, and rendering. */

11 12 13 14 15 16 17 18
#ifndef __REPORTXML_H__
#define __REPORTXML_H__

#include <libxml/tree.h>

#include "icecasttypes.h"
#include "compat.h"

19 20 21
/* XML Tag Types
 * While a hint of what the nodes are used for is given, see the specification for more details.
 */
22
typedef enum {
23
    /* This is a virtual type used to indicate error conditions */
24
    REPORTXML_NODE_TYPE__ERROR,
25
    /* <report> is the root element of report XML documents */
26
    REPORTXML_NODE_TYPE_REPORT,
27
    /* <definition> is used to define templates */
28
    REPORTXML_NODE_TYPE_DEFINITION,
29
    /* <incident> defines an event that is reported */
30
    REPORTXML_NODE_TYPE_INCIDENT,
31
    /* <state> defines the state an <incident> resulted in */
32
    REPORTXML_NODE_TYPE_STATE,
33
    /* <backtrace> provides helpful information about the location some event happend */
34
    REPORTXML_NODE_TYPE_BACKTRACE,
35
    /* <position> defines an element within <backtrace> */
36
    REPORTXML_NODE_TYPE_POSITION,
37 38 39
    /* <more> allows to skip <position>s in <backtrace> for any reason
     * (e.g. they are unknown or consider of no intrest)
     */
40
    REPORTXML_NODE_TYPE_MORE,
41
    /* <fix> provides a machine readable way to actually fix the problem */
42
    REPORTXML_NODE_TYPE_FIX,
43
    /* <action> defines a specific action to do */
44
    REPORTXML_NODE_TYPE_ACTION,
45
    /* <reason> allows to define why an event happend */
46
    REPORTXML_NODE_TYPE_REASON,
47 48 49
    /* <text> is used to provide messages to the user.
     * The content of <text> is not machine readable.
     */
50
    REPORTXML_NODE_TYPE_TEXT,
51
    /* <timestamp> provides a way to present a point in time an event happend */
52
    REPORTXML_NODE_TYPE_TIMESTAMP,
53
    /* <resource> names a resource that was involved in the event such as user input or the result */
54
    REPORTXML_NODE_TYPE_RESOURCE,
55
    /* <value> provides an actual value for a <resource> */
56
    REPORTXML_NODE_TYPE_VALUE,
57
    /* <reference> provides a way to refer to external documents such as documentation */
58
    REPORTXML_NODE_TYPE_REFERENCE,
59
    /* <extension> is used to allow application specific extensions */
60 61 62
    REPORTXML_NODE_TYPE_EXTENSION
} reportxml_node_type_t;

63

64
/* ---[ Document level ]--- */
65 66
/* The document object is NOT thread safe. */

67 68

/* This creates a new, empty report XML document */
69
reportxml_t *           reportxml_new(void);
70
/* This gets the root node of a report XML document */
71
reportxml_node_t *      reportxml_get_root_node(reportxml_t *report);
72 73 74 75 76 77 78
/* This selects a node by an attribute and it's value.
 * This is mostly useful to look for an object by using it's ID.
 * If more than one node matches the first one found is returned.
 * If the parameter include_definitions is true nodes from within
 * <definition> are also considered. If it is false nodes inside
 * <definition>s are skipped.
 */
79
reportxml_node_t *      reportxml_get_node_by_attribute(reportxml_t *report, const char *key, const char *value, int include_definitions);
80 81
/* This gets a node by it's type. Otherwise identical to reportxml_get_node_by_attribute() */
reportxml_node_t *      reportxml_get_node_by_type(reportxml_t *report, reportxml_node_type_t type, int include_definitions);
82
/* This function parses an XML document and returns the parst report XML document */
83
reportxml_t *           reportxml_parse_xmldoc(xmlDocPtr doc);
84
/* This function renders an report XML document as XML structure */
85 86
xmlDocPtr               reportxml_render_xmldoc(reportxml_t *report);

87

88
/* ---[ Node level ]--- */
89 90
/* The node object is NOT thread safe. */

91 92 93 94

/* This creates a new node of type type.
 * It's id, definition, and akindof attributes can be given as parameters.
 */
95
reportxml_node_t *      reportxml_node_new(reportxml_node_type_t type, const char *id, const char *definition, const char *akindof);
96
/* This parses an XML node and returns the resulting report XML node */
97
reportxml_node_t *      reportxml_node_parse_xmlnode(xmlNodePtr xmlnode);
98
/* Copy an report XML node (and it's children) */
99
reportxml_node_t *      reportxml_node_copy(reportxml_node_t *node);
100
/* Renders an report XML node as XML node */
101
xmlNodePtr              reportxml_node_render_xmlnode(reportxml_node_t *node);
102
/* This gets the type of an report XML node */
103
reportxml_node_type_t   reportxml_node_get_type(reportxml_node_t *node);
104
/* Gets and Sets attribute values */
105 106
int                     reportxml_node_set_attribute(reportxml_node_t *node, const char *key, const char *value);
char *                  reportxml_node_get_attribute(reportxml_node_t *node, const char *key);
107
/* Adds, counts, and get child nodes */
108 109 110
int                     reportxml_node_add_child(reportxml_node_t *node, reportxml_node_t *child);
ssize_t                 reportxml_node_count_child(reportxml_node_t *node);
reportxml_node_t *      reportxml_node_get_child(reportxml_node_t *node, size_t idx);
111
/* This gets an child by it's value of the given attribute. See reportxml_get_node_by_attribute() for more details. */
112
reportxml_node_t *      reportxml_node_get_child_by_attribute(reportxml_node_t *node, const char *key, const char *value, int include_definitions);
113 114
/* This gets a child by it's type. Otherwise identical to reportxml_node_get_child_by_attribute() */
reportxml_node_t *      reportxml_node_get_child_by_type(reportxml_node_t *node, reportxml_node_type_t type, int include_definitions);
115
/* This gets and sets the text content of an node (used for <text>) */
116 117
int                     reportxml_node_set_content(reportxml_node_t *node, const char *value);
char *                  reportxml_node_get_content(reportxml_node_t *node);
118
/* Adds, counts, and gets XML childs (used for <extension>) */
119 120 121
int                     reportxml_node_add_xml_child(reportxml_node_t *node, xmlNodePtr child);
ssize_t                 reportxml_node_count_xml_child(reportxml_node_t *node);
xmlNodePtr              reportxml_node_get_xml_child(reportxml_node_t *node, size_t idx);
122

123

124
/* ---[ Database level ]--- */
125 126
/* The database object is thread safe. */

127 128

/* Create a new database object */
129
reportxml_database_t *  reportxml_database_new(void);
130
/* Add an report to the database */
131
int                     reportxml_database_add_report(reportxml_database_t *db, reportxml_t *report);
132 133 134 135
/* Build a node (copy) from the data in the database based on the given ID (using "definition" and "defines" attributes)
 * depth may be used to select how many recursions may be used to resolve definitions within defines.
 * The default value is selected by passing -1 (recommended).
 */
136
reportxml_node_t *      reportxml_database_build_node(reportxml_database_t *db, const char *id, ssize_t depth);
137
/* This does the same as reportxml_database_build_node() except that a new report document is returned. */
138 139
reportxml_t *           reportxml_database_build_report(reportxml_database_t *db, const char *id, ssize_t depth);

140
#endif