Greenbone Vulnerability Management Libraries 22.10.0
xmlutils.h File Reference

Headers for simple XML reader. More...

#include "serverutils.h"
#include <glib.h>
#include <gnutls/gnutls.h>
#include <stdio.h>

Go to the source code of this file.

Data Structures

struct  context_data_t
 XML context. More...
 
struct  entity_s
 XML element. More...
 
struct  xml_search_data_t
 Data for xml search functions. More...
 

Typedefs

typedef GSList * entities_t
 Entities.
 
typedef struct entity_sentity_t
 
typedef struct _xmlNode * element_t
 
typedef struct xml_file_iterator_structxml_file_iterator_t
 

Functions

void xml_handle_start_element (context_data_t *, const gchar *, const gchar **, const gchar **)
 Handle the start of an OMP XML element.
 
void xml_handle_end_element (context_data_t *, const gchar *)
 Handle the end of an XML element.
 
void xml_handle_text (context_data_t *, const gchar *, gsize)
 Handle additional text of an XML element.
 
entities_t next_entities (entities_t)
 Return all the entities from an entities_t after the first.
 
entity_t first_entity (entities_t)
 Return the first entity from an entities_t.
 
entity_t add_entity (entities_t *, const char *, const char *)
 Add an XML entity to a tree of entities.
 
int compare_entities (entity_t, entity_t)
 Compare two XML entity.
 
entity_t entity_child (entity_t, const char *)
 Get a child of an entity.
 
const char * entity_attribute (entity_t, const char *)
 Get an attribute of an entity.
 
char * entity_name (entity_t entity)
 Get the name an entity.
 
char * entity_text (entity_t entity)
 Get the text an entity.
 
void free_entity (entity_t)
 Free an entity, recursively.
 
void print_entity (FILE *, entity_t)
 Print an XML entity.
 
void print_entity_format (entity_t, gpointer indentation)
 Print an XML entity to stdout, recursively printing its children.
 
int try_read_entity_and_string (gnutls_session_t *, int, entity_t *, GString **)
 Try read an XML entity tree from the manager.
 
int read_entity_and_string (gnutls_session_t *, entity_t *, GString **)
 Try read an XML entity tree from the manager.
 
int read_entity_and_string_c (gvm_connection_t *, entity_t *, GString **)
 Try read an XML entity tree from the manager.
 
int read_entity_and_text (gnutls_session_t *, entity_t *, char **)
 Read an XML entity tree from the manager.
 
int read_entity_and_text_c (gvm_connection_t *, entity_t *, char **)
 Read an XML entity tree from the manager.
 
int try_read_entity (gnutls_session_t *, int, entity_t *)
 Try read an XML entity tree from the manager.
 
int try_read_entity_c (gvm_connection_t *, int, entity_t *)
 Try read an XML entity tree from the manager.
 
int read_entity (gnutls_session_t *, entity_t *)
 Read an XML entity tree from the manager.
 
int read_entity_s (int, entity_t *)
 Read an XML entity tree from the socket.
 
int read_entity_c (gvm_connection_t *, entity_t *)
 Read an XML entity tree from the manager.
 
int read_string (gnutls_session_t *, GString **)
 Read entity and text. Free the entity immediately.
 
int read_string_c (gvm_connection_t *, GString **)
 Read entity and text. Free the entity immediately.
 
int read_text_c (gvm_connection_t *, char **)
 Read text from the server.
 
int parse_entity (const char *, entity_t *)
 Read an XML entity tree from a string.
 
void print_entity_to_string (entity_t entity, GString *string)
 Print an XML entity tree to a GString, appending it if string is not.
 
int xml_count_entities (entities_t)
 Count the number of entities.
 
void xml_string_append (GString *, const char *,...)
 Append formatted escaped XML to a string.
 
int find_element_in_xml_file (gchar *, gchar *, GHashTable *)
 Tests if an XML file contains an element with given attributes.
 
