# HG changeset patch
# User Ewan Mellor <ewan@xxxxxxxxxxxxx>
# Date 1173401050 0
# Node ID f421ccd1141f452fbd22b9f87d570f73e16494d1
# Parent 3f8f5854acf005d200f3eee46498fc2d1e5506ba
Added section on references vs UUIDs.
Signed-off-by: Ewan Mellor <ewan@xxxxxxxxxxxxx>
---
docs/xen-api/wire-protocol.tex | 50 ++++++++++++++++++++++++++++++++---------
1 files changed, 40 insertions(+), 10 deletions(-)
diff -r 3f8f5854acf0 -r f421ccd1141f docs/xen-api/wire-protocol.tex
--- a/docs/xen-api/wire-protocol.tex Fri Mar 09 00:35:29 2007 +0000
+++ b/docs/xen-api/wire-protocol.tex Fri Mar 09 00:44:10 2007 +0000
@@ -30,8 +30,13 @@ These types are mapped onto XML-RPC type
\item Floats, Bools, DateTimes and Strings map directly to the XML-RPC {\tt
double}, {\tt boolean}, {\tt dateTime.iso8601}, and {\tt string} elements.
- \item all our ``{\tt ref\_}'' types (e.g.\ {\tt ref\_vm} in the above
- example) map to XML-RPC's {\tt String} type. The string itself is the OSF
+ \item all ``{\tt ref\_}'' types are opaque references, encoded as the
+ XML-RPC's {\tt String} type. Users of the API should not make assumptions
+ about the concrete form of these strings and should not expect them to
+ remain valid after the client's session with the server has terminated.
+
+ \item fields named ``{\tt uuid}'' of type ``{\tt String}'' are mapped to
+ the XML-RPC {\tt String} type. The string itself is the OSF
DCE UUID presentation format (as output by {\tt uuidgen}, etc).
\item ints are all assumed to be 64-bit in our API and are encoded as a
@@ -82,6 +87,32 @@ These types are mapped onto XML-RPC type
\item our {\tt Void} type is transmitted as an empty string.
+\end{itemize}
+
+\subsection{Note on References vs UUIDs}
+
+References are opaque types --- encoded as XML-RPC strings on the wire ---
understood
+only by the particular server which generated them. Servers are free to choose
+any concrete representation they find convenient; clients should not make any
+assumptions or attempt to parse the string contents. References are not
guaranteed
+to be permanent identifiers for objects; clients should not assume that
references
+generated during one session are valid for any future session. References do
not
+allow objects to be compared for equality. Two references to the same object
are
+not guaranteed to be textually identical.
+
+UUIDs are intended to be permanent names for objects. They are
+guaranteed to be in the OSF DCE UUID presentation format (as output by {\tt
uuidgen}.
+Clients may store UUIDs on disk and use them to lookup objects in subsequent
sessions
+with the server. Clients may also test equality on objects by comparing UUID
strings.
+
+The API provides mechanisms
+for translating between UUIDs and opaque references. Each class that contains
a UUID
+field provides:
+\begin{itemize}
+\item A ``{\tt get\_by\_uuid}'' method that takes a UUID, $u$, and returns an
opaque reference
+to the server-side object that has UUID=$u$;
+\item A {\tt get\_uuid} function (a regular ``field getter'' RPC) that takes
an opaque reference,
+$r$, and returns the UUID of the server-side object that is referenced by $r$.
\end{itemize}
\subsection{Return Values/Status Codes}
@@ -138,7 +169,7 @@ may look like this:
\subsection{Transport Layer}
-We ought to support at least
+The following transport layers are currently supported:
\begin{itemize}
\item HTTP/S for remote administration
\item HTTP over Unix domain sockets for local administration
@@ -247,13 +278,12 @@ call takes the session token as the only
\begin{verbatim}
>>> all_vms = host.get_resident_VMs(session)['Value']
>>> all_vms
-['b7b92d9e-d442-4710-92a5-ab039fd7d89b',
'23e1e837-abbf-4675-b077-d4007989b0cc',
- '2045dbc0-0734-4eea-9cb2-b8218c6b5bf2',
'3202ae18-a046-4c32-9fda-e32e9631866e']
-\end{verbatim}
-
-The VM references here are UUIDs, though they may not be that simple in the
-future, and you should treat them as opaque strings. Once a reference to a VM
-has been acquired a lifecycle operation may be invoked:
+['OpaqueRef:1', 'OpaqueRef:2', 'OpaqueRef:3', 'OpaqueRef:4' ]
+\end{verbatim}
+
+The VM references here have the form {\tt OpaqueRef:X}, though they may not be
+that simple in the future, and you should treat them as opaque strings.
+Once a reference to a VM has been acquired a lifecycle operation may be
invoked:
\begin{verbatim}
>>> xen.VM.start(session, all_vms[3], False)
_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog
|
Home