Programming Interface

XDI Programming Interface

This page describes the programming interface (API: Application Programming Interface) for the XDI File Library. The XDI File library provides methods and structured data for the XAFS Data Interchange File Format. Here, you will find a full listing of the functions and data avaliable for dealing with XDI formatted files.

XDI Files are plain-text files, and so should be readable by a large number of existing Applications and programming languages. The library described here should be viewed as the standard interface to XDI Files, and offers data structured in a way that is meant to be more useful than simply as plain text. Though XDI Files can be read in a variety of languages, the discussion here focuses on usage from the C programming language. Other languages will have similar APIs, typically derived from the C API, and will be discussed as > comments for each function.

Basic usage

To use the XDI interface, include the line

  #include "xdifile.h"

In your C program.

readxdi

The principle way to read an XDI File is with the readxdi() function. This function has a signature of

int readxdi(char *filename, XDIFile *xdifile);

and so takes the name of the XDI file as its first object, and a pointer to an allocated XDIFile structure (defined in xdifile.h) as its second argument. The function return value is one of

 0   success.
-7   could not open file.
-6   out of memory to read file.
-5   file contains more than 16384 lines, and so cannot be valid.
-1   file does not begin with '# XDI/', and so cannot be valid.

The XDIFile structure will be filled with the data read and parsed from the XDI file.

Example Usage:

XDIFile *xdifile;
int ret;
char *filname;

xdifile = calloc(1, sizeof(XDIFile));
ret = readxdi(filename, xdifile);
if (ret < 0) {
   printf("Error reading %s: error code=%ld\n", filename, ret);
}
printf("Read XDI File!\nXDI version = %s\n", xdifile->xdi_version);
printf("Read %ld arrays, each with %ld data points\n", xdifile->narrays, xdifile->npts);