int parse_element (const gchar *, element_t *)
 Read an XML element tree from a string.
 
void element_free (element_t)
 Free an entire element tree.
 
const gchar * element_name (element_t)
 Get the name of an element.
 
gchar * element_attribute (element_t, const gchar *)
 Get an attribute of an element.
 
gchar * element_text (element_t)
 Get text of an element.
 
element_t element_child (element_t, const gchar *)
 Get a child of an element.
 
element_t element_first_child (element_t)
 Get the first child of an element.
 
element_t element_next (element_t)
 Get the next sibling of an element.
 
gchar * element_to_string (element_t element)
 Output the XML element as a string.
 
void print_element_to_string (element_t element, GString *string)
 Print an XML element tree to a GString, appending it if string is not.
 
xml_file_iterator_t xml_file_iterator_new (void)
 Allocates a new, uninitialized XML file iterator.
 
int xml_file_iterator_init_from_file_path (xml_file_iterator_t, const char *, int)
 Initializes an XML file iterator to read from a given path.
 
void xml_file_iterator_free (xml_file_iterator_t)
 Frees an XML file iterator and all of its internal data structures.
 
int xml_file_iterator_rewind (xml_file_iterator_t)
 Rewinds an XML file iterator by rewinding the file and creating a new XML parser context.
 
element_t xml_file_iterator_next (xml_file_iterator_t, gchar **)
 Get the next subelement from a XML file iterator.
 

Detailed Description

Headers for simple XML reader.

Typedef Documentation

◆ element_t

typedef struct _xmlNode* element_t

◆ entities_t

typedef GSList* entities_t

Entities.

◆ entity_t

typedef struct entity_s* entity_t

◆ xml_file_iterator_t

Function Documentation

◆ add_entity()

entity_t add_entity ( entities_t * entities,
const char * name,
const char * text )

Add an XML entity to a tree of entities.

Parameters
[in]entitiesThe tree of entities
[in]nameName of the entity. Copied, copy is freed by free_entity.
[in]textText of the entity. Copied, copy is freed by free_entity.
Returns
The new entity.

◆ compare_entities()

int compare_entities ( entity_t entity1,
entity_t entity2 )

Compare two XML entity.

Parameters
[in]entity1First entity.
[in]entity2First entity.
Returns
0 if equal, 1 otherwise.

◆ element_attribute()

gchar * element_attribute ( element_t element,
const gchar * name )

Get an attribute of an element.

Parameters
[in]elementElement.
[in]nameName of the attribute.
Returns
Attribute value if found, else NULL. Caller must g_free.

◆ element_child()

element_t element_child ( element_t element,
const gchar * name )

Get a child of an element.

Parameters
[in]elementElement.
[in]nameName of the child.
Returns
Element if found, else NULL.

◆ element_first_child()

element_t element_first_child ( element_t element)

Get the first child of an element.

Parameters
[in]elementElement.
Returns
Child if there is one, else NULL.

◆ element_free()

void element_free ( element_t element)

Free an entire element tree.

Beware that this frees the entire tree that element is part of, including any ancestors.

Parameters
[in]elementElement.

◆ element_name()

const gchar * element_name ( element_t element)

Get the name of an element.

Parameters
[in]elementElement.
Returns
Element name.

◆ element_next()

element_t element_next ( element_t element)

Get the next sibling of an element.

Parameters
[in]elementElement.
Returns
Next sibling element if there is one, else NULL.

◆ element_text()

gchar * element_text ( element_t element)

Get text of an element.

If element is not NULL then the return is guaranteed to be a string. So if the caller has NULL checked element then there is no need for the caller to NULL check the return.

Parameters
[in]elementElement.
Returns
NULL if element is NULL, else the text. Caller must g_free.

◆ element_to_string()

gchar * element_to_string ( element_t element)

Output the XML element as a string.

The generated XML string will include namespace definitions from ancestor elements.

Parameters
[in]elementThe element to output as a string.
Returns
The newly allocated XML string.

