Host Protocol Stack and Network Service API

Contents

1. 0. Requirements
2. 1. Mobility First API
   1. 1.1 Primitives
      1. 1.1.1 Open
      2. 1.1.2 Attach
      3. 1.1.3 Detach
      4. 1.1.4 Send
      5. 1.1.5 Recv
      6. 1.1.6 Close
   2. 1.2 Content Centric Operations
      1. 1.2.1 Get
      2. 1.2.2 Get_handle
      3. 1.2.3 Get_response
      4. 1.2.4 Post
      5. 1.2.5 Post_handle
      6. 1.2.6 Post_response
   3. 1.3 Service Centric Operations
      1. 1.3.1 Exec
      2. 1.3.2 Exec_handle
      3. 1.3.3 Exec_response
3. 2. Installation
   1. 2.1 Linux
   2. 2.2 Android
      1. 2.2.1 Manual installation
      2. 2.2.2 Automatic installation (not available yet)
4. 3. Running Mobility First protocol stack
   1. 3.1 Linux
   2. 3.2 Android
      1. 3.2.1 Manual
      2. 3.2.2 Automatic
5. 4. Performance
6. 5. Known Issues

0. Requirements

1. Mobility First API

In this section it will be described Mobility First's API. At the moment not all interfaces are implemented or works as listed; the API is at the moment under development so it will need some time before reaching a good level of stability. The description provided reflect what is the goal we are trying to achieve.
MFAPI is divided into three major groups that are differentiate the different patterns of possible communications between network entities. This groups are: primitives, content centric operations and service centric operations.

1.1 Primitives

The set of primitives has been intended to provide basic services to the applications that use them such as initiating a network session by stating the communication intent, ...

1.1.1 Open

Synopsis

open(scheme, profile-opts, [GUID-set]);

Description

The open function shall define the initialization of a communication session between the application layer and the underneath layers. On doing so the system is informed of the intent of the application and can choose the appropriate transportation service and initialize the needed resources.
Scheme is a descriptive element that inform the system about the intent of the application.
Profile-opts are additional parameters that can be provided to request additional services.
GUID-set is optional and represents the set of GUIDs that the application is willing of listening at. If no value is provided, the system should select a standard GUID identifier for the application.

Return Value

The function returns a value representing the created network endpoint. If the function has failed, this value should represent the incurred error.

1.1.2 Attach

Synopsis

attach(GUID-set);

Description

The attach function provides the functionalities to add additional GUIDs at the set originally identified during the open call.
GUID-set represents the set of GUIDs that the application wants to add at the set that it is listening at.

Return Value

The returned value shall inform the application of weather the API layer has successfully added the set of GUIDs or not.

1.1.3 Detach

Synopsis

detach(GUID-set);

Description

The detach function shall provide a way of removing GUIDs form the set originally identified during the open call.
GUID-set represents the set of GUIDs that the application wants to remove from the set that it is listening at.

Return Value

The returned value shall inform the application of weather the API layer has successfully removed the set of GUIDs or not.

1.1.4 Send

Synopsis

send(dst-GUID, message, [svc-opts]);

Description

The send operation shall send data to a destination GUID as messages with no size limits except for the ones defined by system resources. The way the message is delivered to the entity defined by the GUID is determined by the session characteristics defined during the open call and eventually by additional service options.
dst-GUID represents the destination GUID.
message is the data message to be sent.
svc-opts are additional service options used to determine how the message is delivered.

Return Value

The function shall return the number of bytes sent.

1.1.5 Recv

Synopsis

recv(src-GUID, buffer, [GUID-set]);

Description

The recv operation shall write into the buffer passed the oldest not read message received.
src-GUID is a variable that will be filled with the GUID of the entity that sent the message.
buffer is filled with the message that has been transmitted.
GUID-set is optional and can be used to limit the set of GUIDs to receive from. These GUIDs need to have been previously included in the set provided during the open call or after additional attach operations.

Return Value

Return Value

1.1.6 Close

Synopsis

close();

Description

The close function shall close the session initiated with an open call and clear the resources that were allocated.

Return Value

The returned value shall inform the application of weather the API layer has successfully closed the session or not.

1.2 Content Centric Operations

1.2.1 Get

1.2.2 Get_handle

1.2.3 Get_response

1.2.4 Post

