1.1 --- a/docs/xen-api/presentation.tex	Wed Nov 29 23:31:07 2006 +0000
     1.2 +++ b/docs/xen-api/presentation.tex	Wed Nov 29 23:34:33 2006 +0000
     1.3 @@ -131,9 +131,6 @@ of that class that has the specified {\t
     1.4  ``{\tt get\_by\_name\_label(name)}'' RPC that returns a set of objects of that
     1.5  class that have the specified {\tt label}.
     1.6  
     1.7 -\item Each class has a ``{\tt to\_XML()}'' RPC that serialises the
     1.8 -state of all fields as an XML string.
     1.9 -
    1.10  \item Each class has a ``{\tt destroy(Ref x)}'' RPC that explicitly deletes
    1.11  the persistent object specified by {\tt x} from the system.  This is a
    1.12  non-cascading delete -- if the object being removed is referenced by another
    1.13 @@ -144,6 +141,6 @@ object then the {\tt destroy} call will 
    1.14  \subsection{Additional RPCs}
    1.15  
    1.16  As well as the RPCs enumerated above, some classes have additional RPCs
    1.17 -associated with them. For example, the {\tt VM} class have RPCs for cloning,
    1.18 +associated with them. For example, the {\tt VM} class has RPCs for cloning,
    1.19  suspending, starting etc. Such additional RPCs are described explicitly
    1.20  in the API reference.

     2.1 --- a/docs/xen-api/todo.tex	Wed Nov 29 23:31:07 2006 +0000
     2.2 +++ b/docs/xen-api/todo.tex	Wed Nov 29 23:34:33 2006 +0000
     2.3 @@ -35,6 +35,8 @@ code, potential error description, but o
     2.4  \item Clarify behaviour of progress field on asyncrhonous request polling when
     2.5  that request fails.
     2.6  
     2.7 +\item Clarify which calls have asynchronous counterparts by marking them as such in the reference. (Individual getters and setters are too small and quick to justify having async versions)
     2.8 +
     2.9  \end{itemize}
    2.10  
    2.11  \subsection{Content}

     3.1 --- a/docs/xen-api/wire-protocol.tex	Wed Nov 29 23:31:07 2006 +0000
     3.2 +++ b/docs/xen-api/wire-protocol.tex	Wed Nov 29 23:34:33 2006 +0000
     3.3 @@ -21,9 +21,9 @@ primitive XML-RPC types.
     3.4  In our API Reference we specify the signatures of API functions in the following
     3.5  style:
     3.6  \begin{verbatim}
     3.7 -    (ref_vm Set)   Host.ListAllVMs()
     3.8 +    (ref_vm Set)   VM.get_all()
     3.9  \end{verbatim}
    3.10 -This specifies that the function with name {\tt Host.ListAllVMs} takes
    3.11 +This specifies that the function with name {\tt VM.get\_all} takes
    3.12  no parameters and returns a Set of {\tt ref\_vm}s.
    3.13  These types are mapped onto XML-RPC types in a straight-forward manner:
    3.14  \begin{itemize}
    3.15 @@ -105,8 +105,8 @@ In the case where {\tt Status} is set to
    3.16  the struct contains a second element named {\tt ErrorDescription}:
    3.17  \begin{itemize}
    3.18  \item The element of the struct named {\tt ErrorDescription} contains
    3.19 -an array of string values. The first element of the array represents an error code;
    3.20 -the remainder of the array represents error parameters relating to that code.
    3.21 +an array of string values. The first element of the array is an XML-RPC 32-bit {\tt i4} and represents an error code;
    3.22 +the remainder of the array are strings representing error parameters relating to that code.
    3.23  \end{itemize}
    3.24  
    3.25  For example, an XML-RPC return value from the {\tt Host.ListAllVMs} function above
    3.26 @@ -161,19 +161,19 @@ A session can be terminated with the {\t
    3.27  
    3.28  \subsection{Synchronous and Asynchronous invocation}
    3.29  
    3.30 -Each method call (apart from those on ``Session'' and ``Task'' objects)
    3.31 +Each method call (apart from methods on ``Session'' and ``Task'' objects 
    3.32 +and ``getters'' and ``setters'' derived from fields)
    3.33  can be made either synchronously or asynchronously.
    3.34  A synchronous RPC call blocks until the
    3.35  return value is received; the return value of a synchronous RPC call is
    3.36  exactly as specified in Section~\ref{synchronous-result}.
    3.37  
    3.38 -Each of the methods specified in the API Reference is synchronous.
    3.39 -However, although not listed explicitly in this document, each
    3.40 -method call has an asynchronous analogue in the {\tt Async}
    3.41 -namespace. For example, synchronous call {\tt VM.Install(...)}
    3.42 +Only synchronous API calls are listed explicitly in this document. 
    3.43 +All asynchronous versions are in the special {\tt Async} namespace.
    3.44 +For example, synchronous call {\tt VM.clone(...)}
    3.45  (described in Chapter~\ref{api-reference})
    3.46  has an asynchronous counterpart, {\tt
    3.47 -Async.VM.Install(...)}, that is non-blocking.
    3.48 +Async.VM.clone(...)}, that is non-blocking.
    3.49  
    3.50  Instead of returning its result directly, an asynchronous RPC call
    3.51  returns a {\tt task-id}; this identifier is subsequently used
    3.52 @@ -186,39 +186,14 @@ is wrapped in an XML-RPC struct with a {
    3.53  The {\tt task-id} is provided in the {\tt Value} field if {\tt Status} is set to
    3.54  {\tt Success}.
    3.55  
    3.56 -Two special RPC calls are provided to poll the status of
    3.57 -asynchronous calls:
    3.58 +The RPC call
    3.59  \begin{verbatim}
    3.60 -    Array<task_id>  Async.Task.GetAllTasks (session_id s)
    3.61 -    task_status     Async.Task.GetStatus   (session_id s, task_id t)
    3.62 -\end{verbatim}
    3.63 -
    3.64 -{\tt Async.Task.GetAllTasks} returns a set of the currently
    3.65 -executing asynchronous tasks belong to the current user\footnote{
    3.66 -%
    3.67 -The current user is determined by the username that was provided
    3.68 -to {\tt Session.Login}.
    3.69 -%
    3.70 -}.
    3.71 -
    3.72 -{\tt Async.Task.GetStatus} returns a {\tt task\_status} result.
    3.73 -This is an XML-RPC struct with three elements:
    3.74 -\begin{itemize}
    3.75 -  \item The first element is named {\tt Progress} and contains
    3.76 -an {\tt Integer} between 0 and 100 representing the estimated percentage of
    3.77 -the task currently completed.
    3.78 -  \item The second element is named {\tt ETA} and contains a {\tt DateTime} 
    3.79 -representing the estimated time the task will be complete.
    3.80 -  \item The third element is named {\tt Result}. If {\tt Progress}
    3.81 -is not 100 then {\tt Result} contains the empty string. If {\tt Progress}
    3.82 -{\em is\/} set to 100, then {\tt Result} contains the function's return
    3.83 -result (as specified in Section~\ref{synchronous-result})\footnote{
    3.84 -%
    3.85 -Recall that this itself is a struct potentially containing status, errorcode,
    3.86 -value fields etc.
    3.87 -%
    3.88 -}.
    3.89 -\end{itemize}
    3.90 +    (ref_task Set)   Task.get_all(session_id s)
    3.91 +\end{verbatim} 
    3.92 +returns a set of all task IDs known to the system. The status (including any
    3.93 +returned result and error codes) of these tasks
    3.94 +can then be queried by accessing the fields of the Task object in the usual way. 
    3.95 +Note that, in order to get a consistent snapshot of a task's state, it is advisable to call the ``get\_record'' function.
    3.96  
    3.97  \section{Example interactive session}
    3.98  
    3.99 @@ -267,7 +242,8 @@ Next, the user may acquire a list of all
   3.100  \begin{verbatim}
   3.101  >>> all_vms = xen.VM.do_list(session)['Value']
   3.102  >>> all_vms
   3.103 -['b7b92d9e-d442-4710-92a5-ab039fd7d89b', '23e1e837-abbf-4675-b077-d4007989b0cc', '2045dbc0-0734-4eea-9cb2-b8218c6b5bf2', '3202ae18-a046-4c32-9fda-e32e9631866e']
   3.104 +['b7b92d9e-d442-4710-92a5-ab039fd7d89b', '23e1e837-abbf-4675-b077-d4007989b0cc',
   3.105 +  '2045dbc0-0734-4eea-9cb2-b8218c6b5bf2', '3202ae18-a046-4c32-9fda-e32e9631866e']
   3.106  \end{verbatim}
   3.107  
   3.108  Note the VM references are internally UUIDs. Once a reference to a VM has been acquired a lifecycle operation may be invoked: