XSocket API Documentation

XSocket API

This document describes the eXpressive Internet Architecture (XIA) network socket user interface.

Socket Layer Functions

For the most part, the Xsocket APIs use the same parameters as their Berkley socket counterparts. The main difference is that XIA has introduced a new address family (AF_INET) and the addresses passed between functions use a new sockaddr type (sockaddr_x). This documentation describes the APIs and the differences between XIA and Berkley sockets. The man pages for the Berkley calls can be referred to more more detailed information on the function calls.

XIA Function List

• Xaccept() - accept connections
• Xaccept4() - accept connections
• Xbind() - bind a socket to a DAG
• Xclose() - close the Xsocket
• Xconnect() - connect to a remote DAG
• XcreateFID() - create and register a cryptographic FID
• Xfcntl() - manipulate a socket
• Xfork() - create a child process
• Xfreeaddrinfo() - free memory returned by Xgetaddrinfo()
• Xfreeifaddrs() - free list of network addresses
• Xlisten() - listen for connections
• Xgai_strerror() - Xgetaddrinfo() error message string
• Xgetaddrinfo() - look up an address
• XgetDAGbyName() - look up an address
• Xgethostname() - get the XIA hostname
• Xgetifaddrs() - get list of network interfaces
• XgetNamebyDAG() - reverse address lookup
• Xgetpeername() - get address of connected socket
• Xgetsockname() - get address of my socket
• Xgetsockopt() - get socket options
• XmakeNewSID() - create a crypotgraphic SID & keypair
• Xnotify() - receive notification of interface changes
• Xpoll() - asyncronous I/O
• XreadLocalHostAddr() - look up the AD and HID of the local host
• Xrecv() - receive data
• Xrecvfrom() - receive datagram data
• Xrecvmsg() - receive datagram message
• XregisterName() - register our service/host name with the nameserver
• XremoveFID() - delete FID and associated keypair
• XremoveSID() - delete SID & associated keypair
• XrootDir() - get the path to the xia directory tree
• Xselect() - asyncronous I/O
• Xsend() - send data
• Xsendmsg() - send datagram message
• Xsendto() - send datagram data
• Xsetsockopt() - set socket options
• Xsocket() - create an XIA socket
• xia_ntop() - convert binary address to a string
• xia_pton() - convert a string to binary address

Content (Chunk) Oriented Functions

• XbufAdd() - append data to a buffer
• XbufFree() - free a buffer
• XbufInit() - initialize a buffer
• XbufPut() - load a buffer into the cache
• XcacheHandleDestroy() - delete handle to a cache context
• XcacheHandleInit() - initialize a cache context handle
• XcacheHandleSetTtl() - set default lifetime
• XevictChunk() - remove a chunk from the cache
• XfetchChunk() - fetch a chunk form a remote cache
• XputBuffer() - put a buffer into the cache
• XputChunk() - put a chunk into the cache
• XputFile() - put a file into the cache
• XputMetaChunk() - put a descriptive chunk into the cache

DAG Manipulation Overview

In XIA, addresses are represented as directed acyclic graphs (DAGs). The XIA socket API manipulates DAGs as strings in a particular format; creating and working with DAGs in this string format can be tedious. This library provides an object-oriented API (in C++ and Python) for creating and manipulating DAGs.

DAGs are managed using 2 C++ classes:

• Node - contains methods for managing a single XID
• Graph - contains methods for manipulating DAGs

Creating a DAG

Here we describe building a DAG from the ground up. Most simple DAGs can be seen one or more possible paths for reaching the final intent; that is, most DAGs you work with will consist of and handful of paths from source to sink. Consider this simple example: we are constructing a DAG for retrieving a piece of content with ID "CID". We want to make a DAG that offers the network three possible paths to the content, each more specific than the last:

1. SRC -> CID
2. SRC -> AD -> CID
3. SRC -> AD -> HID -> CID

In the subsections that follow, we show how to construct a DAG for each of these paths and then how to combine those three DAGs into a single DAG, where paths 2 and 3 are fallbacks.

A DAG is represented by a Graph object in our library. Graphs are composed of Node objects, so we begin by instantiating the nodes we'll need:

C++

Node n_src;
Node n_ad(Node::XID_TYPE_AD, "0606060606060606060606060606060606060606");
Node n_hid(Node::XID_TYPE_HID, "0101010101010101010101010101010101010101");
Node n_cid(Node::XID_TYPE_CID, "0202020202020202020202020202020202020202");

Python

n_src = Node()
n_ad = Node(Node.XID_TYPE_AD, "0606060606060606060606060606060606060606")
n_hid = Node(Node.XID_TYPE_HID, "0101010101010101010101010101010101010101")
n_cid = Node(Node.XID_TYPE_CID, "0202020202020202020202020202020202020202")

Making a Path

The simplest way to combine Nodes to make a Graph is to append them using the * operator:

C++

// Path directly to n_cid
// n_src -> n_cid
Graph g0 = n_src * n_cid;

// Path to n_cid through n_hid
// n_src -> n_hid -> n_cid
Graph g1 = n_src * n_ad * n_cid;

// Path to n_cid through n_ad then n_hid
// n_src -> n_ad -> n_hid -> n_cid
Graph g2 = n_src * n_ad * n_hid * n_cid;

Python

# Path directly to n_cid
# n_src -> n_cid
g0 = n_src * n_cid

# Path to n_cid through n_hid
# n_src -> n_hid -> n_cid
g1 = n_src * n_hid * n_cid

# Path to n_cid through n_ad then n_hid
# n_src -> n_ad -> n_hid -> n_cid
g2 = n_src * n_ad * n_hid * n_cid

Combining Paths

Paths can be combined into a single DAG using the + operator. The easiest way to make a DAG with a fallback route from one node to another is to combine paths that share the same source and sink; in our case, we are combining three paths with source node n_src and sink node n_cid:

C++

// Combine the above three paths into a single DAG;
// g1 and g2 become fallback paths from n_src to n_cid

Graph g3 = g0 + g1 + g2;

Python

# Combine the above three paths into a single DAG;
# g1 and g2 become fallback paths from n_src to n_cid

g3 = g0 + g1 + g2

 

 

Converting to a DAG string

To use a DAG constructed with this library in an XSocket API call, use the Graph::dag_string() method:

C++

// Get a DAG string version of the graph that could be used in an
// XSocket API call

const char* dag_string =  g3.dag_string().c_str();

Python

# Get a DAG string version of the graph that could be used in an
# XSocket API call

dag_string = g3.dag_string()

In this example, dag_string will have the value:

DAG 2 0 -
AD:0606060606060606060606060606060606060606 2 1 -
HID:0101010101010101010101010101010101010101 2 -
CID:0202020202020202020202020202020202020202

 

 

Converting from a DAG string

At times, you may want to create a Graph object from a DAG string you get from an XSocket API call (like XrecvFrom()) to make it easier to manipulate. This is easy to do, as the Graph class has a constructor that takes in a DAG string:

C++

// Create a DAG from a string (which we might have gotten from an Xsocket
// API call like XrecvFrom)

Graph g4 = Graph(dag_string);

Python

# Create a DAG from a string (which we might have gotten from an Xsocket
# API call like XrecvFrom)

g4 = Graph(dag_string)

 

 

Visualizing a DAG

It is not always easy to tell if the DAG you created is really what you wanted; inspecting the DAG string to make sure there are edges in the right places can be tedious. To help with this, we created a web-based tool for displaying DAGs. Simply paste the DAG string (like the one we obtained