Documentation API

From RLIB

Jump to: navigation, search

RLIB Supports C, C++, PHP, PERL, Python, Java, and C#

The API is 99% the same from language to language, except of course the syntax of the language.

Important differences and examples of the language bindings are in the following sub sections:

C | PHP | PERL | PYTHON | JAVA | C# |

Contents

Initialization, cleanup

rlib * rlib_init();

    Must be called before any other RLIB functions.
    RETURNS: A pointer to an initialized RLIB structure

int rlib_free(rlib *r);

    This is the cleanup function for RLIB.
    It must be called on the pointer returned by rlib_init()
    after all work has been finished with the report, i.e. it was generated and saved.
    RETURNS: 0

char *rlib_version(void)

    This returns the RLIB version in use.
    RETURNS: Pointer to initialized RLIB Structure

Datasource definition

gint rlib_add_datasource(rlib *r, const gchar *input_name, struct input_filter *input)

    Adds a custom datasource using the input_filter structure. This is defined in the <rlib_input.h> C API header:
    
    typedef struct input_filter input_filter;
    struct input_filter {
            gpointer private;
            struct input_info info;
            gint (*input_close)(gpointer);
            gpointer (*new_result_from_query)(gpointer, gchar *);
            gint (*free)(gpointer);
            gint (*first)(gpointer, gpointer);
            gint (*next)(gpointer, gpointer);
            gint (*previous)(gpointer, gpointer);
            gint (*last)(gpointer, gpointer);
            gint (*isdone)(gpointer, gpointer);
            const gchar * (*get_error)(gpointer);
            gchar * (*get_field_value_as_string)(gpointer, gpointer, gpointer);
            gpointer (*resolve_field_pointer)(gpointer, gpointer, gchar *);
            void (*free_result)(gpointer, gpointer);        
            gint (*set_encoding)(gpointer);
    };
    
    This is used to create e.g. add_datasource_array() call in Python and rlib_add_datasource_array() in PHP.

int rlib_add_datasource_mysql(rlib *r, char *input_name, char *database_host, char *database_user, char *database_password, char *database_database)

    Adds a MySQL datasource to the report.
    input_name contains the name that can be used later when adding queries to the report.
    database_host, database_user, database_password and database_database parameters
    control the connection to the datasource.
    RETURNS: 0 for success, -1 for failure

int rlib_add_datasource_postgre(rlib *r, char *input_name, char *conn)

    Adds a PostgreSQL datasource to the report.
    input_name contains the name that can be used later when adding queries to the report.
    conn contains the PostgreSQL specific connection string controlling the connection to the datasource.
    RETURNS: 0 for success, -1 for failure

int rlib_add_datasource_odbc(rlib *r, char *input_name, char *source, char *user, char *password)

    Adds an ODBC datasource to the report.
    input_name contains the name that can be used later when adding queries to the report.
    source is the data source name (DSN) defined in the ODBC settings
    user and password are use the provide the authentication information for the connection.
    RETURNS: 0 for success, -1 for failure

int rlib_add_datasource_xml(rlib *r, char *input_name)

    Adds an XML datasource to the report.
    input_name contains the name that can be used later when adding queries to the report.
    RETURNS: 0

int rlib_add_datasource_csv(rlib *r, char *input_name)

    Adds an XML datasource to the report.
    input_name contains the name that can be used later when adding queries to the report.
    RETURNS: 0

Query definition

int rlib_add_query_as(rlib *r, char *input_source, char *sql, char *name)

    Adds a query to the report.
    input_source is the name that was given as input_name in an rlib_add_datasource_*() call.
    sql contains the SQL query if the datasource is an actual SQL source (MySQL, PostgreSQL or ODBC) or
              contains a filename pointing to a CSV or XML file for their respective datasource.
              The sql string's duplicated copy is stored in the *r structure, so it can be passed
              as a static string or it can be freed by the caller.
    name is the query name that can be used to refer to fields of the query in the report XML.
    RETURNS: the number of defined queries in the report (a positive number) on success,
             -1 on failure (input_source is not defined as a datasource yet)

