lib/evms/options.h

   1 /*
   2  *
   3  *   Copyright (c) International Business Machines  Corp., 2001
   4  *   Copyright (C) 1997-1999 David Mosberger-Tang and Andreas Beck
   5  *
   6  *   This program is free software;  you can redistribute it and/or modify
   7  *   it under the terms of the GNU General Public License as published by
   8  *   the Free Software Foundation; either version 2 of the License, or
   9  *   (at your option) any later version.
  10  *
  11  *   This program is distributed in the hope that it will be useful,
  12  *   but WITHOUT ANY WARRANTY;  without even the implied warranty of
  13  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
  14  *   the GNU General Public License for more details.
  15  *
  16  *   You should have received a copy of the GNU General Public License
  17  *   along with this program;  if not, write to the Free Software
  18  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  19  *
  20  * Module: options.h
  21  */
  22
  23 #ifndef EVMS_OPTIONS_H_INCLUDED
  24 #define EVMS_OPTIONS_H_INCLUDED 1
  25
  26 #include <common.h>
  27
  28 /*
  29  * Dear Reader,
  30  *
  31  * Yes, some of the structures look a lot like the ones the SANE
  32  * (Scanner Access Now Easy) folks use for negotiating options
  33  * between a frontend and backend. In fact, some of the structures
  34  * here were derived from their solution with some tweaks for EVMS.
  35  *
  36  * Kindest regards and most humble apologies to the SANE folks for
  37  * borrowing their solution.
  38  */
  39
  40 /*
  41  * Task API typedefs
  42  */
  43
  44 typedef u_int32_t task_handle_t;
  45
  46 /*
  47  * Task actions correspond to the low-level API available to frontends.
  48  * The task API allows binding of action, plugin, target objects, and
  49  * plugin-specific options. This allows for interaction with the backend
  50  * to validate the correctness of parameters and options necessary to
  51  * fulfill the requirements of the low-level API which eventually is invoked.
  52  */
  53
  54 typedef enum {
  55     EVMS_Task_Create = 0,
  56     EVMS_Task_Create_Container,
  57     EVMS_Task_Assign_Plugin,
  58     EVMS_Task_Expand_Container,
  59     EVMS_Task_Set_Info,
  60     EVMS_Task_Expand,
  61     EVMS_Task_Shrink,
  62     EVMS_Task_Slide,
  63     EVMS_Task_Move,
  64     EVMS_Task_mkfs,
  65     EVMS_Task_fsck,
  66     EVMS_Task_defrag,
  67     EVMS_Task_Message,
  68     EVMS_Task_Add_Feature,
  69     EVMS_Task_Shrink_Container,
  70     EVMS_Task_Set_Container_Info,
  71     EVMS_Task_Plugin_Function = 0x1000  /* Base number for plug-in funtions */
  72 } task_action_t;
  73
  74
  75 typedef struct function_info_s {
  76     task_action_t   function;       /* Plugin function number */
  77 #if (EVMS_ABI_CODE >= 110)
  78     char          * name;           /* Short, unique (within the plug-in) name for the function */
  79                                     /* e.g., "addspare" */
  80 #endif
  81     char          * title;          /* Short title for the function */
  82                                     /* e.g. "Add a spare" */
  83                                     /* Example usage:  A UI might put this in */
  84                                     /* a menu of functions to select. */
  85     char          * verb;           /* One or two action words for the function */
  86                                     /* e.g. "Add" */
  87                                     /* Example usage:  A GUI may use this on an */
  88                                     /* action button for the function. */
  89     char          * help;           /* Full help text */
  90                                     /* e.g. "Use this function to add a spare blah blah blah..." */
  91 } function_info_t;
  92
  93 typedef struct function_info_array_s {
  94     uint            count;
  95     function_info_t info[1];
  96 } function_info_array_t;
  97
  98
  99 /*
 100  * Object API typedefs
 101  */
 102
 103 typedef struct declined_handle_s {
 104     object_handle_t           handle;               /* Handle of object declined */
 105     int                       reason;               /* Reason for being declined */
 106 } declined_handle_t;
 107
 108 typedef struct declined_handle_array_s {
 109     uint                      count;
 110     declined_handle_t         declined[1];
 111 } declined_handle_array_t;
 112
 113 /*
 114  * Option API typedefs and constants
 115  */
 116
 117 typedef enum {
 118     EVMS_Type_String = 1,                           /* char*     */
 119     EVMS_Type_Boolean,                              /* BOOLEAN   */
 120     EVMS_Type_Char,                                 /* char      */
 121     EVMS_Type_Unsigned_Char,                        /* unsigned char */
 122     EVMS_Type_Real32,                               /* float     */
 123     EVMS_Type_Real64,                               /* double    */
 124     EVMS_Type_Int,                                  /* int       */
 125     EVMS_Type_Int8,                                 /* int8_t    */
 126     EVMS_Type_Int16,                                /* int16_t   */
 127     EVMS_Type_Int32,                                /* int32_t   */
 128     EVMS_Type_Int64,                                /* int64_t   */
 129     EVMS_Type_Unsigned_Int,                         /* uint      */
 130     EVMS_Type_Unsigned_Int8,                        /* u_int8_t  */
 131     EVMS_Type_Unsigned_Int16,                       /* u_int16_t */
 132     EVMS_Type_Unsigned_Int32,                       /* u_int32_t */
 133     EVMS_Type_Unsigned_Int64                        /* u_int64_t */
 134 } value_type_t;
 135
 136 typedef enum {
 137     EVMS_Unit_None = 0,
 138     EVMS_Unit_Disks,
 139     EVMS_Unit_Sectors,
 140     EVMS_Unit_Segments,
 141     EVMS_Unit_Regions,
 142     EVMS_Unit_Percent,
 143     EVMS_Unit_Milliseconds,
 144     EVMS_Unit_Microseconds,
 145     EVMS_Unit_Bytes,
 146     EVMS_Unit_Kilobytes,
 147     EVMS_Unit_Megabytes,
 148     EVMS_Unit_Gigabytes,
 149     EVMS_Unit_Terabytes,
 150     EVMS_Unit_Petabytes
 151 } value_unit_t;
 152
 153 typedef enum {
 154     EVMS_Collection_None = 0,                       /* No collection */
 155     EVMS_Collection_List,                           /* Use a value_list_t structure */
 156     EVMS_Collection_Range                           /* Use a value_range_t structure */
 157 } collection_type_t;
 158
 159 typedef enum {
 160     EVMS_Format_Normal = 0,
 161     EVMS_Format_Hex,
 162     EVMS_Format_Ascii,
 163     EVMS_Format_Binary
 164 } value_format_t;
 165
 166 typedef union {
 167     char                      c;                    /* one character, e.g. 'C' */
 168     char                     *s;                    /* string pointer */
 169     u_char                    uc;
 170     int                       bool;
 171     int                       i;
 172     int8_t                    i8;
 173     int16_t                   i16;
 174     int32_t                   i32;
 175     int64_t                   i64;
 176     u_int                     ui;
 177     u_int8_t                  ui8;
 178     u_int16_t                 ui16;
 179     u_int32_t                 ui32;
 180     u_int64_t                 ui64;
 181     float                     r32;
 182     double                    r64;
 183     struct value_list_s      *list;
 184 } value_t;
 185
 186 /*
 187  * The struct key_value_pair_s allows some generic passing
 188  * of a key/value pair for some basic data type values. The
 189  * key can be a name (a string) or a number. The sending
 190  * and receiving ends denote, through the is_number_based flag,
 191  * which key should be looked at for identification purposes.
 192  */
 193
 194 typedef struct key_value_pair_s {
 195     char           *name;                           /* Key if name-based */
 196     u_int16_t       number;                         /* Key if number-based */
 197     BOOLEAN         is_number_based;                /* TRUE if number-based */
 198     value_type_t    type;                           /* Value type */
 199     value_t         value;                          /* Union of basic data types */
 200 } key_value_pair_t;
 201
 202 /*
 203  * Some frontends may supply plugin-specific data as "options" through
 204  * the API functions, e.g. evms_create(), available to a frontend.
 205  * Options are essentially key/value pairs where the key and value types
 206  * are known ahead-of-time or were interrogated through the option
 207  * descriptor API.
 208  */
 209
 210 typedef struct option_array_s {
 211     u_int                     count;
 212     key_value_pair_t          option[1];
 213 } option_array_t;
 214
 215 typedef struct value_list_s {
 216     u_int                     count;
 217     value_t                   value[1];
 218 } value_list_t;
 219
 220 typedef struct value_range_s {
 221     value_t                   min;                  /* Minimum value */
 222     value_t                   max;                  /* Maximum value */
 223     value_t                   increment;            /* Step or increment for changes in-between */
 224 } value_range_t;
 225
 226 typedef union {
 227     value_list_t             *list;                 /* Array of values of the same type */
 228     value_range_t            *range;                /* Range of values for numeric types */
 229 } value_collection_t;
 230
 231 typedef struct group_info_s {
 232     u_int32_t                 group_number;         /* group number, 0 if not grouped */
 233     u_int32_t                 group_level;          /* possibly used for indenting, or sub fields */
 234     char                     *group_name;           /* name of group                              */
 235 } group_info_t;
 236
 237 typedef struct option_descriptor_s {
 238     char                     *name;                 /* Option name/key */
 239     char                     *title;                /* One or two word description of option */
 240     char                     *tip;                  /* Multi-sentence description of option for tip */
 241     char                     *help;                 /* Multi-paragraph detailed option help */
 242     value_type_t              type;                 /* Defines option data type */
 243     value_unit_t              unit;                 /* Defines unit value */
 244 #if (EVMS_ABI_CODE == 100)
 245     u_int32_t                 size;                 /* Maximum size (in bytes) of option value */
 246 #else
 247     value_format_t            format;               /* Suggested format for display of values */
 248     u_int32_t                 min_len;              /* Minimum length for string types */
 249     u_int32_t                 max_len;              /* Maximum length for string types */
 250 #endif
 251     u_int64_t                 flags;                /* Option flags (defined below) */
 252     collection_type_t         constraint_type;      /* Constraint type (none, range, list) */
 253     value_collection_t        constraint;           /* Either a list or range of valid input values */
 254     value_t                   value;                /* Initial/current value */
 255     group_info_t              group;                /* Group information for display purposes     */
 256 } option_descriptor_t;
 257
 258 /*
 259  * option_descriptor_t flags bitset
 260  */
 261
 262 #define EVMS_OPTION_FLAGS_NOT_REQUIRED     (1 << 0) /* A key_value_pair_t for this option can be provided */
 263                                                     /* but is not absolutely required by the plug-in */
 264 #define EVMS_OPTION_FLAGS_NO_INITIAL_VALUE (1 << 1) /* The plug-in has not provided an initial value */
 265 #define EVMS_OPTION_FLAGS_AUTOMATIC        (1 << 2) /* Backend is capable of selecting reasonable value */
 266 #define EVMS_OPTION_FLAGS_INACTIVE         (1 << 3) /* Option exists but is neither optional or required */
 267 #define EVMS_OPTION_FLAGS_ADVANCED         (1 << 4) /* Option is an "advanced user option" */
 268 #define EVMS_OPTION_FLAGS_VALUE_IS_LIST    (1 << 5) /* Value is/is expected to be a pointer to value_list_t */
 269 #define EVMS_OPTION_FLAGS_NO_UNIT_CONVERSION (1 << 6) /* Don't convert unit measurements, e.g. I really mean */
 270                                                       /* to have the user specify/see sectors not KB or MB */
 271
 272 #define EVMS_OPTION_IS_ACTIVE(flags)     (((flags) & EVMS_OPTION_FLAGS_INACTIVE) == 0)
 273 #define EVMS_OPTION_IS_REQUIRED(flags)   (((flags) & EVMS_OPTION_FLAGS_NOT_REQUIRED) == 0)
 274 #define EVMS_OPTION_HAS_VALUE(flags)     (((flags) & EVMS_OPTION_FLAGS_NO_INITIAL_VALUE) == 0)
 275 #define EVMS_OPTION_VALUE_IS_LIST(flags) (((flags) & EVMS_OPTION_FLAGS_VALUE_IS_LIST) != 0)
 276
 277 /*
 278  * Following bitset indicating additional information of
 279  * the outcome of a set_object or a set action on a option value.
 280  */
 281
 282 typedef enum {
 283     EVMS_Effect_Inexact        = (1 << 0),       /* Option value was adjusted by backend */
 284     EVMS_Effect_Reload_Options = (1 << 1),       /* Setting of an object or option has affected */
 285                                                  /* the value or availability of other options */
 286     EVMS_Effect_Reload_Objects = (1 << 2)        /* Setting of an object or option has affected */
 287                                                  /* the acceptable and/or selected objects */
 288                                                  /* or the limits of objects selected. */
 289 } task_effect_t;
 290
 291 /*
 292  * Extended information structure. Plug-ins generate an
 293  * array of these to supply plugin-specific information.
 294  * They are similar to option descriptors but lighter.
 295  */
 296
 297 typedef struct extended_info_s {
 298     char                   *name;                   /* Info field name */
 299     char                   *title;                  /* One or two word description of info field */
 300     char                   *desc;                   /* Multi-sentence description of info field */
 301     value_type_t            type;                   /* Defines info data type */
 302     value_unit_t            unit;                   /* Defines info unit value */
 303     value_format_t          format;                 /* Suggested format for display of values */
 304     value_t                 value;                  /* Single value if not a collection */
 305     collection_type_t       collection_type;        /* Defines if either a list or range of values */
 306     value_collection_t      collection;             /* Either a list or range of values of value_type_t */
 307     group_info_t            group;                  /* Group information for display purposes */
 308     u_int16_t               flags;                  /* Extended info flags (defined below) */
 309 } extended_info_t;
 310
 311 #define EVMS_EINFO_FLAGS_NO_UNIT_CONVERSION (1 << 0) /* Don't convert unit measurements, e.g. I really */
 312                                                      /* mean the user to see sectors not KB or MB */
 313 #define EVMS_EINFO_FLAGS_MORE_INFO_AVAILABLE (1 << 1)/* This entry has more information if */
 314                                                      /* queried by name. */
 315
 316 typedef struct extended_info_array_s {
 317     u_int                   count;                  /* Count of extended_info_t structs in array */
 318     extended_info_t         info[1];                /* Info descriptors */
 319 } extended_info_array_t;
 320
 321 #endif