path: root/generator/types.ml

(* libguestfs
 * Copyright (C) 2009-2012 Red Hat Inc.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 *)

(* Please read generator/README first. *)

(* Types used to describe the API. *)

type style = ret * args * optargs
    (* The [style] is a tuple which describes the return value and
     * arguments of a function.
     *
     * [ret] is the return value, one of the [R*] values below.
     *
     * The second element is the list of required arguments, a list of
     * [argt]s from the list below, eg. [Bool], [String] etc.  Each has
     * a name so that for example [Int "foo"] corresponds in the C
     * bindings to an [int foo] parameter.
     *
     * The third element is the list of optional arguments.  These are
     * mapped to optional arguments in the language binding, eg. in
     * Perl to:
     *   $g->fn (required1, required2, opt1 => val, opt2 => val);
     * As the name suggests these are optional, and the function can
     * tell which optional parameters were supplied by the caller.
     *)

and ret =
    (* "RErr" as a return value means an int used as a simple error
     * indication, ie. 0 or -1.
     *)
  | RErr

    (* "RInt" as a return value means an int which is -1 for error
     * or any value >= 0 on success.  Only use this for smallish
     * positive ints (0 <= i < 2^30).
     *)
  | RInt of string

    (* "RInt64" is the same as RInt, but is guaranteed to be able
     * to return a full 64 bit value, _except_ that -1 means error
     * (so -1 cannot be a valid, non-error return value).
     *)
  | RInt64 of string

    (* "RBool" is a bool return value which can be true/false or
     * -1 for error.
     *)
  | RBool of string

    (* "RConstString" is a string that refers to a constant value.
     * The return value must NOT be NULL (since NULL indicates
     * an error).
     *
     * Try to avoid using this.  In particular you cannot use this
     * for values returned from the daemon, because there is no
     * thread-safe way to return them in the C API.
     *)
  | RConstString of string

    (* "RConstOptString" is an even more broken version of
     * "RConstString".  The returned string may be NULL and there
     * is no way to return an error indication.  Avoid using this!
     *)
  | RConstOptString of string

    (* "RString" is a returned string.  It must NOT be NULL, since
     * a NULL return indicates an error.  The caller frees this.
     *)
  | RString of string

    (* "RStringList" is a list of strings.  No string in the list
     * can be NULL.  The caller frees the strings and the array.
     *)
  | RStringList of string

    (* "RStruct" is a function which returns a single named structure
     * or an error indication (in C, a struct, and in other languages
     * with varying representations, but usually very efficient).  See
     * after the function list below for the structures.
     *)
  | RStruct of string * string		(* name of retval, name of struct *)

    (* "RStructList" is a function which returns either a list/array
     * of structures (could be zero-length), or an error indication.
     *)
  | RStructList of string * string	(* name of retval, name of struct *)

    (* Key-value pairs of untyped strings.  Turns into a hashtable or
     * dictionary in languages which support it.  DON'T use this as a
     * general "bucket" for results.  Prefer a stronger typed return
     * value if one is available, or write a custom struct.  Don't use
     * this if the list could potentially be very long, since it is
     * inefficient.  Keys should be unique.  NULLs are not permitted.
     *)
  | RHashtable of string

    (* "RBufferOut" is handled almost exactly like RString, but
     * it allows the string to contain arbitrary 8 bit data including
     * ASCII NUL.  In the C API this causes an implicit extra parameter
     * to be added of type <size_t *size_r>.  The extra parameter
     * returns the actual size of the return buffer in bytes.
     *
     * Other programming languages support strings with arbitrary 8 bit
     * data.
     *
     * At the RPC layer we have to use the opaque<> type instead of
     * string<>.  Returned data is still limited to the max message
     * size (ie. ~ 2 MB).
     *)
  | RBufferOut of string

and args = argt list	(* Function parameters, guestfs handle is implicit. *)

