Changeset 539

Show
Ignore:
Timestamp:
02/19/07 14:41:53 (2 years ago)
Author:
hollow
Message:

add MENOVG error; rearrange error numbers a bit

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved
  • trunk/TODO

    r519 r539  
    1212- sysctl support 
    1313- cpuset support 
     14- owner notifications? 
     15- contact handles? 
  • trunk/doc/manual/rpcref/intro.tex

    r522 r539  
     1\chapter{Introduction} 
     2 
     3 
     4\section{XML-RPC Signatures} 
     5 
     6The XMLRPC signatures used in this part of the manual define a translation 
     7between the XMLRPC value and C-friendly data types that represent the same 
     8information. For example, it might say that a floating point number translates 
     9to or from a C double value, or that an array of 4 integers translates to or 
     10from 4 C int values. 
     11 
     12A format string usually describes the type of one XMLRPC value. But some types 
     13(array and structure) are compound types -- they are composed recursively of 
     14other XMLRPC values. So a single format string might involve multiple XMLRPC 
     15values. 
     16 
     17But first, lets look at the simple (not compound) format types. These are easy. 
     18The format string consists of one of the strings in the list below. The string 
     19is called a format specifier, and in particular a simple format specifier. 
     20 
     21The XMLRPC server uses only three native XMLRPC datatypes: 
     22 
     23\begin{labeling}{00.00.0000} 
     24\item [{\texttt{int}}] signed 32-bit integer (-2,147,483,648 to +2,147,483,647) 
     25\item [{\texttt{bool}}] boolean value (true/false) 
     26\item [{\texttt{string}}] character string of arbitrary length 
     27\end{labeling} 
     28 
     29Unfortunately the XMLRPC protocol does not define 64-bit integer values, 
     30therefore the XMLRPC server uses the native string datatype and converts all 
     31leading digit characters to 64-bit integer representation. 
     32 
     33This chapter uses the following convention to denote these integer datatypes: 
     34 
     35\begin{labeling}{00.00.0000} 
     36\item [{\texttt{int32}}] signed 32-bit integer 
     37        (-2,147,483,648 to +2,147,483,647) 
     38\item [{\texttt{uint32}}] unsigned 32-bit integer 
     39        (0 to +4,294,967,295) 
     40\item [{\texttt{int64}}] signed 64-bit integer 
     41        (-9,223,372,036,854,775,808 to +9,223,372,036,854,775,807) 
     42\item [{\texttt{uint64}}] unsigned 64-bit integer 
     43        (0 to +18,446,744,073,709,551,615) 
     44\end{labeling} 
     45 
     46The simple datatypes mentioned above are not sufficent to represent data in an 
     47efficient way. Therefore compound datatypes are defined in XMLRPC. There are two 
     48compound datatypes: array and struct.  The signature denotes arrays using 
     49normal braces, structs use curly braces. 
     50 
     51\begin{labeling}{00.00.0000} 
     52\item [{\texttt{array}}] An array holds a series of data elements. Individual 
     53        elements are accessed by their position array in the array. 
     54\item [{\texttt{struct}}] A structure is a collection of simple datatypes under 
     55        a single compund. This collection can be of different types, and each has 
     56        a name which is used to select it from the structure. A structure is a 
     57        convenient way of grouping several pieces of related information together. 
     58\end{labeling} 
     59 
     60Here are some examples of XMLRPC signatures: 
     61 
     62\begin{itemize} 
     63\item A single \texttt{string} datatype named \emph{path}:\\ 
     64        \texttt{string path} 
     65\item An \texttt{array} of three int datatypes:\\ 
     66        \texttt{(int, int, int)} 
     67\item An \texttt{array} with one \texttt{bool}, one \texttt{string} and one 
     68        \texttt{int} datatype:\\ 
     69        \texttt{(bool, string, int)} 
     70\item A \texttt{struct} with one \texttt{string} and one \texttt{int} 
     71        datatype:\\ 
     72        \texttt{\{string name, int id\}} 
     73\end{itemize} 
     74 
     75Please note that the next chapters use the following convention to declare 
     76methods and their parameters, although they do not involve arrays. 
     77 
     78\begin{quote} 
     79\texttt{vx.create(string name, string template, int rebuild)} 
     80\end{quote} 
     81 
     82Instead this convention matches the function declaration in the C language. 
     83Translated to a XMLRPC signature format string the above would become a struct: 
     84 
     85\begin{quote} 
     86\texttt{\{string name, string template, int rebuild\}} 
     87\end{quote} 
     88 
     89Read on to the next section to learn how method requests are performed and how 
     90this struct is placed in the request. 
     91 
     92 
     93\section{Performing XML-RPC Requests} 
     94 
     95An XMLRPC method call is an HTTP-POST request. The body of the request is in 
     96XML. The specified method executes on the server and the value it returns is 
     97also formatted in XML. 
     98 
     99Here is an example of an XML-RPC request: 
     100 
     101\begin{verbatim} 
     102POST /RPC2 HTTP/1.0 
     103User-Agent: VCC/1.0 
     104Host: betty.userland.com 
     105Content-Type: text/xml 
     106Content-length: 181 
     107 
     108<?xml version="1.0"?> 
     109<methodCall> 
     110<methodName>examples.getStateName</methodName> 
     111<params> 
     112<param> 
     113<value><i4>41</i4></value> 
     114</param> 
     115</params> 
     116</methodCall> 
     117\end{verbatim} 
     118 
     119 
     120\subsection{Header Requirements} 
     121 
     122The following requirements must be met when sending requests to the XMLRPC 
     123server: 
     124 
     125\begin{itemize} 
     126\item The \texttt{/RPC2} location handler to explicitly denote XMLRPC requests 
     127\item A User-Agent and Host must be specified 
     128\item The Content-Type is text/xml 
     129\item The Content-Length must be specified and must be correct 
     130\end{itemize} 
     131 
     132 
     133\subsection{Payload Format} 
     134 
     135The payload is in XML, a single \texttt{<methodCall>} structure. 
     136 
     137The \texttt{<methodCall>} must contain a \texttt{<methodName>} sub-item, a 
     138string, containing the name of the method to be called. The string may only 
     139contain identifier characters, upper and lower-case A-Z, the numeric 
     140characters, 0-9, underscore, dot, colon and slash. 
     141 
     142If the procedure call has parameters, the <methodCall> must contain a <params> 
     143sub-item. The <params> sub-item can contain any number of <param>s, each of 
     144which has a <value>. 
     145 
     146 
     147\subsubsection{Simple Datatypes} 
     148 
     149The XMLRPC server only uses three native datatypes as mentioned above: 
     150 
     151\begin{labeling}{00.00.0000} 
     152\item [{\texttt{<int>}}] signed 32-bit integer 
     153\item [{\texttt{<boolean>}}] 0 (false) or 1 (true) 
     154\item [{\texttt{<string>}}] character string of arbitrary length 
     155\end{labeling} 
     156 
     157If no type is indicated, the type is string. 
     158 
     159 
     160\subsubsection{Structures} 
     161 
     162\subsubsection{Arrays} 
     163 
     164\subsection{Method Initialization} 
     165 
     166\subsection{Authentication and Access Restrictions} 
     167 
     168\subsection{Response Format} 
     169 
     170 
     171 
     172\section{Method Error Codes} 
  • trunk/doc/manual/rpcref/vxdb.tex

    r531 r539  
    236236 
    237237\begin{rpcaccess} 
     238% FIXME: INFO cap may expose information leak. 
    238239\rpccapability{INFO} and \rpcnoownerchecks. 
    239240\end{rpcaccess} 
     
    440441 
    441442\begin{rpcaccess} 
     443% FIXME: INFO cap may expose information leak. 
    442444\rpccapability{INFO} and \rpcnoownerchecks. 
    443445\end{rpcaccess} 
     
    842844 
    843845\begin{rpcaccess} 
     846% FIXME: INFO cap may expose information leak. 
    844847\rpccapability{INFO} and \rpcnoownerchecks. 
    845848\end{rpcaccess} 
  • trunk/src/vcd/methods.c

    r534 r539  
    3737        { MEVXDB,    "Error in vxdb" }, 
    3838        { MECONF,    "Invalid configuration" }, 
    39         { MENOUSER,  "No such user" }, 
    40         { MESTOPPED, "Not running" }, 
    41         { MERUNNING, "Already running" }, 
    42         { MEEXIST,   "Conflict/Already exists" }, 
    43         { MENOVPS,   "Not found" }, 
     39        { MENOUSER,  "User does not exist" }, 
     40        { MESTOPPED, "Virtual server not running" }, 
     41        { MERUNNING, "Virtual server still/already running" }, 
     42        { MEEXIST,   "Object already exists" }, 
     43        { MENOVPS,   "Virtual server does not exist" }, 
     44        { MENOVG,    "Virtual server group does not exist" }, 
    4445        { MEBUSY,    "Operation still in progress" }, 
    4546        { MESYS,     "System call failed" }, 
  • trunk/src/vcd/methods.h

    r534 r539  
    3232#define MEAUTH    100 
    3333#define MEPERM    101 
    34 #define MEINVAL   102 
    35 #define MEVXDB    200 
    36 #define MECONF    201 
    37 #define MENOUSER  202 
     34#define MENOUSER  102 
     35#define MEINVAL   200 
     36#define MEEXIST   201 
     37#define MENOVPS   202 
     38#define MENOVG    203 
    3839#define MESTOPPED 300 
    3940#define MERUNNING 301 
    40 #define MEEXIST   400 
    41 #define MENOVPS   401 
    42 #define MEBUSY    402 
     41#define MEBUSY    302 
     42#define MEVXDB    400 
     43#define MECONF    401 
    4344#define MESYS     500 
    4445#define MEEXEC    1000 /* this should always be the last error code */ 
  • trunk/src/vgc

    • Property svn:ignore set to
      Makefile.in