int rlib_add_query_pointer_as(rlib *r, char *input_source, char *sql, char *name)

    Adds a query to the report.
    input_source is the name that was given as input_name in an rlib_add_datasource_*() call.
    sql contains the SQL query if the datasource is an actual SQL source (MySQL, PostgreSQL or ODBC) or
              contains a filename pointing to a CSV or XML file for their respective datasource.
              The sql pointer is stored as is in the *r structure, so it has to be an allocated string
              that must not be freed by the caller.
    name is the query name that can be used to refer to fields of the query in the report XML.
    RETURNS: the number of defined queries in the report (a positive number) on success,
             -1 on failure (input_source is not defined as a datasource yet)

Report XML definition

int rlib_add_report(rlib *r, char *name)

    Adds a report XML file ("report part") to the report that will be used to layout the output report.
    name contains the XML filename.
    RETURNS: the number of defined XML reports on success (a positive number), or
             -1 on failure, the number of defined report parts would exceed RLIB_MAXIMUM_REPORTS (by default 5)

int rlib_add_report_from_buffer(rlib *r, char *buffer)

    Adds a report XML (important: zero-terminated string) from a memory buffer to the report
    that will be used to layout the output report.
    buffer is the pointer to the memory buffer that contains the XML content.
    RETURNS: the number of defined XML reports on success (a positive number), or
             -1 on failure, the number of defined report parts would exceed RLIB_MAXIMUM_REPORTS (by default 5)

Output control

int rlib_set_output_format(rlib *r, int format)

    Sets the report output format using the format's number.
    format can be:
         RLIB_FORMAT_PDF  (1)
         RLIB_FORMAT_HTML (2)
         RLIB_FORMAT_TXT  (3)
         RLIB_FORMAT_CSV  (4)
    RETURNS: 0

int rlib_set_output_format_from_text(rlib *r, char *name)

    Sets the report output format using the format name.
    name can be:
         'PDF'
         'HTML'
         'TXT'
         'CSV'
         Any unmatching text means 'TXT'.
    RETURNS: 0

void rlib_set_output_parameter(rlib *r, char *parameter, char *value)

    Adds a new output parameter with its value. The output parameters can be global or specific
    to the chosen output format set by rlib_set_output_format() or rlib_set_output_format_from_text().
    The output parameters currently known by RLIB are:

Global output parameters

    "debugging"
      If "yes", turns on HTML debugging output.
    "do_breaks"
      Values: "yes" / "no". Controls whether to add breaks in the report.
      Default FALSE for CSV, TRUE for all other output formats.

Output format specific output parameters

    CSV-specific settings:
    
    "csv_file_name"
      Sets the filename for rlib_get_content_type_as_text(). By default it's "report.csv".
    "only_quote_strings"
      Only strings in the CSV file will be quoted.
      The value in not important, only the presence of the parameter.
    "no_quotes"
      No quotes at all in the CSV output.
      The value in not important, only the presence of the parameter.
    "new_line_on_end_of_line"
      ???
      The value in not important, only the presence of the parameter.
    
    HTML-specific settings:
    
    "trim_links"
      ???
    "suppress_head"
      If set, it suppresses the HTML <HEAD> (and other) sections, only the actual <BODY> is output.
      The value in not important, only the presence of the parameter.
    "meta"
      A custom <META> tag may be provided in the <HEAD> section.
    "html_image_directory"
      It specifies the image directory where graphs created on the fly.
    
    PDF-specific settings:
    
    "pdf_fontdir1"
    "pdf_fontdir2"
    "pdf_encoding"
    "pdf_fontname"
      Font overrides for the PDF output.
    "compress"
      The contents of the PDF pages will be compressed resulting in a smaller PDF file.

int rlib_set_locale(rlib *r, char *locale)

    Sets the locale for the output. This setting enables locale-specific output during conversions, like
    decimal comma instead of dot, thousand separators, etc.
    RETURNS: TRUE

void rlib_set_output_encoding(rlib *r, const char *encoding)

    Sets the output encoding. The strings in the output will be encoded according to the given charset.

int rlib_set_datasource_encoding(rlib *r, char *input_name, char *encoding)

    Sets the encoding for the given datasource. The strings from the datasource assumed to come encoded
    according to the given charset.
    RETURNS: 0 on success, -1 on error (no datasource found with a name given in input_name)

int rlib_execute(rlib *r)

    Executes the report: connects to the defined database(s), runs the query or queries and layouts
    according to the XML description.
    RETURNS: 0 on success, -1 on failure