and argt =
  | Bool of string	(* boolean *)
  | Int of string	(* int (smallish ints, signed, <= 31 bits) *)
  | Int64 of string	(* any 64 bit int *)
  | String of string	(* const char *name, cannot be NULL *)
  | Device of string	(* /dev device name, cannot be NULL *)
  | Pathname of string	(* file name, cannot be NULL *)
  | Dev_or_Path of string (* /dev device name or Pathname, cannot be NULL *)
  | OptString of string	(* const char *name, may be NULL *)
  | StringList of string(* list of strings (each string cannot be NULL) *)
  | DeviceList of string(* list of Device names (each cannot be NULL) *)
    (* Opaque buffer which can contain arbitrary 8 bit data.
     * In the C API, this is expressed as <const char *, size_t> pair.
     * Most other languages have a string type which can contain
     * ASCII NUL.  We use whatever type is appropriate for each
     * language.
     * Buffers are limited by the total message size.  To transfer
     * large blocks of data, use FileIn/FileOut parameters instead.
     * To return an arbitrary buffer, use RBufferOut.
     *)
  | BufferIn of string
    (* Key material / passphrase.  Eventually we should treat this
     * as sensitive and mlock it into physical RAM.  However this
     * is highly complex because of all the places that XDR-encoded
     * strings can end up.  So currently the only difference from
     * 'String' is the way that guestfish requests these parameters
     * from the user.
     *)
  | Key of string
    (* These are treated as filenames (simple string parameters) in
     * the C API and bindings.  But in the RPC protocol, we transfer
     * the actual file content up to or down from the daemon.
     * FileIn: local machine -> daemon (in request)
     * FileOut: daemon -> local machine (in reply)
     * In guestfish (only), the special name "-" means read from
     * stdin or write to stdout.
     *)
  | FileIn of string
  | FileOut of string
    (* This specifies an opaque pointer that is passed through
     * untouched.  Only non-daemon functions are supported.
     *
     * Pointer ("foo *", "bar") translates to "foo *bar" in the
     * C API.  The pointer ("bar") cannot be NULL.
     *
     * This is less well supported in other language bindings:
     * if the pointer type is known then we may be able to produce
     * a suitable binding, otherwise this is translated into a 64
     * bit int.
     *
     * Functions with this parameter type are not supported at all
     * in guestfish (the function must be declared "NotInFish" else
     * you will get an error).  Also the function cannot contain
     * tests, although we should fix this in future.
     *)
  | Pointer of (string * string)

and optargs = optargt list

and optargt =
  | OBool of string	(* boolean *)
  | OInt of string	(* int (smallish ints, signed, <= 31 bits) *)
  | OInt64 of string	(* any 64 bit int *)
  | OString of string	(* const char *name, cannot be NULL *)
  | OStringList of string (* char **strings, neither the list nor any
                             string may be NULL *)

