Writing XIA Applications

Table of Contents XIA Socket API API Documentation Example Applications Coding Examples Working With DAGs RE Format DAG Format URL Format Annotated Examples

XIA Socket API

Similarities To The Standard Socket Library

• The Xsocket API was designed to be as similar as possible to the standard socket library to make porting applications easier. Parameter lists are in almost all instances identical to the corresponding Berkley socket API.
• XIA supports socket of type 'SOCK_STREAM', 'SOCK_DGRAM', and 'SOCK_RAW'.

Differences From Berkley Sockets

• API calls are prefixed with an X (Xbind, Xpoll, etc...)
• The address family is AF_XIA instead of AF_INET
• XIA does not have IP addresses or ports. It uses DAGs in their place
• XIA uses a sockaddr_x structure instead of sockaddr_in to hold addresses
• XIA provides additional APIs for content management and DAG manipulation

API Documentation

• Xsockets API
• Xcache API
• DAG Library

Example Applications

• Sample Applications
• System Applications

Coding Examples

TODO: DO we need to keep these around?

• C Example
• Python Example

Working With DAGs

Several APIs are provided for working with DAGs

• Xgetaddrinfo() is used to look up DAGs in the name server similar to how standard DNS works. It can also be used to create local DAGs that can be used to bind to sockets.
• inet_ntop() is used to convert DAGs contained in a sockaddr_x structure into a printable sting in the DAG format.
• inet pton() is used to convert strings in the DAG, RE, or URL format into a sockaddr_x.
• The DAG library
  • The Node class is used to manage individual XIDs that make up the nodes in a Graph
  • The Graph class is used to manage DAGs.

XIA uses Directed Acuclic Graphs (DAGs) as network addresses.

Sometimes it's helpful to be able to see a visual representation of a DAG; to this end, we've created a DAG visualization tool.

RE Format

The RE format is simple and relatively easy to use but cannot represent all DAGs. An RE string consists of the characters "RE " followed by a chain of XIDs, each of which can optionally have a fallback path from the previous node in the chain to itself. Nodes are separated by spaces and parens are used to mark fallback paths. The "start" node is implicit and does not appear in the string. For example:

RE AD:1000000000000000000000000000000000000000 HID:0000000000000000000000000000000000000000 SID:1110000000000000000000000000000000001113
RE ( AD:1000000000000000000000000000000000000000 HID:0000000000000000000000000000000000000000 ) SID:1110000000000000000000000000000000001113

TODO: show example pictures

DAG Format

The DAG format is capable of encoding arbitrary graphs but is more tedious to construct manually. A DAG string is a list of XIDs and their outgoing edges separated by the '-' character; by convention, we use "- \n" as the separator to make DAG strings easier to read when printed. Nodes are implicitly numbered starting from 0. This index is used by other nodes to denote an outgoing edge to a node. A DAG string begins with the characters "DAG " and is followed by the start node's outgoing edges (separated by spaces). This is followed by the list of XIDs and their outgoing edges.

An example may help clarify:

DAG 2 0 - 
AD:4349445f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f 2 1 - 
HID:4849445f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f 2 - 
SID:534944305f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f

In this example, the nodes are implicitly ordered:

0. AD:4349445f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f
1. HID:4849445f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f
2. SID:534944305f5f5f5f5f5f5f5f5f5f5f5f5f5f5f5f

The numbers following each XID indicate to which other nodes a node has outgoing edges (in order of priority). The 2 and 0 in the first line are the implicit starting node's outgoing edges. The service ID is the sink node and thus has no outgoing edges (and is not followed by a '-').

TODO: show picture

IMPORTANT: Nodes may be listed in any order, with the exception of the sink node which must be listed last.

URL Format

Annotated Examples

• Python Example
• C Example

Previous: Running Sample Applications

Next: Debugging