Skip to content

Application API

Jump to bottom Edit New page
Eduard Grasa edited this page Feb 20, 2017 · 37 revisions

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

Table of contents

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

    1. Introduction
    1. API Walkthrough
    • 2.1 Server-side operations
    • 2.2 Client-side operations
    1. API Specification
    1. Running and configuring IRATI
    • 4.1 Loading the kernel modules
    • 4.2 The configuration files
    • 4.3 Running the IPC Manager Daemon
    1. Tutorials
    1. 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).

dd

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 calls. This file descriptor is the handler for an instance of a RINA control device which acts as a receiver for incoming flow allocation requests.

At (2), the server calls rina-register to register a name with the RINA control device, specifying the associated listening file descriptor (lfd), the name of the DIF to register to (dif) and the name to be registered (appl). The DIF argument is optional and advisory: the API implementation may choose to ignore it, and use some namespace management strategy to decide into which DIF the name should be registered.

After a successful registration, the server can receive flow allocation requests, by calling rina-flow-accept on the listening file descriptor (3). Since the listening file descriptor was not put in non-blocking mode, this call will block until a flow request arrives. When this happens, the function returns a new file descriptor (cfd), the name of the remote application (src) and the QoS granted to the flow. The returned file descriptor is an handler for an instance of a RINA I/O device, to be used for data I/O.

At this point (4), the flow allocation is complete, and the server can exchange SDUs with the client, using the write and read blocking calls or working in non-blocking mode (possibly mutliplexing with other I/O devices, sockets, etc.) by means of poll or select. This I/O phase is completely analogous to the I/O exchange that happens with TCP or UDP sockets, only the QoS may be different.

Once the I/O session ends, the server can close the flow, triggering flow deallocation, using the close system call (5). The server can then decide whether to terminate or accept another flow allocation request (3).

2.2 Client-side operations

############################################################################# Client operation is straightforward; the client calls rina-flow-alloc (1) to issue a flow allocation request, passing as arguments the name of the DIF that is asked to support the flow (dif), the name of the client (src, i.e. the source application name), the name of the destination application (dst, i.e. the server name) and the required QoS parameters for the flow (qos). The call will block until the flow allocation completes successfully, returning an file descriptor (fd) to be used for data I/O.

At this point the client can exchange SDUs with the server (2), using the I/O file descriptor either in blocking or not blocking mode, similarly to what is possible to do with sockets. When the I/O session terminates, the client can deallocate the flow with the close system call.

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

3. API Specification

############################################################################# In the following, the API calls are listed and documented in depth. Some general considerations:

  • Names (e.g. for applications and DIFs) are specified using C strings. Application names are composed of four components: process name, process instance, entity name and entity instance. Only process name is mandatory. The API mandates a standard separator to allow application developers to provide these 4 pieces of information using a single string. This separator is the '|' character, which cannot be used as part of the process name, instance, entity name or instance. Some examples of valid app names:
    • traffic.generator
    • traffic.generator|23
    • traffic.generator||perf
    • traffic.generator|23|perf
    • traffic.generator|23|perf|12
Add a custom footer
Clone this wiki locally