/*
 * This file is part of Hubbub.
 * Licensed under the MIT License,
 *                http://www.opensource.org/licenses/mit-license.php
 * Copyright 2007-8 John-Mark Bell <jmb@netsurf-browser.org>
 */

#ifndef hubbub_functypes_h_
#define hubbub_functypes_h_

#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

#include <hubbub/types.h>

/**
 * Type of allocation function for hubbub 
 *
 * The semantics of this function are the same as for realloc().
 *
 * \param ptr   Pointer to object to reallocate, or NULL for a new allocation
 * \param size  Required length in bytes, or zero to free ::ptr
 * \param pw    Pointer to client data
 * \return Pointer to allocated object, or NULL on failure
 */
typedef void *(*hubbub_alloc)(void *ptr, size_t size, void *pw);

/**
 * Type of token handling function
 *
 * \param token  Pointer to token to handle
 * \param pw     Pointer to client data
 * \return HUBBUB_OK on success, appropriate error otherwise.
 */
typedef hubbub_error (*hubbub_token_handler)(
		const hubbub_token *token, void *pw);

/**
 * Type of parse error handling function
 *
 * \param line     Source line on which error occurred
 * \param col      Column in ::line of start of erroneous input
 * \param message  Error message
 * \param pw       Pointer to client data
 */
typedef void (*hubbub_error_handler)(uint32_t line, uint32_t col,
		const char *message, void *pw);

/**
 * Create a comment node
 *
 * \param ctx     Client's context
 * \param data    String content of node
 * \param result  Pointer to location to receive created node
 * \return 0 on success, 1 on failure.
 *
 * Postcondition: if successful, result's reference count must be 1.
 */
typedef int (*hubbub_tree_create_comment)(void *ctx, const hubbub_string *data,
		void **result);

/**
 * Create a doctype node
 *
 * \param ctx      Client's context
 * \param doctype  Data for doctype node (name, public id, system id)
 * \param result   Pointer to location to receive created node
 * \return 0 on success, 1 on failure.
 *
 * Postcondition: if successful, result's reference count must be 1.
 */
typedef int (*hubbub_tree_create_doctype)(void *ctx,
		const hubbub_doctype *doctype,
		void **result);

/**
 * Create an element node
 *
 * \param ctx     Client's context
 * \param tag     Data for element node (namespace, name, attributes)
 * \param result  Pointer to location to receive created node
 * \return 0 on success, 1 on failure.
 *
 * Postcondition: if successful, result's reference count must be 1.
 */
typedef int (*hubbub_tree_create_element)(void *ctx, const hubbub_tag *tag, 
		void **result);

/**
 * Create a text node
 *
 * \param ctx     Client's context
 * \param data    String content of node
 * \param result  Pointer to location to receive created node
 * \return 0 on success, 1 on failure.
 *
 * Postcondition: if successful, result's reference count must be 1.
 */
typedef int (*hubbub_tree_create_text)(void *ctx, const hubbub_string *data,
		void **result);

/**
 * Increase a node's reference count
 *
 * \param ctx   Client's context
 * \param node  Node to reference
 * \param 0 on success, 1 on failure.
 *
 * Postcondition: node's reference count is one larger than before
 */
typedef int (*hubbub_tree_ref_node)(void *ctx, void *node);

/**
 * Decrease a node's reference count
 *
 * \param ctx   Client's context
 * \param node  Node to reference
 * \param 0 on success, 1 on failure.
 *
 * Postcondition: If the node's reference count becomes zero, and it has no 
 * parent, and it is not the document node, then it is destroyed. Otherwise,
 * the reference count is one less than before.
 */
typedef int (*hubbub_tree_unref_node)(void *ctx, void *node);

/**
 * Append a node to the end of another's child list
 *
 * \param ctx     Client's context
 * \param parent  The node to append to
 * \param child   The node to append
 * \param result  Pointer to location to receive appended node
 * \return 0 on success, 1 on failure
 *
 * Postcondition: if successful, result's reference count is increased by 1
 *
 * Important: *result may not == child (e.g. if text nodes got coalesced)
 */
