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>
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}