Skip to content

Embedding the Ioto Agent

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

The Ioto agent can be customized two ways:

  1. Use the Ioto main() and provide "start" and "stop" functions that link to your code.
  2. Use your own main() and code and link with the Ioto library.

Use the Ioto Main

The first way to integrate Ioto is to use the Ioto main program and provide your own ioStart and ioStop functions. These functions are invoked by Ioto during startup and shutdown. The default versions of these functions are provided by the Ioto library, however if you provide your alternates and link them before libioto.a, your versions will be used instead.

To build with your start/stop functions you need to do the following things:

  1. Add #include "ioto.h" to the relevant source files.
  2. Provide an ioStart function to initialize your code and ioStop function to terminate your code. Reference your required code from these functions.
  3. Add the libioto.a library to the build/link target in your Makefile.
  4. Build your application.
  5. Create or edit the Ioto ioto.json5 and other Ioto config files to suit your needs.

Embedding API

The following code demonstrates the Ioto embedding API.

1
2
3
4
5
6
#include "ioto.h"

PUBLIC void ioStart(void *arg)
{
    rInfo("sample", "Hello World\n");
}

If this source is contained in a file called custom.c, you can build this sample and link with the Ioto library:

1
cc -I build/*dev/inc -o server custom.c -lioto

You can alternatively compile your code and put the object into a static library then rebuild Ioto using the standard Ioto Makefile. For example:

1
2
3
cc -I build/*dev/inc -c custom.c
ar -cr libcustom.a custom.o
make LDFLAGS="-L. -lcustom" SHOW=1 clean build

Provide your own main()

The second way to integrate your code with 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 Ioto command line options that require full control over the main() program.

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

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

  1. Add #include "ioto.h" to the relevant source files.
  2. Provide a main().
  3. Invoke ioInit and ioTerm from your main().
  4. Build your app and references the libioto.a library.
  5. Create or edit the Ioto config/ioto.json5 configuration file and other Ioto config files to suit your needs.

The following code demonstrates providing your own main().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
#include "ioto.h"

static void start(void *arg);

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

    //  Service requests until told to stop
    rServiceEvents();
    ioTerm();
    rTerm();
    return 0;
}

static void start(void *arg)
{
    ioInit(0);
    rInfo("sample", "Hello World\n");
    //  Your code here
}

If this source is contained in a file called custom.c, you can build this sample and link with the Ioto library:

1
cc -o server -I build/*dev/inc custom.c -lioto

Samples

The link-agent-main sample demonstrates linking with the Ioto library. The own-main sample demonstrates linking with your own main.

More Details

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