typedef int (*hubbub_tree_append_child)(void *ctx, void *parent, void *child,
		void **result);

/**
 * Insert a node into another's child list
 *
 * \param ctx        Client's context
 * \param parent     The node to insert into
 * \param child      The node to insert
 * \param ref_child  The node to insert before
 * \param result     Pointer to location to receive inserted node
 * \return 0 on success, 1 on failure
 *
 * Postcondition: if successful, result's reference count is increased by 1
 *
 * Important: *result may not == child (e.g. if text nodes got coalesced)
 */
typedef int (*hubbub_tree_insert_before)(void *ctx, void *parent, void *child,
		void *ref_child, void **result);

/**
 * Remove a node from another's child list
 *
 * \param ctx     Client context
 * \param parent  The node to remove from
 * \param child   The node to remove
 * \param result  Pointer to location to receive removed node
 * \return 0 on success, 1 on failure
 *
 * Postcondition: if successful, result's reference count is increased by 1
 */
typedef int (*hubbub_tree_remove_child)(void *ctx, void *parent, void *child,
		void **result);

/**
 * Clone a node
 * 
 * \param ctx     Client's context
 * \param node    The node to clone
 * \param deep    True to clone entire subtree, false to clone only the node
 * \param result  Pointer to location to receive clone
 * \return 0 on success, 1 on failure
 *
 * Postcondition: if successful, result's reference count must be 1.
 */
typedef int (*hubbub_tree_clone_node)(void *ctx, void *node, bool deep,
		void **result);

/**
 * Move all the children of one node to another
 *
 * \param ctx         Client's context
 * \param node        The initial parent node
 * \param new_parent  The new parent node
 * \return 0 on success, 1 on failure
 */
typedef int (*hubbub_tree_reparent_children)(void *ctx, void *node, 
		void *new_parent);

/**
 * Retrieve the parent of a node
 *
 * \param ctx           Client context
 * \param node          Node to retrieve the parent of
 * \param element_only  True if the parent must be an element, false otherwise
 * \param result        Pointer to location to receive parent node
 * \return 0 on success, 1 on failure
 *
 * If there is a parent node, but it is not an element node and element_only
 * is true, then act as if no parent existed.
 *
 * Postcondition: if there is a parent, then result's reference count must be
 * increased.
 */
typedef int (*hubbub_tree_get_parent)(void *ctx, void *node, bool element_only, 
		void **result);

/**
 * Determine if a node has children
 *
 * \param ctx     Client's context
 * \param node    The node to inspect
 * \param result  Location to receive result
 * \return 0 on success, 1 on failure
 */
typedef int (*hubbub_tree_has_children)(void *ctx, void *node, bool *result);

/**
 * Associate a node with a form
 *
 * \param ctx   Client's context
 * \param form  The form to associate with
 * \param node  The node to associate
 * \return 0 on success, 1 on failure
 */
typedef int (*hubbub_tree_form_associate)(void *ctx, void *form, void *node);

/**
 * Add attributes to a node
 *
 * \param ctx           Client's context
 * \param node          The node to add to
 * \param attributes    Array of attributes to add
 * \param n_attributes  Number of entries in array
 * \return 0 on success, 1 on failure
 */
typedef int (*hubbub_tree_add_attributes)(void *ctx, void *node,
		const hubbub_attribute *attributes, uint32_t n_attributes);

/**
 * Notification of the quirks mode of a document
 *
 * \param ctx   Client's context
 * \param mode  The quirks mode
 * \return 0 on success, 1 on failure
 */
typedef int (*hubbub_tree_set_quirks_mode)(void *ctx, hubbub_quirks_mode mode);

/**
 * Notification that a potential encoding change is required
 *
 * \param ctx      Client's context
 * \param charset  The new charset for the source data
 * \return 0 to ignore the change and continue using the current input handler,
 *         1 to stop processing immediately and return control to the client.
 */
typedef int (*hubbub_tree_encoding_change)(void *ctx, const char *encname);

#endif