Skip to content

Embedding the Ioto Agent

The Ioto agent is provided as a stand-alone program and as a library that can be included with your programs for a more customized experience.

The Ioto agent can be customized two ways:

  1. Link with the Ioto library and use the Ioto main() and provide your "start" and "stop" functions.
  2. Link with the Ioto library and provide your own main program.

The second way to integrate Ioto is to link with the Ioto library and provide your own start and stop functions. In this manner, your app becomes empowered with MQTT, HTTP and AWS integration services.

The Ioto Makefile builds a library called libioto.a. Ioto can be customized by providing iaStart and iaStop functions. These functions are invoked by Ioto during startup and shutdown.

The default versions of these functions are provided by the library via the start.c and stop.c files that are linked into the libioto.a library. However if you provide your alternates and link against them before libioto.a, your versions will be used instead.

The embedding API requires only a few lines of code. See the Link Library Sample for an example.

To include the Ioto library in your program you need to do the following things:

  1. Add #include "ioto/agent.h" to the relevant source files.
  2. Add the libioto.a library to your Makefile.
  3. Provide an iaStart function to initialize your code and iaStop function to terminate your code.
  4. Build your application.
  5. Create or edit the Ioto config.json and other Ioto config files to suit your needs.

Embedding API

The following code demonstrates the Ioto embedding API. This will create the Ioto services based on the config.json configuration file.

1
2
3
4
5
6
7
8
9
#include "ioto/agent.h"

PUBLIC void iaStart(void *arg)
{
    rinfo("sample", "Hello World\n");

    //  Instruct ioto to exit the sample
    rStop();
}

To build this sample and link with the Ioto library:

cc -o server server.c -lioto

Provide your own main()

The last way to integrate Ioto is to create your own main program and link with the Ioto library.

This method is desirable if you have more extensive customizations or need to parse custom command line options.

The Ioto libioto.a library also includes a default main() program. If you provide your own main() and link with libioto.a, then your main will be used instead.

See the Link Main Sample for an example.

To build with your own main, you need to do the following things:

  1. Add *#include "ioto/agent.h" to the relevant source files.
  2. Add the libioto.a library to your Makefile.
  3. Provide a main().
  4. Invoke ioInit and ioTerm.
  5. Build your application.
  6. Create or edit the Ioto config.json and other Ioto config files to suit your needs.

The following code demonstrates providing your own main().

#include "ioto/agent.h"
static void start(void *arg);

int main(int argc, char** argv)
{
    rInit((RFiberProc) start, 0, 0);

    //  Block until rStop()
    rServiceEvents();
    ioTerm();
    rTerm();
    return 0;
}

static void start(void *arg)
{
    ioInit(0);
    rinfo("sample", "Hello World\n");
    //  Exit the sample
    rStop();
}

To build this sample and link with the Ioto library:

cc -o server server.c -lioto

Samples

The Link Library Ioto sample demonstrates linking with the Ioto library. The Link Main Ioto sample demonstrates linking with your own main.

More Details

For more details about the embedding API, please consult the Ioto APIs.