usr.sbin/installer/libdfui/dfui.h

   1 /*
   2  * Copyright (c)2004 Cat's Eye Technologies.  All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  *
   8  *   Redistributions of source code must retain the above copyright
   9  *   notice, this list of conditions and the following disclaimer.
  10  *
  11  *   Redistributions in binary form must reproduce the above copyright
  12  *   notice, this list of conditions and the following disclaimer in
  13  *   the documentation and/or other materials provided with the
  14  *   distribution.
  15  *
  16  *   Neither the name of Cat's Eye Technologies nor the names of its
  17  *   contributors may be used to endorse or promote products derived
  18  *   from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  23  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  24  * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  25  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  26  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  27  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  29  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  30  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  31  * OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 /*
  35  * dfui.h
  36  * $Id: dfui.h,v 1.28 2005/02/07 06:39:59 cpressey Exp $
  37  */
  38
  39 #ifndef __DFUI_H
  40 #define __DFUI_H
  41
  42 #ifdef __cplusplus
  43 #define DFUI_BEGINDECLS     extern "C" {
  44 #define DFUI_ENDDECLS       }
  45 #else
  46 #define DFUI_BEGINDECLS
  47 #define DFUI_ENDDECLS
  48 #endif
  49
  50 DFUI_BEGINDECLS
  51
  52 #include <libaura/buffer.h>
  53
  54 /*
  55  * TYPEDEFS
  56  */
  57
  58 typedef int             dfui_err_t;
  59
  60 /*
  61  * CONSTANTS
  62  */
  63
  64 #define DFUI_SUCCESS    (dfui_err_t)1
  65 #define DFUI_FAILURE    (dfui_err_t)0
  66
  67 /*
  68  * Transports.
  69  */
  70
  71 #define DFUI_TRANSPORT_NPIPE    1
  72 #define DFUI_TRANSPORT_TCP      2
  73
  74 /*
  75  * Message types.
  76  */
  77
  78 #define DFUI_BE_MSG_READY       'r'     /* send me back a reply please */
  79
  80 #define DFUI_BE_MSG_STOP        'X'     /* shut down please, we're done */
  81 #define DFUI_BE_MSG_PRESENT     'P'     /* present this form to the user */
  82 #define DFUI_BE_MSG_PROG_BEGIN  'b'     /* begin showing a progress bar */
  83 #define DFUI_BE_MSG_PROG_UPDATE 'u'     /* update the progress bar */
  84 #define DFUI_BE_MSG_PROG_END    'e'     /* stop showing the progress bar */
  85
  86 #define DFUI_BE_MSG_SET_GLOBAL  'G'     /* set a global setting in the f/e */
  87
  88 #define DFUI_FE_MSG_READY       'r'     /* send me a form or something */
  89
  90 #define DFUI_FE_MSG_SUBMIT      'S'     /* submit results of a form */
  91 #define DFUI_FE_MSG_CONTINUE    'c'     /* nothing stopping a progress bar */
  92 #define DFUI_FE_MSG_CANCEL      'C'     /* user cancelled a progress bar */
  93 #define DFUI_FE_MSG_ABORT       'X'     /* something catastrophic (^C?) */
  94
  95 /*
  96  * STRUCTURE PROTOTYPES
  97  */
  98
  99 struct dfui_connection;
 100 struct dfui_payload;
 101 struct dfui_info;
 102 struct dfui_property;
 103 struct dfui_dataset;
 104 struct dfui_celldata;
 105 struct dfui_form;
 106 struct dfui_field;
 107 struct dfui_option;
 108 struct dfui_action;
 109 struct dfui_response;
 110 struct dfui_progress;
 111
 112 /*
 113  * STRUCTURE DEFINITIONS
 114  */
 115
 116 #ifdef NEEDS_DFUI_STRUCTURE_DEFINITIONS
 117
 118 /* Connections */
 119
 120 struct dfui_connection {
 121         int transport;            /* transport layer: NPIPE or TCP */
 122         char *rendezvous;         /* rendezvous point */
 123         struct aura_buffer *ebuf; /* last message recvd */
 124         int is_connected;         /* was a connection actually established? */
 125         void *t_data;             /* transport-specific connection data */
 126
 127         dfui_err_t (*be_start)(struct dfui_connection *);
 128         dfui_err_t (*be_stop)(struct dfui_connection *);
 129         dfui_err_t (*be_ll_exchange)(struct dfui_connection *, char, const char *);
 130
 131         dfui_err_t (*fe_connect)(struct dfui_connection *);
 132         dfui_err_t (*fe_disconnect)(struct dfui_connection *);
 133
 134         dfui_err_t (*fe_ll_request)(struct dfui_connection *, char, const char *);
 135 };
 136
 137 /* Common structures on objects */
 138
 139 struct dfui_info {
 140         char *name;
 141         char *short_desc;
 142         char *long_desc;
 143 };
 144
 145 struct dfui_dataset {
 146         struct dfui_dataset *next;
 147         struct dfui_celldata *celldata_head;
 148 };
 149
 150 struct dfui_celldata {
 151         struct dfui_celldata *next;
 152         char *field_id;
 153         char *value;
 154 };
 155
 156 /*
 157  * Properties may be either strong (imply a behavioural guarantee from
 158  * the frontend) or weak (may be ignored or interpreted subjectively
 159  * by the frontend) depending on their name.  Currently only the
 160  * following properties are strong:
 161  *
 162  *   editable
 163  *   obscured
 164  */
 165 struct dfui_property {
 166         struct dfui_property *next;
 167         char *name;
 168         char *value;
 169 };
 170
 171 /* Form objects */
 172
 173 struct dfui_form {
 174         char *id;
 175         struct dfui_info *info;
 176         int multiple;
 177         int extensible;
 178         struct dfui_field *field_head;
 179         struct dfui_action *action_head;
 180         struct dfui_dataset *dataset_head;
 181         struct dfui_property *property_head;
 182 };
 183
 184 struct dfui_field {
 185         char *id;
 186         struct dfui_info *info;
 187         struct dfui_field *next;
 188         struct dfui_option *option_head;
 189         struct dfui_property *property_head;
 190 };
 191
 192 struct dfui_option {
 193         char *value;
 194         struct dfui_option *next;
 195 };
 196
 197 struct dfui_action {
 198         char *id;
 199         struct dfui_info *info;
 200         struct dfui_action *next;
 201         struct dfui_property *property_head;
 202 };
 203
 204 /* Progress objects */
 205
 206 struct dfui_progress {
 207         struct dfui_info *info;
 208         int amount;
 209         int streaming;          /* if 1, msg will stream in line by line */
 210         char *msg_line;         /* next line of message if streaming=1 */
 211 };
 212
 213 /* Response objects */
 214
 215 struct dfui_response {
 216         char *form_id;
 217         char *action_id;
 218         struct dfui_dataset *dataset_head;
 219 };
 220
 221 /* Payload objects */
 222
 223 struct dfui_payload {
 224         char msgtype;
 225         struct dfui_form *form;
 226         struct dfui_progress *progress;
 227         struct dfui_property *global_setting;
 228 };
 229
 230 #endif /* NEEDS_DFUI_STRUCTURE_DEFINITIONS */
 231
 232 /*
 233  * PROTOTYPES
 234  */
 235
 236 /*
 237  * UTILITY (form/field creation, etc)
 238  */
 239
 240 struct dfui_info                *dfui_info_new(const char *, const char *, const char *);
 241 void                             dfui_info_free(struct dfui_info *);
 242 const char                      *dfui_info_get_name(const struct dfui_info *);
 243 const char                      *dfui_info_get_short_desc(const struct dfui_info *);
 244 const char                      *dfui_info_get_long_desc(const struct dfui_info *);
 245 void                             dfui_info_set_name(struct dfui_info *, const char *);
 246 void                             dfui_info_set_short_desc(struct dfui_info *, const char *);
 247 void                             dfui_info_set_long_desc(struct dfui_info *, const char *);
 248
 249 struct dfui_property            *dfui_property_new(const char *, const char *);
 250 void                             dfui_property_free(struct dfui_property *);
 251 void                             dfui_properties_free(struct dfui_property *);
 252 struct dfui_property            *dfui_property_find(struct dfui_property *, const char *);
 253 const char                      *dfui_property_get(struct dfui_property *, const char *);
 254 struct dfui_property            *dfui_property_set(struct dfui_property **, const char *, const char *);
 255 const char                      *dfui_property_get_name(const struct dfui_property *);
 256 const char                      *dfui_property_get_value(const struct dfui_property *);
 257
 258 struct dfui_celldata            *dfui_celldata_new(const char *, const char *);
 259 void                             dfui_celldata_free(struct dfui_celldata *);
 260 void                             dfui_celldatas_free(struct dfui_celldata *);
 261 struct dfui_celldata            *dfui_celldata_find(struct dfui_celldata *, const char *);
 262 struct dfui_celldata            *dfui_celldata_get_next(const struct dfui_celldata *);
 263 const char *                     dfui_celldata_get_field_id(const struct dfui_celldata *);
 264 const char *                     dfui_celldata_get_value(const struct dfui_celldata *);
 265
 266 struct dfui_dataset             *dfui_dataset_new(void);
 267 struct dfui_dataset             *dfui_dataset_dup(const struct dfui_dataset *);
 268 void                             dfui_dataset_free(struct dfui_dataset *);
 269 void                             dfui_datasets_free(struct dfui_dataset *);
 270 struct dfui_celldata            *dfui_dataset_celldata_add(struct dfui_dataset *,
 271                                         const char *, const char *);
 272 struct dfui_celldata            *dfui_dataset_celldata_get_first(const struct dfui_dataset *);
 273 struct dfui_celldata            *dfui_dataset_celldata_find(const struct dfui_dataset *, const char *);
 274 struct dfui_dataset             *dfui_dataset_get_next(const struct dfui_dataset *);
 275 const char                      *dfui_dataset_get_value(const struct dfui_dataset *, const char *);
 276 char                            *dfui_dataset_dup_value(const struct dfui_dataset *, const char *);
 277
 278 struct dfui_field               *dfui_field_new(const char *, struct dfui_info *);
 279 void                             dfui_field_free(struct dfui_field *);
 280 void                             dfui_fields_free(struct dfui_field *);
 281 struct dfui_option              *dfui_field_option_add(struct dfui_field *, const char *);
 282 struct dfui_option              *dfui_field_option_get_first(const struct dfui_field *);
 283 struct dfui_property            *dfui_field_property_set(struct dfui_field *, const char *, const char *);
 284 const char                      *dfui_field_property_get(const struct dfui_field *, const char *);
 285 int                              dfui_field_property_is(const struct dfui_field *, const char *, const char *);
 286 struct dfui_field               *dfui_field_get_next(const struct dfui_field *);
 287 const char                      *dfui_field_get_id(const struct dfui_field *);
 288 struct dfui_info                *dfui_field_get_info(const struct dfui_field *);
 289
 290 struct dfui_option              *dfui_option_new(const char *);
 291 void                             dfui_option_free(struct dfui_option *);
 292 void                             dfui_options_free(struct dfui_option *);
 293 struct dfui_option              *dfui_option_get_next(const struct dfui_option *);
 294 const char                      *dfui_option_get_value(const struct dfui_option *);
 295
 296 struct dfui_action              *dfui_action_new(const char *, struct dfui_info *);
 297 void                             dfui_action_free(struct dfui_action *);
 298 void                             dfui_actions_free(struct dfui_action *);
 299 struct dfui_action              *dfui_action_get_next(const struct dfui_action *);
 300 struct dfui_property            *dfui_action_property_set(struct dfui_action *, const char *, const char *);
 301 const char                      *dfui_action_property_get(const struct dfui_action *, const char *);
 302 int                              dfui_action_property_is(const struct dfui_action *, const char *, const char *);
 303 const char                      *dfui_action_get_id(const struct dfui_action *);
 304 struct dfui_info                *dfui_action_get_info(const struct dfui_action *);
 305
 306 struct dfui_form                *dfui_form_new(const char *, struct dfui_info *);
 307 struct dfui_form                *dfui_form_create(const char *, const char *, const char *, const char *, ...);
 308 void                             dfui_form_free(struct dfui_form *);
 309 struct dfui_field               *dfui_form_field_add(struct dfui_form *,
 310                                         const char *, struct dfui_info *);
 311 struct dfui_field               *dfui_form_field_attach(struct dfui_form *,
 312                                         struct dfui_field *);
 313 struct dfui_action              *dfui_form_action_add(struct dfui_form *,
 314                                         const char *, struct dfui_info *);
 315 struct dfui_action              *dfui_form_action_attach(struct dfui_form *,
 316                                         struct dfui_action *);
 317 void                             dfui_form_dataset_add(struct dfui_form *,
 318                                         struct dfui_dataset *);
 319 struct dfui_dataset             *dfui_form_dataset_get_first(const struct dfui_form *);
 320 int                              dfui_form_dataset_count(const struct dfui_form *);
 321 void                             dfui_form_datasets_free(struct dfui_form *);
 322 struct dfui_property            *dfui_form_property_set(struct dfui_form *, const char *, const char *);
 323 const char                      *dfui_form_property_get(const struct dfui_form *, const char *);
 324 int                              dfui_form_property_is(const struct dfui_form *, const char *, const char *);
 325 struct dfui_field               *dfui_form_field_find(const struct dfui_form *, const char *);
 326 struct dfui_field               *dfui_form_field_get_first(const struct dfui_form *);
 327 int                              dfui_form_field_count(const struct dfui_form *);
 328 struct dfui_action              *dfui_form_action_find(const struct dfui_form *, const char *);
 329 struct dfui_action              *dfui_form_action_get_first(const struct dfui_form *);
 330 int                              dfui_form_action_count(const struct dfui_form *);
 331 const char                      *dfui_form_get_id(const struct dfui_form *);
 332 struct dfui_info                *dfui_form_get_info(const struct dfui_form *);
 333 void                             dfui_form_set_multiple(struct dfui_form *, int);
 334 int                              dfui_form_is_multiple(const struct dfui_form *);
 335 void                             dfui_form_set_extensible(struct dfui_form *, int);
 336 int                              dfui_form_is_extensible(const struct dfui_form *);
 337
 338 struct dfui_response            *dfui_response_new(const char *, const char *);
 339 void                             dfui_response_free(struct dfui_response *);
 340 void                             dfui_response_dataset_add(struct dfui_response *,
 341                                         struct dfui_dataset *);
 342 struct dfui_dataset             *dfui_response_dataset_get_first(const struct dfui_response *);
 343 int                              dfui_response_dataset_count(const struct dfui_response *);
 344 const char                      *dfui_response_get_form_id(const struct dfui_response *);
 345 const char                      *dfui_response_get_action_id(const struct dfui_response *);
 346
 347 struct dfui_progress            *dfui_progress_new(struct dfui_info *, int);
 348 void                             dfui_progress_free(struct dfui_progress *);
 349 struct dfui_info                *dfui_progress_get_info(const struct dfui_progress *);
 350 void                             dfui_progress_set_amount(struct dfui_progress *, int);
 351 int                              dfui_progress_get_amount(const struct dfui_progress *);
 352 void                             dfui_progress_set_streaming(struct dfui_progress *, int);
 353 int                              dfui_progress_get_streaming(const struct dfui_progress *);
 354 void                             dfui_progress_set_msg_line(struct dfui_progress *, const char *);
 355 const char                      *dfui_progress_get_msg_line(const struct dfui_progress *);
 356
 357 void                             dfui_payload_free(struct dfui_payload *);
 358 char                             dfui_payload_get_msg_type(const struct dfui_payload *);
 359 struct dfui_form                *dfui_payload_get_form(const struct dfui_payload *);
 360 struct dfui_progress            *dfui_payload_get_progress(const struct dfui_payload *);
 361
 362 /*
 363  * PROTOCOL
 364  */
 365
 366 struct dfui_connection  *dfui_connection_new(int, const char *);
 367 void                     dfui_connection_free(struct dfui_connection *);
 368
 369 /*
 370  * BACKEND VERY HIGH LEVEL INTERFACE
 371  */
 372
 373 int                      dfui_be_present_dialog(struct dfui_connection *,
 374                              const char *, const char *, const char *, ...)
 375                              __printflike(4, 5);
 376
 377 /*
 378  * BACKEND HIGH LEVEL INTERFACE
 379  */
 380 dfui_err_t              dfui_be_start(struct dfui_connection *);
 381 dfui_err_t              dfui_be_stop(struct dfui_connection *);
 382
 383 dfui_err_t              dfui_be_present(struct dfui_connection *,
 384                                         struct dfui_form *, struct dfui_response **);
 385 dfui_err_t              dfui_be_progress_begin(struct dfui_connection *,
 386                                                 struct dfui_progress *);
 387 dfui_err_t              dfui_be_progress_update(struct dfui_connection *,
 388                                                 struct dfui_progress *, int *);
 389 dfui_err_t              dfui_be_progress_end(struct dfui_connection *);
 390
 391 dfui_err_t              dfui_be_set_global_setting(struct dfui_connection *,
 392                                                    const char *, const char *, int *);
 393
 394 /*
 395  * FRONTEND HIGH LEVEL INTERFACE
 396  */
 397 dfui_err_t              dfui_fe_connect(struct dfui_connection *);
 398 dfui_err_t              dfui_fe_disconnect(struct dfui_connection *);
 399
 400 dfui_err_t              dfui_fe_receive(struct dfui_connection *, char *, void **);
 401 struct dfui_payload    *dfui_fe_receive_payload(struct dfui_connection *);
 402 dfui_err_t              dfui_fe_submit(struct dfui_connection *, struct dfui_response *);
 403 dfui_err_t              dfui_fe_progress_continue(struct dfui_connection *);
 404 dfui_err_t              dfui_fe_progress_cancel(struct dfui_connection *);
 405 dfui_err_t              dfui_fe_confirm_set_global(struct dfui_connection *);
 406 dfui_err_t              dfui_fe_cancel_set_global(struct dfui_connection *);
 407 dfui_err_t              dfui_fe_confirm_stop(struct dfui_connection *);
 408 dfui_err_t              dfui_fe_abort(struct dfui_connection *);
 409
 410 DFUI_ENDDECLS
 411
 412 #endif /* !__DFUI_H */