Application API

#############################################################################

Table of contents

#############################################################################

• 1. Introduction
• 2. API Walkthrough
  • 2.1 Server-side operations
  • 2.2 Client-side operations
• 3. API Specification
• 4. Running and configuring IRATI
  • 4.1 Loading the kernel modules
  • 4.2 The configuration files
  • 4.3 Running the IPC Manager Daemon
• 5. Tutorials
• 6. Overview of the software components

#############################################################################

1. Introduction

############################################################################# Since existing network applications are written using the socket API, it comes natural to design a C RINA API which closely resembles the socket API, provided that the differences in the naming and addressing scheme and the QoS support are taken into account. The socket API is currently defined by the POSIX.1-2008 standard; for this reason the API presented in this section will be referred to as a POSIX-like API for RINA. The advantages of a C POSIX-like API include the following:

• POSIX standards are universally accepted and widely known, so that it would be easy for developers to catch up with the RINA API and write applications.
• It would be easy to port existing network applications to RINA, starting from the definition of a simple mapping between socket API calls and RINA API calls.
• File descriptors are used as universal handlers to interact with the API; this makes it possible to reuse standard system calls (e.g. read, write, close, ...), and synchronisation mechanism (e.g. select, poll, ...).
• The C language is widely used for mission-critical network applications, and a C API can also be used directly by C++ programs.

This C POSIX-like API was originally designed for the rlite RINA implementation.

#############################################################################

2. API Walkthrough

############################################################################# A convenient way to introduce the API is to show how a simple application would use the client-side and server-side API calls. This also eases the comparison with sockets, where a similar walkthrough is often presented. Note that in this context the term client simply refers to the initiator of the flow allocation procedure, while the term server refers to the other peer. The discussion here, in other words, does not imply that the client/server paradigm must be applied; the walkthrough is more general, being valid also for other distributed application paradigms (e.g. peer-to-peer).

The workflow presented in this subsection, depicted in figure 1, refers to the case of blocking operation, that is the API calls may block waiting for asynchronous events; moreover, for the sake of exposition, we assume that the operations do not fail. Non-blocking operations and errors are however covered by the API specification (section 2.2) and the examples (section 2.4).

2.1 Server-side operations

############################################################################# The first operation needed by the server, (1) in figure 1, is rina-open, which takes no arguments and returns a listening file descriptor (an integer, as usual) to be used for subsequent server-side