type errcode = [ `CannotReturnError | `ErrorIsMinusOne | `ErrorIsNULL ]

type fish_output_t =
  | FishOutputOctal       (* for int return, print in octal *)
  | FishOutputHexadecimal (* for int return, print in hex *)

(* See guestfs(3)/EXTENDING LIBGUESTFS. *)
type tests = (test_init * test_prereq * test) list
and test =
    (* Run the command sequence and just expect nothing to fail. *)
  | TestRun of seq

    (* Run the command sequence and expect the output of the final
     * command to be the string.
     *)
  | TestOutput of seq * string

    (* Run the command sequence and expect the output of the final
     * command to be the list of strings.
     *)
  | TestOutputList of seq * string list

    (* Run the command sequence and expect the output of the final
     * command to be the list of block devices (could be either
     * "/dev/sd.." or "/dev/hd.." form - we don't check the 5th
     * character of each string).
     *)
  | TestOutputListOfDevices of seq * string list

    (* Run the command sequence and expect the output of the final
     * command to be the integer.
     *)
  | TestOutputInt of seq * int

    (* Run the command sequence and expect the output of the final
     * command to be <op> <int>, eg. ">=", "1".
     *)
  | TestOutputIntOp of seq * string * int

    (* Run the command sequence and expect the output of the final
     * command to be a true value (!= 0 or != NULL).
     *)
  | TestOutputTrue of seq

    (* Run the command sequence and expect the output of the final
     * command to be a false value (== 0 or == NULL, but not an error).
     *)
  | TestOutputFalse of seq

    (* Run the command sequence and expect the output of the final
     * command to be a list of the given length (but don't care about
     * content).
     *)
  | TestOutputLength of seq * int

    (* Run the command sequence and expect the output of the final
     * command to be a buffer (RBufferOut), ie. string + size.
     *)
  | TestOutputBuffer of seq * string

    (* Run the command sequence and expect the output of the final
     * command to be a structure.
     *)
  | TestOutputStruct of seq * test_field_compare list

    (* Run the command sequence and expect the output of the final
     * command to be a string which is the hex MD5 of the content of
     * the named file.
     *)
  | TestOutputFileMD5 of seq * string

    (* Run the command sequence and expect the output of the final
     * command to be a string which is a block device name (we don't
     * check the 5th character of the string, so "/dev/sda" == "/dev/vda").
     *)
  | TestOutputDevice of seq * string

    (* Run the command sequence and expect a hashtable.  Check
     * one of more fields in the hashtable against known good
     * strings.
     *)
  | TestOutputHashtable of seq * (string * string) list

  (* Run the command sequence and expect the final command (only)
   * to fail.
   *)
  | TestLastFail of seq

and test_field_compare =
  | CompareWithInt of string * int
  | CompareWithIntOp of string * string * int
  | CompareWithString of string * string
  | CompareFieldsIntEq of string * string
  | CompareFieldsStrEq of string * string

(* Test prerequisites. *)
and test_prereq =
    (* Test always runs. *)
  | Always

    (* Test is currently disabled - eg. it fails, or it tests some
     * unimplemented feature.
     *)
  | Disabled

    (* 'string' is some C code (a function body) that should return
     * true or false.  The test will run if the code returns true.
     *)
  | If of string

    (* As for 'If' but the test runs _unless_ the code returns true. *)
  | Unless of string

    (* Run the test only if 'string' is available in the daemon. *)
  | IfAvailable of string

(* Some initial scenarios for testing. *)
and test_init =
    (* Do nothing, block devices could contain random stuff including
     * LVM PVs, and some filesystems might be mounted.  This is usually
     * a bad idea.
     *)
  | InitNone

    (* Block devices are empty and no filesystems are mounted. *)
  | InitEmpty

    (* /dev/sda contains a single partition /dev/sda1, with random
     * content.  No LVM.
     *)
  | InitPartition

    (* /dev/sda contains a single partition /dev/sda1, which is formatted
     * as ext2, empty [except for lost+found] and mounted on /.
     * No LVM.
     *
     * Note: for testing filesystem operations, it is quicker to use
     * InitScratchFS
     *)
  | InitBasicFS

    (* /dev/sda:
     *   /dev/sda1 (is a PV):
     *     /dev/VG/LV (size 8MB):
     *       formatted as ext2, empty [except for lost+found], mounted on /
     *
     * Note: only use this if you really need a freshly created filesystem
     * on LVM.  Normally you should use InitScratchFS instead.
     *)
  | InitBasicFSonLVM

    (* /dev/sdd (the ISO, see images/ directory in source)
     * is mounted on /
     *)
  | InitISOFS

    (* /dev/sdb1 (write scratch disk) is mounted on /.  The filesystem
     * will be empty.
     *
     * Note that this filesystem is not recreated between tests, and
     * could contain random files and directories from previous tests.
     * Therefore it is recommended that you create uniquely named files
     * and directories for your tests.
     *)
  | InitScratchFS

(* Sequence of commands for testing. *)
and seq = cmd list
and cmd = string list

(* Type of an action as declared in Actions module. *)
type action = {
  name : string;                  (* name, not including "guestfs_" *)
  style : style;                  (* args and return value *)
  proc_nr : int option;           (* proc number, None for non-daemon *)
  tests : tests;                  (* tests *)
  shortdesc : string;             (* single line description *)
  longdesc : string;              (* longer documentation *)

  (* Lots of flags ... *)
  protocol_limit_warning : bool;  (* warn about protocol size limits *)
  fish_alias : string list;       (* alias(es) for this cmd in guestfish *)
  fish_output : fish_output_t option; (* how to display output in guestfish *)
  in_fish : bool;                 (* export via guestfish *)
  in_docs : bool;                 (* add this function to documentation *)
  deprecated_by : string option;  (* function is deprecated, use .. instead *)
  optional : string option;       (* function is part of an optional group *)
  progress : bool;                (* function can generate progress messages *)
  camel_name : string;            (* Pretty camel case name of
                                     function.  Only specify this if the
                                     generator doesn't make a good job of
                                     it, for example if it contains an
                                     abbreviation. *)
  cancellable : bool;             (* the user can cancel this long-running
                                     function *)
  config_only : bool;             (* non-daemon-function which can only be used
                                     while in CONFIG state *)
  once_had_no_optargs : bool;     (* mark functions that once had no optargs
                                     but now do, so we can generate the
                                     required back-compat machinery *)
  blocking : bool;                (* Function blocks (long-running).  All
                                     daemon functions are blocking by
                                     definition.  Some functions that just
                                     set flags in the handle are marked
                                     non-blocking so that we don't add
                                     machinery in various bindings. *)

  (* "Internal" data attached by the generator at various stages.  This
   * doesn't need to (and shouldn't) be set when defining actions.
   *)
  c_name : string;                (* shortname exposed by C API *)
  c_function : string;            (* full name of C API function called by
                                     non-C bindings *)
  c_optarg_prefix : string;       (* prefix for optarg names/bitmask names *)
  non_c_aliases : string list;    (* back-compat aliases that have to be
                                     generated for this function *)
}

(* Field types for structures. *)
type field =
  | FChar			(* C 'char' (really, a 7 bit byte). *)
  | FString			(* nul-terminated ASCII string, NOT NULL. *)
  | FBuffer			(* opaque buffer of bytes, (char *, int) pair *)
  | FUInt32
  | FInt32
  | FUInt64
  | FInt64
  | FBytes		        (* Any int measure that counts bytes. *)
  | FUUID			(* 32 bytes long, NOT nul-terminated. *)
  | FOptPercent			(* [0..100], or -1 meaning "not present". *)

(* Used for testing language bindings. *)
type callt =
  | CallString of string
  | CallOptString of string option
  | CallStringList of string list
  | CallInt of int
  | CallInt64 of int64
  | CallBool of bool
  | CallBuffer of string

type call_optargt =
  | CallOBool of string * bool
  | CallOInt of string * int
  | CallOInt64 of string * int64
  | CallOString of string * string
  | CallOStringList of string * string list