%
% Copyright (c) 2006-2007 XenSource, Inc.
%
% Permission is granted to copy, distribute and/or modify this document under
% the terms of the GNU Free Documentation License, Version 1.2 or any later
% version published by the Free Software Foundation; with no Invariant
% Sections, no Front-Cover Texts and no Back-Cover Texts.  A copy of the
% license is included in the section entitled
% "GNU Free Documentation License" or the file fdl.tex.
%
% Authors: Ewan Mellor, Richard Sharp, Dave Scott, Jon Harrop.
%

The API is presented here as a set of Remote Procedure Calls, with a wire
format based upon XML-RPC. No specific language bindings are prescribed,
although examples will be given in the python programming language.
 
Although we adopt some terminology from object-oriented programming, 
future client language bindings may or may not be object oriented.
The API reference uses the terminology {\em classes\/} and {\em objects\/}.
For our purposes a {\em class\/} is simply a hierarchical namespace;
an {\em object\/} is an instance of a class with its fields set to
specific values. Objects are persistent and exist on the server-side.
Clients may obtain opaque references to these server-side objects and then
access their fields via get/set RPCs.

%In each class there is a $\mathit{uid}$ field that assigns an indentifier
%to each object. This $\mathit{uid}$ serves as an object reference
%on both client- and server-side, and is often included as an argument in
%RPC messages.

For each class we specify a list of
fields along with their {\em types\/} and {\em qualifiers\/}.  A
qualifier is one of:
\begin{itemize}
  \item $\mathit{RO}_\mathit{run}$: the field is Read
Only. Furthermore, its value is automatically computed at runtime.
For example: current CPU load and disk IO throughput.
  \item $\mathit{RO}_\mathit{ins}$: the field must be manually set
when a new object is created, but is then Read Only for
the duration of the object's life.
For example, the maximum memory addressable by a guest is set 
before the guest boots.
  \item $\mathit{RW}$: the field is Read/Write. For example, the name
of a VM.
\end{itemize}

A full list of types is given in Chapter~\ref{api-reference}. However,
there are three types that require explicit mention:
\begin{itemize}
  \item $t~\mathit{Ref}$: signifies a reference to an object
of type $t$.
  \item $t~\mathit{Set}$: signifies a set containing
values of type $t$.
  \item $(t_1, t_2)~\mathit{Map}$: signifies a mapping from values of
type $t_1$ to values of type $t_2$.
\end{itemize}

Note that there are a number of cases where {\em Ref}s are {\em doubly
linked\/}---e.g.\ a VM has a field called {\tt VIFs} of type
$(\mathit{VIF}~\mathit{Ref})~\mathit{Set}$; this field lists
the network interfaces attached to a particular VM. Similarly, the VIF
class has a field called {\tt VM} of type $(\mathit{VM}~{\mathit
Ref})$ which references the VM to which the interface is connected.
These two fields are {\em bound together\/}, in the sense that
creating a new VIF causes the {\tt VIFs} field of the corresponding
VM object to be updated automatically.

The API reference explicitly lists the fields that are
bound together in this way. It also contains a diagram that shows
relationships between classes. In this diagram an edge signifies the
existence of a pair of fields that are bound together, using standard
crows-foot notation to signify the type of relationship (e.g.\
one-many, many-many).

\section{RPCs associated with fields}

Each field, {\tt f}, has an RPC accessor associated with it
that returns {\tt f}'s value:
\begin{itemize}
\item ``{\tt get\_f(Ref x)}'': takes a
{\tt Ref} that refers to an object and returns the value of {\tt f}.
\end{itemize}

Each field, {\tt f}, with attribute
{\em RW} and whose outermost type is {\em Set\/} has the following
additional RPCs associated with it:
\begin{itemize}
\item an ``{\tt add\_to\_f(Ref x, v)}'' RPC adds a new element v to the set\footnote{
%
Since sets cannot contain duplicate values this operation has no action in the case
that {\tt v} was already in the set.
%
};
\item a ``{\tt remove\_from\_f(Ref x, v)}'' RPC removes element {\tt v} from the set;
\end{itemize}

Each field, {\tt f}, with attribute
{\em RW} and whose outermost type is {\em Map\/} has the following
additional RPCs associated with it:
\begin{itemize}
\item an ``{\tt add\_to\_f(Ref x, k, v)}'' RPC adds new pair {\tt (k, v)}
to the mapping stored in {\tt f} in object {\tt x}. Adding a new pair for duplicate
key, {\tt k}, overwrites any previous mapping for {\tt k}.
\item a ``{\tt remove\_from\_f(Ref x, k)}'' RPC removes the pair with key {\tt k}
from the mapping stored in {\tt f} in object {\tt x}.
\end{itemize}

Each field whose outermost type is neither {\em Set\/} nor {\em Map\/}, 
but whose attribute is {\em RW} has an RPC acessor associated with it
that sets its value:
\begin{itemize}
\item For {\em RW\/} ({\em R\/}ead/{\em
W\/}rite), a ``{\tt set\_f(Ref x, v)}'' RPC function is also provided.
This sets field {\tt f} on object {\tt x} to value {\tt v}.
\end{itemize}

\section{RPCs associated with classes}

\begin{itemize}
\item Each class has a {\em constructor\/} RPC named ``{\tt create}'' that
takes as parameters all fields marked {\em RW\/} and
$\mathit{RO}_\mathit{ins}$. The result of this RPC is that a new {\em
persistent\/} object is created on the server-side with the specified field
values.

\item Each class has a {\tt get\_by\_uuid(uuid)} RPC that returns the object
of that class that has the specified {\tt uuid}.

\item Each class that has a {\tt name\_label} field has a
``{\tt get\_by\_name\_label(name)}'' RPC that returns a set of objects of that
class that have the specified {\tt label}.

\item Each class has a ``{\tt destroy(Ref x)}'' RPC that explicitly deletes
the persistent object specified by {\tt x} from the system.  This is a
non-cascading delete -- if the object being removed is referenced by another
object then the {\tt destroy} call will fail.

\end{itemize}

\subsection{Additional RPCs}

As well as the RPCs enumerated above, some classes have additional RPCs
associated with them. For example, the {\tt VM} class has RPCs for cloning,
suspending, starting etc. Such additional RPCs are described explicitly
in the API reference.