ia64/xen-unstable

changeset 13169:5675a2ac56e4

Fix description of ErrorDescription to be all strings, and update the examples.

Signed-off-by: Ewan Mellor <ewan@xensource.com>
author Ewan Mellor <ewan@xensource.com>
date Fri Dec 22 11:49:19 2006 +0000 (2006-12-22)
parents e45948c4dba4
children 8c6e20c60563
files docs/xen-api/wire-protocol.tex
line diff
     1.1 --- a/docs/xen-api/wire-protocol.tex	Fri Dec 22 11:39:29 2006 +0000
     1.2 +++ b/docs/xen-api/wire-protocol.tex	Fri Dec 22 11:49:19 2006 +0000
     1.3 @@ -105,11 +105,13 @@ In the case where {\tt Status} is set to
     1.4  the struct contains a second element named {\tt ErrorDescription}:
     1.5  \begin{itemize}
     1.6  \item The element of the struct named {\tt ErrorDescription} contains
     1.7 -an array of string values. The first element of the array is an XML-RPC 32-bit {\tt i4} and represents an error code;
     1.8 -the remainder of the array are strings representing error parameters relating to that code.
     1.9 +an array of string values. The first element of the array is an error code;
    1.10 +the remainder of the array are strings representing error parameters relating
    1.11 +to that code.
    1.12  \end{itemize}
    1.13  
    1.14 -For example, an XML-RPC return value from the {\tt Host.ListAllVMs} function above
    1.15 +For example, an XML-RPC return value from the {\tt host.get_resident_VMs}
    1.16 +function above
    1.17  may look like this:
    1.18  \begin{verbatim}
    1.19      <struct>
    1.20 @@ -122,9 +124,9 @@ may look like this:
    1.21            <value>
    1.22              <array>
    1.23                 <data>
    1.24 -                 <value>vm-id-1</value>
    1.25 -                 <value>vm-id-2</value>
    1.26 -                 <value>vm-id-3</value>
    1.27 +                 <value>81547a35-205c-a551-c577-00b982c5fe00</value>
    1.28 +                 <value>61c85a22-05da-b8a2-2e55-06b0847da503</value>
    1.29 +                 <value>1d401ec4-3c17-35a6-fc79-cee6bd9811fe</value>
    1.30                 </data>
    1.31              </array>
    1.32           </value>
    1.33 @@ -214,10 +216,12 @@ Create a python object referencing the r
    1.34  >>> xen = xmlrpclib.Server("http://test:4464")
    1.35  \end{verbatim}
    1.36  
    1.37 -Acquire a session token by logging in with a username and password (error-handling ommitted for brevity; the session token is pointed to by the key {\tt 'Value'} in the returned dictionary)
    1.38 +Acquire a session token by logging in with a username and password
    1.39 +(error-handling ommitted for brevity; the session token is pointed to by the
    1.40 +key {\tt 'Value'} in the returned dictionary)
    1.41  
    1.42  \begin{verbatim}
    1.43 ->>> session = xen.Session.do_login_with_password("user", "passwd")['Value']
    1.44 +>>> session = session.login_with_password("user", "passwd")['Value']
    1.45  \end{verbatim}
    1.46  
    1.47  When serialised, this call looks like the following:
    1.48 @@ -225,7 +229,7 @@ When serialised, this call looks like th
    1.49  \begin{verbatim}
    1.50  <?xml version='1.0'?>
    1.51  <methodCall>
    1.52 -  <methodName>Session.do_login_with_password</methodName>
    1.53 +  <methodName>session.login_with_password</methodName>
    1.54    <params>
    1.55      <param>
    1.56        <value><string>user</string></value>
    1.57 @@ -237,10 +241,11 @@ When serialised, this call looks like th
    1.58  </methodCall>
    1.59  \end{verbatim}
    1.60  
    1.61 -Next, the user may acquire a list of all the VMs known to the host: (Note the call takes the session token as the only parameter)
    1.62 +Next, the user may acquire a list of all the VMs known to the host: (Note the
    1.63 +call takes the session token as the only parameter)
    1.64  
    1.65  \begin{verbatim}
    1.66 ->>> all_vms = xen.VM.do_list(session)['Value']
    1.67 +>>> all_vms = host.get_resident_VMs(session)['Value']
    1.68  >>> all_vms
    1.69  ['b7b92d9e-d442-4710-92a5-ab039fd7d89b', '23e1e837-abbf-4675-b077-d4007989b0cc',
    1.70    '2045dbc0-0734-4eea-9cb2-b8218c6b5bf2', '3202ae18-a046-4c32-9fda-e32e9631866e']
    1.71 @@ -249,15 +254,15 @@ Next, the user may acquire a list of all
    1.72  Note the VM references are internally UUIDs. Once a reference to a VM has been acquired a lifecycle operation may be invoked:
    1.73  
    1.74  \begin{verbatim}
    1.75 ->>> xen.VM.do_start(session, all_vms[3], False)
    1.76 +>>> xen.VM.start(session, all_vms[3], False)
    1.77  {'Status': 'Failure', 'ErrorDescription': 'Operation not implemented'}
    1.78  \end{verbatim}
    1.79  
    1.80  In this case the {\tt start} message has not been implemented and an error response has been returned. Currently these high-level errors are returned as structured data (rather than as XMLRPC faults), allowing for internationalised errors in future. Finally, here are some examples of using accessors for object fields:
    1.81  
    1.82  \begin{verbatim}
    1.83 ->>> xen.VM.getname_label(session, all_vms[3])['Value']
    1.84 +>>> xen.VM.get_name_label(session, all_vms[3])['Value']
    1.85  'SMP'
    1.86 ->>> xen.VM.getname_description(session, all_vms[3])['Value']
    1.87 +>>> xen.VM.get_name_description(session, all_vms[3])['Value']
    1.88  'Debian for Xen'
    1.89  \end{verbatim}