◆ entity_attribute()

const char * entity_attribute ( entity_t entity,
const char * name )

Get an attribute of an entity.

Parameters
[in]entityEntity.
[in]nameName of the attribute.
Returns
Attribute if found, else NULL.

◆ entity_child()

entity_t entity_child ( entity_t entity,
const char * name )

Get a child of an entity.

Parameters
[in]entityEntity.
[in]nameName of the child.
Returns
Entity if found, else NULL.

◆ entity_name()

char * entity_name ( entity_t entity)

Get the name an entity.

Parameters
[in]entityEntity.
Returns
Entity name, which is freed by free_entity.

◆ entity_text()

char * entity_text ( entity_t entity)

Get the text an entity.

Parameters
[in]entityEntity.
Returns
Entity text, which is freed by free_entity.

◆ find_element_in_xml_file()

int find_element_in_xml_file ( gchar * file_path,
gchar * find_element,
GHashTable * find_attributes )

Tests if an XML file contains an element with given attributes.

Parameters
[in]file_pathPath of the XML file.
[in]find_elementName of the element to find.
[in]find_attributesGHashTable of attributes to find.
Returns
1 if element was found, 0 if not.

◆ first_entity()

entity_t first_entity ( entities_t entities)

Return the first entity from an entities_t.

Parameters
[in]entitiesThe list of entities.
Returns
The first entity.

◆ free_entity()

void free_entity ( entity_t entity)

Free an entity, recursively.

Parameters
[in]entityThe entity, can be NULL.

◆ next_entities()

entities_t next_entities ( entities_t entities)

Return all the entities from an entities_t after the first.

Parameters
[in]entitiesThe list of entities.
Returns
All the entities that follow the first.

◆ parse_element()

int parse_element ( const gchar * string,
element_t * element )

Read an XML element tree from a string.

Caller must not free string until caller is finished using element.

Parameters
[in]stringInput string.
[out]elementLocation for parsed element tree, or NULL if not required. If given, set to NULL on failure. Free with element_free.
Returns
0 success, -1 read error, -2 parse error, -3 XML ended prematurely, -4 setup error.

◆ parse_entity()

int parse_entity ( const char * string,
entity_t * entity )

Read an XML entity tree from a string.

Parameters
[in]stringInput string.
[out]entityPointer to an entity tree.
Returns
0 success, -1 read error, -2 parse error, -3 XML ended prematurely.

◆ print_element_to_string()

void print_element_to_string ( element_t element,
GString * string )

Print an XML element tree to a GString, appending it if string is not.

empty.

Parameters
[in]elementElement tree to print to string.
[in,out]stringString to write to.

◆ print_entity()

void print_entity ( FILE * stream,
entity_t entity )

Print an XML entity.

Parameters
[in]entityThe entity.
[in]streamThe stream to which to print.

◆ print_entity_format()

void print_entity_format ( entity_t entity,
gpointer indent )

Print an XML entity to stdout, recursively printing its children.

Does very basic indentation for pretty printing.

This function is used as the (callback) GFunc in g_slist_foreach.

Parameters
[in]entityThe entity.
[in]indentIndentation level, indentation width is 2 spaces. Use GINT_TO_POINTER to convert a integer value when passing this parameter.

◆ print_entity_to_string()

void print_entity_to_string ( entity_t entity,
GString * string )

Print an XML entity tree to a GString, appending it if string is not.

empty.

Parameters
[in]entityEntity tree to print to string.
[in,out]stringString to write to.

◆ read_entity()

int read_entity ( gnutls_session_t * session,
entity_t * entity )

Read an XML entity tree from the manager.

Parameters
[in]sessionPointer to GNUTLS session.
[out]entityPointer to an entity tree.
Returns
0 success, -1 read error, -2 parse error, -3 end of file.

◆ read_entity_and_string()

int read_entity_and_string ( gnutls_session_t * session,
entity_t * entity,
GString ** string_return )

Try read an XML entity tree from the manager.

Parameters
[in]sessionPointer to GNUTLS session.
[out]entityPointer to an entity tree.
[out]string_returnAn optional return location for the text read from the session. If NULL then it simply remains NULL. If a pointer to NULL then it points to a freshly allocated GString on successful return. Otherwise it points to an existing GString onto which the text is appended.
Returns
0 success, -1 read error, -2 parse error, -3 end of file.

◆ read_entity_and_string_c()

int read_entity_and_string_c ( gvm_connection_t * connection,
entity_t * entity,
GString ** string_return )

Try read an XML entity tree from the manager.

Parameters
[in]connectionConnection.
[out]entityPointer to an entity tree.
[out]string_returnAn optional return location for the text read from the session. If NULL then it simply remains NULL. If a pointer to NULL then it points to a freshly allocated GString on successful return. Otherwise it points to an existing GString onto which the text is appended.
Returns
0 success, -1 read error, -2 parse error, -3 end of file.

◆ read_entity_and_text()

int read_entity_and_text ( gnutls_session_t * session,
entity_t * entity,
char ** text )

Read an XML entity tree from the manager.

Parameters
[in]sessionPointer to GNUTLS session.
[out]entityPointer to an entity tree.
[out]textA pointer to a pointer, at which to store the address of a newly allocated string holding the text read from the session, if the text is required, else NULL.
Returns
0 success, -1 read error, -2 parse error, -3 end of file.

◆ read_entity_and_text_c()

int read_entity_and_text_c ( gvm_connection_t * connection,
entity_t * entity,
char ** text )

Read an XML entity tree from the manager.

Parameters
[in]connectionConnection.
[out]entityEntity tree.
[out]textA pointer to a pointer, at which to store the address of a newly allocated string holding the text read from the session, if the text is required, else NULL.
Returns
0 success, -1 read error, -2 parse error, -3 end of file.

◆ read_entity_c()

int read_entity_c ( gvm_connection_t * connection,
entity_t * entity )

Read an XML entity tree from the manager.

Parameters
[in]connectionConnection.
[out]entityPointer to an entity tree.
Returns
0 success, -1 read error, -2 parse error, -3 end of file.

◆ read_entity_s()

int read_entity_s ( int socket,
entity_t * entity )

Read an XML entity tree from the socket.

Parameters
[in]socketSocket to read from.
[out]entityPointer to an entity tree.
Returns
0 success, -1 read error, -2 parse error, -3 end of file.

◆ read_string()

int read_string ( gnutls_session_t * session,
GString ** string )

Read entity and text. Free the entity immediately.

Parameters
[in]sessionPointer to GNUTLS session to read from.
[out]stringReturn location for the string.
Returns
0 success, -1 read error, -2 parse error, -3 end of file.

◆ read_string_c()

int read_string_c ( gvm_connection_t * connection,
GString ** string )

Read entity and text. Free the entity immediately.

Parameters
[in]connectionConnection.
[out]stringReturn location for the string.
Returns
0 success, -1 read error, -2 parse error, -3 end of file.

◆ read_text_c()

int read_text_c ( gvm_connection_t * connection,
char ** text )

Read text from the server.

Parameters
[in]connectionConnection.
[out]textA pointer to a pointer, at which to store the address of a newly allocated string holding the text read from the session.
Returns
0 success, -1 read error, -2 argument error.

◆ try_read_entity()

int try_read_entity ( gnutls_session_t * session,
int timeout,
entity_t * entity )

Try read an XML entity tree from the manager.

Parameters
[in]sessionPointer to GNUTLS session.
[in]timeoutServer idle time before giving up, in seconds. 0 to wait forever.
[out]entityPointer to an entity tree.
Returns
0 success, -1 read error, -2 parse error, -3 end of file, -4 timeout.

◆ try_read_entity_and_string()

int try_read_entity_and_string ( gnutls_session_t * session,
int timeout,
entity_t * entity,
GString ** string_return )

Try read an XML entity tree from the manager.

Parameters
[in]sessionPointer to GNUTLS session.
[in]timeoutServer idle time before giving up, in seconds. 0 to wait forever.
[out]entityPointer to an entity tree.
[out]string_returnAn optional return location for the text read from the session. If NULL then it simply remains NULL. If a pointer to NULL then it points to a freshly allocated GString on successful return. Otherwise it points to an existing GString onto which the text is appended.
Returns
0 success, -1 read error, -2 parse error, -3 end of file, -4 timeout, -5 null buffer.

◆ try_read_entity_c()

int try_read_entity_c ( gvm_connection_t * connection,
int timeout,
entity_t * entity )

Try read an XML entity tree from the manager.

Parameters
[in]connectionConnection.
[in]timeoutServer idle time before giving up, in seconds. 0 to wait forever.
[out]entityPointer to an entity tree.
Returns
0 success, -1 read error, -2 parse error, -3 end of file, -4 timeout.

◆ xml_count_entities()

int xml_count_entities ( entities_t entities)

Count the number of entities.

Parameters
[in]entitiesEntities.
Returns
Number of entities.

◆ xml_file_iterator_free()

void xml_file_iterator_free ( xml_file_iterator_t iterator)

Frees an XML file iterator and all of its internal data structures.

Parameters
[in]iteratorThe XML file iterator to free.

◆ xml_file_iterator_init_from_file_path()

int xml_file_iterator_init_from_file_path ( xml_file_iterator_t iterator,
const char * file_path,
int output_depth )

Initializes an XML file iterator to read from a given path.

Parameters
[in]iteratorPointer to the iterator to initialize.
[in]file_pathPath to the file to read from.
[in]output_depthXML tree depth at which to return elements.
Returns
-1 error, 0 success, 1 already initialized, 2 error opening file (errno is set to reason), 3 error creating parser context

◆ xml_file_iterator_new()

xml_file_iterator_t xml_file_iterator_new ( void )

Allocates a new, uninitialized XML file iterator.

Free with xml_file_iterator_free.

Returns
Opaque pointer to the XML file iterator data structure.

◆ xml_file_iterator_next()

element_t xml_file_iterator_next ( xml_file_iterator_t iterator,
gchar ** error )

Get the next subelement from a XML file iterator.

Parameters
[in]iteratorThe XML file iterator to get the element from.
[out]errorError message output, set to NULL on success / EOF
Returns
The next subelement (free with element_free) or NULL if finished or on error.

◆ xml_file_iterator_rewind()

int xml_file_iterator_rewind ( xml_file_iterator_t iterator)

Rewinds an XML file iterator by rewinding the file and creating a new XML parser context.

Parameters
[in]iteratorThe XML file iterator to rewind.
Returns
0 success, 1 error creating new parser context

◆ xml_handle_end_element()

void xml_handle_end_element ( context_data_t * context,
const gchar * element_name )

Handle the end of an XML element.

Parameters
[in]contextParser context.
[in]element_nameXML element name.

◆ xml_handle_start_element()

void xml_handle_start_element ( context_data_t * context,
const gchar * element_name,
const gchar ** attribute_names,
const gchar ** attribute_values )

Handle the start of an OMP XML element.

Parameters
[in]contextParser context.
[in]element_nameXML element name.
[in]attribute_namesXML attribute name.
[in]attribute_valuesXML attribute values.

◆ xml_handle_text()

void xml_handle_text ( context_data_t * context,
const gchar * text,
gsize text_len )

Handle additional text of an XML element.

Parameters
[in]contextParser context.
[in]textThe text.
[in]text_lenLength of the text.

◆ xml_string_append()

void xml_string_append ( GString * xml,
const char * format,
... )

Append formatted escaped XML to a string.

Parameters
[in]xmlXML string.
[in]formatFormat string.
[in]...Arguments for format string.