libdocview C API References

docview.h is the C header of libdocview. It provides all functions, structures, enumerations required to interact with Docview. It mainly consists of two parts. One part is for applications like documentation viewer or browsers, IDEs for handling documentations. Another part is for extensions. The first part provides functions required to load and unload extensions, parse documents into document trees and access them. The second part is extension related. It defines the most important structure for extensions written in C, docview_extension_functions, which holds all required function pointers of an extension. All symbols defined in this file is prefixed with docview_.

Include this file with:

#include <docview.h>

Typedefs

typedef void docview_doc_tree_node

Define void as docview_doc_tree_node.

Enums

enum docview_extension_applicability_level

Enum holding all possible values of applicability level of an extension.

For more, see “What is applicability level?”.

Values:

enumerator docview_extension_applicability_level_tiny

The extension applies to a tiny amount of documentations.

enumerator docview_extension_applicability_level_small

The extension applies to a small amount of documentations, but not as small as tiny.

enumerator docview_extension_applicability_level_medium

The extension applies to a bigger amount of documentations then small.

enumerator docview_extension_applicability_level_big

The extension applies to a reasonable amount of documentations.

enumerator docview_extension_applicability_level_huge

The extension applies to a huge amount of documentations.

Functions

bool docview_load_ext(const char *path)

Loads an extension from given path.

This function loads an extension from given path. If extension is already loaded, there is no effects. If extension loading fails, false is returned.

Return

true on success, false on failure

Parameters

  • path: path to extension

void docview_unload_ext(const char *path)

Unloads extension with given path.

This function unloads extension with given path. If extension isn’t loaded, there is no effects.

Parameters

  • path: path to extension

bool docview_ext_is_loaded(std::filesystem::path path)

Check whether extension at given path is loaded.

This function checks whether an extension at given path is located.

Return

whether extension at given path is loaded

Parameters

  • path: path to extension

docview_doc_tree_node *docview_get_docs_tree(const char *path)

Returns a pointer to document tree of a path, NULL on failure.

This function returns a pointer to document tree of a path, NULL on failure. The pointer returned should not be freed by the application.

Return

pointer to document tree

Parameters

  • path: path to documents

docview_document docview_get_doc(docview_doc_tree_node *node)

Returns the path or HTML content of document.

This function will return a structure of a const char* and a bool. The value bool will true of the const char* points to a URI, false if the const char* points to HTML content.

Return

path or HTML content of document

Parameters

  • node: pointer to a node in document tree

const char *docview_get_brief(docview_doc_tree_node *node)

Returns the brief of from document.

This function will return the brief of the the document specified by parameter node. Return value should be in plain text (although any type of text is allowed). May return empty string.

Return

brief of from document

Parameters

  • node: pointer to a node in document tree

const char *docview_get_details(docview_doc_tree_node *node)

Returns the details from document.

This will will return the details from the document specified by parameter node. Return value should be in plain text (although any type of text is allowed). May return empty string.

Return

details of from document

Parameters

  • node: pointer to a node in document tree

const char *docview_get_section(docview_doc_tree_node *node)

Returns a section from document.

This will return a section from the document specified by parameter node. Return value should be in plain text (although any type of text is allowed). May return empty string.

Return

details of from document

Parameters

  • node: pointer to a node in document tree

const docview_doc_tree_node *const *docview_search(const char *query)

Searches through all loaded document tree.

This function searches through the title and synonyms of all nodes of all document trees (including root nodes). Matches occurs only when title or any of synonyms follows or matches exactly (e.g. abc matches with abc, abcabc, abcdef, but not with acb). Returned array does not have any particular order.

Return

NULL terminated array with nodes of matched documents

Parameters

  • query: the search query

bool docview_validate(const docview_doc_tree_node *node)

Checks whether a document node is still valid.

This function checks whether a document node is still valid. A document may be invalidate because of unloading an extension. It is recommended to validate one node from every document node tree after unloading an extension.

Return