char * rlib_get_content_type_as_text(rlib *r)

    RETURNS: the HTML 'Content-Type: ...' string appropriate for output format
             set by rlib_set_output_format() if the report was already executed.
             'UNKNOWN' if the report was not yet executed.

int rlib_spool(rlib *r)

    Spools the result to the standard output of the application.
    The report must have already been executed.
    RETURNS: 0 on success, -1 on error (report has not been executed yet)

char *rlib_get_output(rlib *r)

    RETURNS: a pointer to the memory buffer containing the executed report content.
             NULL if the report was not yet executed.

int rlib_get_output_length(rlib *r)

    RETURNS: the number of bytes in the memory buffer containing the executed report content.
             0 if the report was not yet executed.

Report control

gboolean rlib_add_function(rlib *r, gchar *function_name, gboolean (*function)(rlib *, struct rlib_pcode *code, struct rlib_value_stack *, struct rlib_value *this_field_value, gpointer user_data), gpointer user_data)

    Adds a custom function to the functions known by RLIB. See the RLIB libsrc/pcode_op_functions.c for examples of function implementations.
    r is the report to which it adds the new function.
    function_name is the function name which can be used later as function_name(args...) in the report XML.
    function is the function defined in your C code, its header is mandatory:
        gboolean function(rlib *, struct rlib_pcode *code,  struct rlib_value_stack *, struct rlib_value *this_field_value, gpointer user_data)
    user_data is the extra data passed each time function is called.

int rlib_signal_connect(rlib *r, int signal_number, int (*signal_function)(rlib *, void *), void * data)

    Adds a callback function using the signal ID to a certain event (signal) that gets called during report execution.
    signal_number can be set to the following values:
      RLIB_SIGNAL_ROW_CHANGE          (0)
      RLIB_SIGNAL_REPORT_START        (1)
      RLIB_SIGNAL_REPORT_DONE         (2)
      RLIB_SIGNAL_REPORT_ITERATION    (3)
      RLIB_SIGNAL_PART_ITERATION      (4)
      RLIB_SIGNAL_PRECALCULATION_DONE (5)
    RETURNS: TRUE

int rlib_signal_connect_string(rlib *r, char *signal_name, int (*signal_function)(rlib *, void *), void * data)

    Adds a callback function using the signal name to a certain event (signal) that gets called during report execution.
    signal_name can contain the following strings:
      "row_change"
      "report_done"
      "report_start"
      "report_iteration"
      "part_iteration"
      "precalculation_done"
    RETURNS: TRUE on success, FALSE on error (incorrect signal name)

int rlib_add_parameter(rlib *r, const char *name, const char *value)

    Adds a parameter to the report with an initial value.
    The parameter can be referenced in the report XML description as "m.parameter_name".
    Subsequent calls with the same parameter name replaces the value for the parameter.
    RETURNS: TRUE

int rlib_add_resultset_follower_n_to_1(rlib *r, char *leader, char *leader_field, char *follower, char *follower_field)

    For reports containing multiple queries, they can be concatenated together using query names and fields.
    RETURNS: 0 on success, -1 on failure (no query found by names of leader or follower)

int rlib_add_resultset_follower(rlib *r, char *leader, char *follower)

    For reports containing multiple queries, they can be concatenated together using query names only.
    RETURNS: 0 on success, -1 on failure (no query found by names of leader or follower)

int rlib_query_refresh(rlib *r)

    Restarts the report's queries.

int rlib_graph_add_bg_region(rlib *r, char *graph_name, char *region_label, char *color, float start, float end)

    Add a region of color with a label to a graph.
    Useful when the X axis is time and you want to indicate an event occured over that time.
    RETURNS: TRUE

int rlib_graph_clear_bg_region(rlib *r, char *graph_name)

    NOP. (Might be a deprecated API call?)
    RETURNS: TRUE

int rlib_graph_set_x_minor_tick(rlib *r, char *graph_name, char *x_value)

    Set a x value on a graph as a minor tick.
    RETURNS: TRUE

int rlib_graph_set_x_minor_tick_by_location(rlib *r, char *graph_name, int location)

    Set a x value on a graph as a minor tick. Location starts at 0.
    RETURNS: TRUE
Personal tools