diff --git a/docs/xen-api/xenapi-datamodel.tex b/docs/xen-api/xenapi-datamodel.tex index 71ffb8b524..cfd264bf94 100644 --- a/docs/xen-api/xenapi-datamodel.tex +++ b/docs/xen-api/xenapi-datamodel.tex @@ -109,6 +109,7 @@ The following enumeration types are used: \hline \end{longtable} +\vspace{1cm} \begin{longtable}{|ll|} \hline {\tt enum vdi\_type} & \\ @@ -133,6 +134,17 @@ The following enumeration types are used: \hline \end{longtable} +\vspace{1cm} +\begin{longtable}{|ll|} +\hline +{\tt enum task\_status\_type} & \\ +\hline +\hspace{0.5cm}{\tt pending} & task is in progress \\ +\hspace{0.5cm}{\tt success} & task was completed successfully \\ +\hspace{0.5cm}{\tt failure} & task has failed \\ +\hline +\end{longtable} + \vspace{1cm} \begin{longtable}{|ll|} \hline @@ -273,6 +285,7 @@ The following enumeration types are used: \hline Quals & Field & Type & Description \\ \hline +$\mathit{RO}_\mathit{run}$ & {\tt uuid} & string & unique identifier/object reference \\ $\mathit{RO}_\mathit{ins}$ & {\tt this\_host} & host ref & Currently connected host \\ $\mathit{RO}_\mathit{ins}$ & {\tt this\_user} & user ref & Currently connected user \\ \hline @@ -330,6 +343,38 @@ void +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_uuid} + +{\bf Overview:} +Get the uuid field of the given session. + + \noindent {\bf Signature:} +\begin{verbatim} string get_uuid (session_id s, session ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt session ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +string +} + + +value of the field \vspace{0.3cm} \vspace{0.3cm} \vspace{0.3cm} @@ -540,48 +585,23 @@ Quals & Field & Type & Description \\ $\mathit{RO}_\mathit{run}$ & {\tt uuid} & string & unique identifier/object reference \\ $\mathit{RW}$ & {\tt name/label} & string & a human-readable name \\ $\mathit{RW}$ & {\tt name/description} & string & a notes field containg human-readable description \\ +$\mathit{RO}_\mathit{run}$ & {\tt status} & task\_status\_type & current status of the task \\ +$\mathit{RO}_\mathit{run}$ & {\tt progress} & int & if the task is still pending, this field contains the estimated percentage complete (0-100). If task has completed (successfully or unsuccessfully) this should be 100. \\ +$\mathit{RO}_\mathit{run}$ & {\tt eta} & datetime & if the task is still pending, this field contains the estimated completion time. If the task has finished (successfully or not) it contains the time the task finished. \\ +$\mathit{RO}_\mathit{run}$ & {\tt type} & string & if the task has completed successfully, this field contains the type of the encoded result (i.e. name of the class whose reference is in the result field). Undefined otherwise. \\ +$\mathit{RO}_\mathit{run}$ & {\tt result} & string & if the task has completed successfully, this field contains the result value (either Void or an object reference). Undefined otherwise. \\ +$\mathit{RO}_\mathit{run}$ & {\tt error\_code} & int & if the task has failed, this field contains the error code. Undefined otherwise. \\ +$\mathit{RO}_\mathit{run}$ & {\tt error\_info} & string Set & if the task has failed, this field contains the set of associated error strings. Undefined otherwise. \\ \hline \end{longtable} \subsection{Additional RPCs associated with class: task} -\subsubsection{RPC name:~get\_status} +\subsubsection{RPC name:~get\_all} {\bf Overview:} -Poll a running asynchronous RPC invocation and query its status +Return a list of all the tasks known to the system \noindent {\bf Signature:} -\begin{verbatim} (uuid ref) get_status (session_id s, task ref task)\end{verbatim} - - -\noindent{\bf Arguments:} - - -\vspace{0.3cm} -\begin{tabular}{|c|c|p{7cm}|} - \hline -{\bf type} & {\bf name} & {\bf description} \\ \hline -{\tt task ref } & task & The ID of the RPC call to poll \\ \hline - -\end{tabular} - -\vspace{0.3cm} - - \noindent {\bf Return Type:} -{\tt -uuid ref -} - - -String describing status of specified asynchronous RPC invocation, including estimated completion time -\vspace{0.3cm} -\vspace{0.3cm} -\vspace{0.3cm} -\subsubsection{RPC name:~get\_all\_tasks} - -{\bf Overview:} -List all asynchronous RPC calls currently executing - - \noindent {\bf Signature:} -\begin{verbatim} ((task ref) Set) get_all_tasks (session_id s)\end{verbatim} +\begin{verbatim} ((task ref) Set) get_all (session_id s)\end{verbatim} \vspace{0.3cm} @@ -592,10 +612,7 @@ List all asynchronous RPC calls currently executing } -A list of tasks currently executing. Note that -tasks are associated with users rather than sessions. Thus, if you logout and -login again with a different session but the same user, this function will still -return the user's running tasks. +references to all objects \vspace{0.3cm} \vspace{0.3cm} \vspace{0.3cm} @@ -760,6 +777,230 @@ void +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_status} + +{\bf Overview:} +Get the status field of the given task. + + \noindent {\bf Signature:} +\begin{verbatim} (task_status_type) get_status (session_id s, task ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt task ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +task\_status\_type +} + + +value of the field +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_progress} + +{\bf Overview:} +Get the progress field of the given task. + + \noindent {\bf Signature:} +\begin{verbatim} int get_progress (session_id s, task ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt task ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +int +} + + +value of the field +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_eta} + +{\bf Overview:} +Get the eta field of the given task. + + \noindent {\bf Signature:} +\begin{verbatim} datetime get_eta (session_id s, task ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt task ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +datetime +} + + +value of the field +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_type} + +{\bf Overview:} +Get the type field of the given task. + + \noindent {\bf Signature:} +\begin{verbatim} string get_type (session_id s, task ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt task ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +string +} + + +value of the field +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_result} + +{\bf Overview:} +Get the result field of the given task. + + \noindent {\bf Signature:} +\begin{verbatim} string get_result (session_id s, task ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt task ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +string +} + + +value of the field +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_error\_code} + +{\bf Overview:} +Get the error\_code field of the given task. + + \noindent {\bf Signature:} +\begin{verbatim} int get_error_code (session_id s, task ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt task ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +int +} + + +value of the field +\vspace{0.3cm} +\vspace{0.3cm} +\vspace{0.3cm} +\subsubsection{RPC name:~get\_error\_info} + +{\bf Overview:} +Get the error\_info field of the given task. + + \noindent {\bf Signature:} +\begin{verbatim} (string Set) get_error_info (session_id s, task ref self)\end{verbatim} + + +\noindent{\bf Arguments:} + + +\vspace{0.3cm} +\begin{tabular}{|c|c|p{7cm}|} + \hline +{\bf type} & {\bf name} & {\bf description} \\ \hline +{\tt task ref } & self & reference to the object \\ \hline + +\end{tabular} + +\vspace{0.3cm} + + \noindent {\bf Return Type:} +{\tt +string Set +} + + +value of the field \vspace{0.3cm} \vspace{0.3cm} \vspace{0.3cm}