whether a document node is valid

Parameters

  • node: the node to validate

docview_doc_tree_node *docview_doc_tree_node_parent(docview_doc_tree_node *node)

Returns the parent of a document node.

Return

parent of a document node

Parameters

  • node: pointer to document node

const char *docview_doc_tree_node_title(docview_doc_tree_node *node)

Returns the title of a document node.

Return

title of a document node

Parameters

  • node: pointer to document node

const char *const *docview_doc_tree_node_synonyms(docview_doc_tree_node *node)

Returns a NULL terminated array of synonyms of title.

This function returns a NULL terminated array of synonyms of title. Here synonyms means alternative title or search query to find this document.

Return

NULL terminated array of synonyms of title

Parameters

  • node: pointer to document node

const docview_doc_tree_node *const *docview_doc_tree_node_children(docview_doc_tree_node *node)

Returns a NULL terminated array of children of document node.

Return

NULL terminated array of children

Parameters

  • node: pointer to document node

struct docview_extension_doc_tree_node
#include <docview.h>

Structure for holding a document node.

This structure holds all information about a document node. For more, see “What is a document node?”.

Public Members

const docview_extension_doc_tree_node *parent = NULL

Pointer to parent, NULL if there is no parent.

const char *title

The title of document.

const char *const *synonyms

Synonyms of title, alternative search queries for finding this document, NULL terminated.

const docview_extension_doc_tree_node *const *children

Array of pointers to children, empty if there is no child, NULL terminated.

struct docview_document
#include <docview.h>

Struct holding document content in HTML or URI.

Public Members

const char *content_or_uri

Document content in HTML or URI.

bool is_uri

true if content_or_uri a is URI, false otherwise

struct docview_extension_functions
#include <docview.h>

Structure for holding function pointers of an extension.

Public Members

docview_extension_applicability_level (*applicability_level)()

Returns the applicability level of extension.

Extensions must implement this function. This is used determine the extension calling order. Returning wrong value might cause misbehaviour. See documentation of enum docview_extension_applicability_level and it’s members for more information.

Return

applicability level of extension

const docview_extension_doc_tree_node *(*func_get_docs_tree)(const char *path)

Returns a pointer to document tree of a path, nullptr on failure.

Extensions must implement this function. Note that memory used by the tree isn’t managed by libdocview, it’s extension’s responsibility to do and not do that.

Return

pointer to document tree

Parameters

  • path: path to documents

docview_document (*get_doc)(const docview_extension_doc_tree_node *node)

Returns the URI or HTML content of document.

Extensions must implement this method. This function will return a struct with a const char* and a bool. The value bool will true of the const char* points to a URI, false if the const char* points to HTML content. The pointer to document will be passed to parameter node.

Return

URI or HTML content of document

Parameters

  • node: pointer to a node in document tree

const char *(*get_brief)(const docview_extension_doc_tree_node *node)

Returns the brief of from document.

Extensions should implement this method. If an extension doesn’t implement this method, this member must be NULL. This will return the brief of the the document specified by parameter node. Return value should be in plain text (although any type of text is allowed). If not implemented, an empty string will be assumed.

Return

brief of from document

Parameters

  • node: pointer to a node in document tree

const char *(*get_details)(const docview_extension_doc_tree_node *node)

Returns the details of from document.

Extensions should implement this method. If an extension doesn’t implement this method, this member must be NULL. This will return the details for the document specified by parameter node. Return value should be in plain text (although any type of text is allowed). If not implemented, an empty string will be assumed.

Return

details of from document

Parameters

  • node: pointer to a node in document tree

const char *(*get_section)(const docview_extension_doc_tree_node *node, const char*)

Returns a section from document.

Extensions should implement this method. If an extension doesn’t implement this method, this member must be NULL. This will return a section from the document specified by parameter node. Return value should be in plain text (although any type of text is allowed). If not implemented, an empty string will be assumed.

Return

details of from document

Parameters

  • node: pointer to a node in document tree