# Basic Interface

Abstract

Using the basic interface

### Overview

The libfo basic interface defined in <file>fo-lifo-basic.h</file> provides a high-level interface to the formatter while hiding the use of GObjects.

### Lifecycle

The lifecycle is init–format–shutdown.

#### Initialise

There are two ways to initialise the basic formatter. The first way leaves memory allocation under the control of the formatter. The second way allows the calling program to provide the functions to be used for allocating, reallocating, and freeing memory.

    gboolean         fo_libfo_init (void);

    typedef  gpointer (*FoMalloc)      (gsize    n_bytes);
    typedef  gpointer (*FoRealloc)     (gpointer mem,
    				    gsize    n_bytes);
    typedef  void     (*FoFree)        (gpointer mem);

    gboolean         fo_libfo_init2 (FoMalloc  fo_malloc,
    				 FoRealloc fo_realloc,
    				 FoFree    fo_free);

In both cases, the return value is an indication of whether or not the formatter was successfully initialised. The functions return `TRUE` on success, and `FALSE` on failure.

#### Format

There is one function for performing the formatting. The inputs are:

libfo_context | Information controlling the formatting. See below.
xml | The filename of the input XML file.
xslt | The filename of the stylesheet file to apply.
out | The filename of the output PDF or PostScript file.
error | Indication of any error that occured.

The return value is an indication of the success or failure of the formatting. The function returns `TRUE` on success, and `FALSE` on failure. When the return value is `FALSE`, the `error` value contains information about any error that occurred.

    gboolean         fo_libfo_format (FoLibfoContext *libfo_context,
    				  const gchar    *xml,
    				  const gchar    *xslt,
    				  const gchar    *out,
    				  GError        **error);

#### Shutdown

There is one function for shutting down the formatter.

    gboolean         fo_libfo_shutdown (void);

The return value is an indication of the success or failure of the formatting. The function returns `TRUE` on success, and `FALSE` on failure. However, if the shutdown does fail, there isn't a whole lot that you can then do.

### `FoLibfoContext`

You can use a `FoLibfoContext` to control aspects of the formatting, including:

- Output format (currently ignored).

- Font embedding (currently ignored).

- Validation of input XML document.

- Use or non-use of SGML catalogs when parsing inputs.

- Warning mode.

- Debug mode.