ia64/xen-unstable

changeset 14321:f421ccd1141f

Added section on references vs UUIDs.

Signed-off-by: Ewan Mellor <ewan@xensource.com>
author Ewan Mellor <ewan@xensource.com>
date Fri Mar 09 00:44:10 2007 +0000 (2007-03-09)
parents 3f8f5854acf0
children 038e9138acae
files docs/xen-api/wire-protocol.tex
line diff
     1.1 --- a/docs/xen-api/wire-protocol.tex	Fri Mar 09 00:35:29 2007 +0000
     1.2 +++ b/docs/xen-api/wire-protocol.tex	Fri Mar 09 00:44:10 2007 +0000
     1.3 @@ -30,8 +30,13 @@ These types are mapped onto XML-RPC type
     1.4    \item Floats, Bools, DateTimes and Strings map directly to the XML-RPC {\tt
     1.5    double}, {\tt boolean}, {\tt dateTime.iso8601}, and {\tt string} elements.
     1.6  
     1.7 -  \item all our ``{\tt ref\_}'' types (e.g.\ {\tt ref\_vm} in the above
     1.8 -  example) map to XML-RPC's {\tt String} type.  The string itself is the OSF
     1.9 +  \item all ``{\tt ref\_}'' types are opaque references, encoded as the
    1.10 +  XML-RPC's {\tt String} type. Users of the API should not make assumptions
    1.11 +  about the concrete form of these strings and should not expect them to
    1.12 +  remain valid after the client's session with the server has terminated.
    1.13 +
    1.14 +  \item fields named ``{\tt uuid}'' of type ``{\tt String}'' are mapped to
    1.15 +  the XML-RPC {\tt String} type. The string itself is the OSF
    1.16    DCE UUID presentation format (as output by {\tt uuidgen}, etc).
    1.17  
    1.18    \item ints are all assumed to be 64-bit in our API and are encoded as a
    1.19 @@ -84,6 +89,32 @@ These types are mapped onto XML-RPC type
    1.20  
    1.21  \end{itemize}
    1.22  
    1.23 +\subsection{Note on References vs UUIDs}
    1.24 +
    1.25 +References are opaque types --- encoded as XML-RPC strings on the wire --- understood
    1.26 +only by the particular server which generated them. Servers are free to choose
    1.27 +any concrete representation they find convenient; clients should not make any 
    1.28 +assumptions or attempt to parse the string contents. References are not guaranteed
    1.29 +to be permanent identifiers for objects; clients should not assume that references 
    1.30 +generated during one session are valid for any future session. References do not
    1.31 +allow objects to be compared for equality. Two references to the same object are
    1.32 +not guaranteed to be textually identical.
    1.33 +
    1.34 +UUIDs are intended to be permanent names for objects. They are
    1.35 +guaranteed to be in the OSF DCE UUID presentation format (as output by {\tt uuidgen}.
    1.36 +Clients may store UUIDs on disk and use them to lookup objects in subsequent sessions
    1.37 +with the server. Clients may also test equality on objects by comparing UUID strings.
    1.38 +
    1.39 +The API provides mechanisms
    1.40 +for translating between UUIDs and opaque references. Each class that contains a UUID
    1.41 +field provides:
    1.42 +\begin{itemize}
    1.43 +\item  A ``{\tt get\_by\_uuid}'' method that takes a UUID, $u$, and returns an opaque reference
    1.44 +to the server-side object that has UUID=$u$; 
    1.45 +\item A {\tt get\_uuid} function (a regular ``field getter'' RPC) that takes an opaque reference,
    1.46 +$r$, and returns the UUID of the server-side object that is referenced by $r$.
    1.47 +\end{itemize}
    1.48 +
    1.49  \subsection{Return Values/Status Codes}
    1.50  \label{synchronous-result}
    1.51  
    1.52 @@ -138,7 +169,7 @@ may look like this:
    1.53  
    1.54  \subsection{Transport Layer}
    1.55  
    1.56 -We ought to support at least
    1.57 +The following transport layers are currently supported:
    1.58  \begin{itemize}
    1.59  \item HTTP/S for remote administration
    1.60  \item HTTP over Unix domain sockets for local administration
    1.61 @@ -247,13 +278,12 @@ call takes the session token as the only
    1.62  \begin{verbatim}
    1.63  >>> all_vms = host.get_resident_VMs(session)['Value']
    1.64  >>> all_vms
    1.65 -['b7b92d9e-d442-4710-92a5-ab039fd7d89b', '23e1e837-abbf-4675-b077-d4007989b0cc',
    1.66 -  '2045dbc0-0734-4eea-9cb2-b8218c6b5bf2', '3202ae18-a046-4c32-9fda-e32e9631866e']
    1.67 +['OpaqueRef:1', 'OpaqueRef:2', 'OpaqueRef:3', 'OpaqueRef:4' ]
    1.68  \end{verbatim}
    1.69  
    1.70 -The VM references here are UUIDs, though they may not be that simple in the
    1.71 -future, and you should treat them as opaque strings.  Once a reference to a VM
    1.72 -has been acquired a lifecycle operation may be invoked:
    1.73 +The VM references here have the form {\tt OpaqueRef:X}, though they may not be 
    1.74 +that simple in the future, and you should treat them as opaque strings.  
    1.75 +Once a reference to a VM has been acquired a lifecycle operation may be invoked:
    1.76  
    1.77  \begin{verbatim}
    1.78  >>> xen.VM.start(session, all_vms[3], False)