From ee1ed8aafb077965fb118210ebddde886d8c0a15 Mon Sep 17 00:00:00 2001 From: Ewan Mellor Date: Fri, 9 Mar 2007 00:44:10 +0000 Subject: Added section on references vs UUIDs. Signed-off-by: Ewan Mellor --- docs/xen-api/wire-protocol.tex | 46 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 38 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/xen-api/wire-protocol.tex b/docs/xen-api/wire-protocol.tex index 1548f41c9e..2d11f739c9 100644 --- a/docs/xen-api/wire-protocol.tex +++ b/docs/xen-api/wire-protocol.tex @@ -30,8 +30,13 @@ These types are mapped onto XML-RPC types in a straight-forward manner: \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 @@ -84,6 +89,32 @@ These types are mapped onto XML-RPC types in a straight-forward manner: \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} \label{synchronous-result} @@ -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 parameter) \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'] +['OpaqueRef:1', 'OpaqueRef:2', 'OpaqueRef:3', 'OpaqueRef:4' ] \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: +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) -- cgit v1.2.3