c_gen/templates/README

Introduction
============

LOCI is the C language module of LOXI, the Logical OpenFlow Extensible
Interface. It provides a framework for managing OpenFlow objects in
an object oriented fashion.

All files in LOCI, even this README, are generated by LOXI. Please make
modifications to LOXI instead of to these files directly.

Compilation
===========

It's expected that users of LOCI will want to integrate it into their own build
system. As an example, here's a simple command line to create a shared library
on Linux:

    gcc -fPIC -shared -I inc src/*.c -o loci.so

LOCI has no dependencies beyond the C standard library.

Documentation
=============

A Doxygen configuration file is provided. Just run `doxygen` to generate HTML
documentation pages. Each OpenFlow object is linked to under the "Modules"
tab.

Usage
=====

Currently the best example code for using LOCI is the switchlight-core
repository.

Here's example code that creates a flow mod:

    /* Create the match */
    of_match_t match;
    memset(&match, 0, sizeof(match));
    match.fields.in_port = 1;
    OF_MATCH_MASK_IN_PORT_EXACT_SET(&match);
    match.fields.eth_type = 0x8000;
    OF_MATCH_MASK_ETH_TYPE_EXACT_SET(&match);

    /* Create a flow mod */
    of_flow_add_t *flow_add = of_flow_add_new(OF_VERSION_1_0);
    of_flow_add_idle_timeout_set(flow_add, 5);
    of_flow_add_cookie_set(flow_add, 42);
    of_flow_add_priority_set(flow_add, 10000);
    of_flow_add_buffer_id_set(flow_add, -1);
    if (of_flow_add_match_set(flow_add, &match)) {
        fprintf(stderr, "Failed to set the match field\n");
        abort();
    }

    /* Populate the action list */
    of_list_action_t actions;
    of_flow_add_actions_bind(flow_add, &actions);
    int i;
    for (i = 1; i <= 4; i++) {
        of_action_output_t action;
        of_action_output_init(&action, flow_add->version, -1, 1);
        of_list_action_append_bind(&actions, (of_action_t *)&action);
        of_action_output_port_set(&action, i);
    }

    /* Use the underlying buffer */
    void *buf = WBUF_BUF(OF_OBJECT_TO_WBUF(flow_add));
    uint16_t len = flow_add->length;
    /* ... */

    /* Free the flow mod */
    of_flow_add_delete(flow_add);