1.2.5 Post_handle

1.2.6 Post_response

1.3 Service Centric Operations

1.3.1 Exec

1.3.2 Exec_handle

1.3.3 Exec_response

2. Installation

In this section is explained how to install the system in two different environments: Linux and Android.

2.1 Linux

Manual installation

• Compile:
  • Go to folder: mobilityfirst/trunk/code/prototype/client/api/
  • make
  • Go to folder: mobilityfirst/trunk/code/prototype/client/stack/Release/
  • make -f makefile-linux
• Install:
  • Place the generated libraries under /usr/libs/
  • Create the folder /data/mfdemo/
  • Copy the executable mfandroidstack into the folder /data/mfdemo/
  • Place the interfaces.xml and policy.xml (with the proper values) into /data/mfdemo/
  • Check that all permissions are correctly set to let the files to be read

2.2 Android

There are two options to install all the necessary libraries and binaries in android: manual compilation and installation or use the provided application.

2.2.1 Manual installation

• Dependencies:
  • Having command ndk-build (part of Android NDK) in your environment PATH
  • Root permissions for your Android device
  • Access to Mobility First repository
• Compile:
  • Go to folder: mobilityfirst/trunk/code/prototype/client/c_android/
  • ./c_android if compiling for Android 4.0+, ./c_android2 otherwise
  • All generated files are going to be placed under the mobilityfirst/trunk/code/prototype/client/c_android/bin/ folder
  • At ​THIS link are available all pre-compiled binaries for ARM devices, but there is no guarantee that they are the most updated version.
• Install:
  • Copy all libraries from the bin folder into /system/lib/ floder in your Android device (.so files)
  • Copy the executable mfandroidstack into the folder /system/bin/
  • Create the folder /data/mfdemo/ and the folder /sdcard/mfdemo/
  • Place the interfaces.xml and policy.xml (with the proper values) into /data/mfdemo/
  • Check that all permissions are correctly set to let the files to be read
  • Import the jmfapi.jar library in your Android application by placing it in the libs folder
  • If you are implementing applications for Android 4.0+ that use the jmfapi.jar library, remember to assign them the following permission in the manifest file: WRITE_EXTERNAL_STORAGE

2.2.2 Automatic installation (not available yet)

• Dependencies:
  • Root permissions for your Android device
• Install:
  • Install this application
  • Open it and click the install button
  • Download the jmfapi.jar library or compile it following the "manual installation" instructions
  • Import the jmfapi.jar library in your Android application by placing it in the libs folder

3. Running Mobility First protocol stack

3.1 Linux

• Go to folder /data/mfdemo/
• Execute the following command: ./mfandroidstack -d -I /data/mfdemo/interfaces.xml 11 /data/mfdemo/policy.xml > /data/mfdemo/mflog 2> /data/mfdemo/mferr

3.2 Android

3.2.1 Manual

• Open a shell in the device (adb shell)
• Execute the following command: su -c /system/bin/mfandroidstack -d -I /data/mfdemo/interfaces.xml 11 /data/mfdemo/policy.xml > /data/mfdemo/mflog 2> /data/mfdemo/mferr

3.2.2 Automatic

• Click the start button
• To stop press the stop button
• The application is available in ​THIS package, but there is no guarantee that they are the most updated version.

4. Performance

5. Known Issues

• Link layer block id issue on host stack restarts: The Hop link layer data transport uses a monotonously increasing and unique id to identify data blocks. If upstream node (R) has seen a block id before from a host (H, identified by MAC), it simple acknowledges that it has received (and forwarded) the block before and will not forward again. This enables robustness to any misunderstandings whether block was reliably delivered when acks are lost. However, if the protocol stack on host H were to be restarted for some reason it resets block ids to begin from 1 and results in data blocks sent subsequently to node R to be ignored if those ids were used before.
  • Potential fix(es): 1. Use content hash as block id, rather than sequence number. 2.) Modify router to consider repeated sequence number as new if time from prior receive has exceeded a threshold.
  • Workaround: For experiments, restart router nodes when host stack is restarted. Note that all routers need restart and not only first upstream node R since the same Hop protocol is implemented across routers and host stacks.
  • Status: No fix implemented yet.
• Impossibility of opening more than one socket per proces:
• Impossibility of handling more than one GUID per socket:
• Issue X: