Extending Ioto with Custom Code

Ioto has an extension API that you can use to handle requests, create custom responses and tailor the operation of the Ioto device agent. To use this API, you relink Ioto and integrate your custom code.

This post and is the second of a series on the embedded web server inside Ioto. This post discusses how to extend Ioto with your own custom code.

The posts in the series are:

• Using the Ioto Embedded Web Server
• Extending Ioto with Custom Code
• Using Ioto to Generate Dynamic Responses
• Streaming Responses
• Request Routing
• User Authentication
• Using the Ioto Database
• Managing JSON data with Ioto
• Using the Kickstart Sample Device Manager

Embedding options

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. Use the Ioto main() and provide your “start” and “stop” functions.
2. Use your own main() and link with the Ioto library.

Using the Ioto Main

You can add custom code to Ioto by providing an ioStart function that references your code. When compiled and linked with the Ioto library, your code will be invoked at startup before Ioto beings serving requests.

Your ioStart function can reference any custom code or libraries you desire and can invoke Ioto APIs to change configuration, register action routines, connect to other services, and install various Ioto API hooks.

This example below provides a custom ioStart function that defines a web server action routine. This action will be invoked when the /action/hello URL is requested via the Ioto embedded web server.

#include "ioto.h"

static void hello(Web *web)
{
    printf("In my hello\n");
    webWrite(web, "Hello World\n", -1);
    webFinalize(web);
}

int ioStart(void)
{
    printf("In my start\n");
    webAddAction(ioto->webHost, "/action/hello", hello);
    return 0;
}

At startup, the ioStart function will be invoked and will install the hello action routine to respond to requests to the “/action/hello” URL.

Relinking Ioto

Compile this code in a file custom.c and put the object into a static library.

cc -I build/*dev/inc -c custom.c
ar -cr libcustom.a custom.o

Then rebuild Ioto to include your library and source.

make LDFLAGS="-L. -lcustom" SHOW=1 clean build

The ioStart function will be invoked by Ioto at initialization time and that will register the hello action.

To test, run Ioto.

$ ioto -v 

And then from from your browser or the curl utility, fetch the URL:

http://localhost/api/public/hello

You can also provide your own main() and link with the Ioto library. Read more about embedded in the Embedding the Ioto Agent.

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() that references your code.
3. Invoke ioInit and ioTerm from your main() to initialize and terminate the Ioto runtime.
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().

#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:

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

The next post will cover Generating Dynamic Responses.

Want More Now?

To learn more about EmbedThis Ioto, please read:

• Ioto Web Site
• Ioto Documentation
• Ioto Agent Download
• Builder Documentation
• Embedthis Web Site