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_CAPS     1
  72 #define DFUI_TRANSPORT_NPIPE    2
  73 #define DFUI_TRANSPORT_TCP      3
  74
  75 /*
  76  * Message types.
  77  */
  78
  79 #define DFUI_BE_MSG_READY       'r'     /* send me back a reply please */
  80
  81 #define DFUI_BE_MSG_STOP        'X'     /* shut down please, we're done */
  82 #define DFUI_BE_MSG_PRESENT     'P'     /* present this form to the user */
  83 #define DFUI_BE_MSG_PROG_BEGIN  'b'     /* begin showing a progress bar */
  84 #define DFUI_BE_MSG_PROG_UPDATE 'u'     /* update the progress bar */
  85 #define DFUI_BE_MSG_PROG_END    'e'     /* stop showing the progress bar */
  86
  87 #define DFUI_BE_MSG_SET_GLOBAL  'G'     /* set a global setting in the f/e */
  88
  89 #define DFUI_FE_MSG_READY       'r'     /* send me a form or something */
  90
  91 #define DFUI_FE_MSG_SUBMIT      'S'     /* submit results of a form */
  92 #define DFUI_FE_MSG_CONTINUE    'c'     /* nothing stopping a progress bar */
  93 #define DFUI_FE_MSG_CANCEL      'C'     /* user cancelled a progress bar */
  94 #define DFUI_FE_MSG_ABORT       'X'     /* something catastrophic (^C?) */
  95
  96 /*
  97  * STRUCTURE PROTOTYPES
  98  */
  99
 100 struct dfui_connection;
 101 struct dfui_payload;
 102 struct dfui_info;
 103 struct dfui_property;
 104 struct dfui_dataset;
 105 struct dfui_celldata;
 106 struct dfui_form;
 107 struct dfui_field;
 108 struct dfui_option;
 109 struct dfui_action;
 110 struct dfui_response;
 111 struct dfui_progress;
 112
 113 /*
 114  * STRUCTURE DEFINITIONS
 115  */
 116
 117 #ifdef NEEDS_DFUI_STRUCTURE_DEFINITIONS
 118
 119 /* Connections */
 120
 121 struct dfui_connection {
 122         int transport;            /* transport layer: CAPS, NPIPE, or TCP */
 123         char *rendezvous;         /* rendezvous point */
 124         struct aura_buffer *ebuf; /* last message recvd */
 125         int is_connected;         /* was a connection actually established? */
 126         void *t_data;             /* transport-specific connection data */
 127
 128         dfui_err_t (*be_start)(struct dfui_connection *);
 129         dfui_err_t (*be_stop)(struct dfui_connection *);
 130         dfui_err_t (*be_ll_exchange)(struct dfui_connection *, char, const char *);
 131
 132         dfui_err_t (*fe_connect)(struct dfui_connection *);
 133         dfui_err_t (*fe_disconnect)(struct dfui_connection *);
 134
 135         dfui_err_t (*fe_ll_request)(struct dfui_connection *, char, const char *);
 136 };
 137
 138 /* Common structures on objects */
 139
 140 struct dfui_info {
 141         char *name;
 142         char *short_desc;
 143         char *long_desc;
 144 };
 145
 146 struct dfui_dataset {
 147         struct dfui_dataset *next;
 148         struct dfui_celldata *celldata_head;
 149 };
 150
 151 struct dfui_celldata {
 152         struct dfui_celldata *next;
 153         char *field_id;
 154         char *value;
 155 };
 156
 157 /*
 158  * Properties may be either strong (imply a behavioural guarantee from
 159  * the frontend) or weak (may be ignored or interpreted subjectively
 160  * by the frontend) depending on their name.  Currently only the
 161  * following properties are strong:
 162  *
 163  *   editable
 164  *   obscured
 165  */
 166 struct dfui_property {
 167         struct dfui_property *next;
 168         char *name;
 169         char *value;
 170 };
 171
 172 /* Form objects */
 173
 174 struct dfui_form {
 175         char *id;
 176         struct dfui_info *info;
 177         int multiple;
 178         int extensible;
 179         struct dfui_field *field_head;
 180         struct dfui_action *action_head;
 181         struct dfui_dataset *dataset_head;
 182         struct dfui_property *property_head;
 183 };
 184
 185 struct dfui_field {
 186         char *id;
 187         struct dfui_info *info;
 188         struct dfui_field *next;
 189         struct dfui_option *option_head;
 190         struct dfui_property *property_head;
 191 };
 192
 193 struct dfui_option {
 194         char *value;
 195         struct dfui_option *next;
 196 };
 197
 198 struct dfui_action {
 199         char *id;
 200         struct dfui_info *info;
 201         struct dfui_action *next;
 202         struct dfui_property *property_head;
 203 };
 204
 205 /* Progress objects */
 206
 207 struct dfui_progress {
 208         struct dfui_info *info;
 209         int amount;
 210         int streaming;          /* if 1, msg will stream in line by line */
 211         char *msg_line;         /* next line of message if streaming=1 */
 212 };
 213
 214 /* Response objects */
 215
 216 struct dfui_response {
 217         char *form_id;
 218         char *action_id;
 219         struct dfui_dataset *dataset_head;
 220 };
 221
 222 /* Payload objects */
 223
 224 struct dfui_payload {
 225         char msgtype;
 226         struct dfui_form *form;
 227         struct dfui_progress *progress;
 228         struct dfui_property *global_setting;
 229 };
 230
 231 #endif /* NEEDS_DFUI_STRUCTURE_DEFINITIONS */
 232
 233 /*
 234  * PROTOTYPES
 235  */
 236
 237 /*
 238  * UTILITY (form/field creation, etc)
 239  */
 240
 241 struct dfui_info                *dfui_info_new(const char *, const char *, const char *);
 242 void                             dfui_info_free(struct dfui_info *);
 243 const char                      *dfui_info_get_name(const struct dfui_info *);
 244 const char                      *dfui_info_get_short_desc(const struct dfui_info *);
 245 const char                      *dfui_info_get_long_desc(const struct dfui_info *);
 246 void                             dfui_info_set_name(struct dfui_info *, const char *);
 247 void                             dfui_info_set_short_desc(struct dfui_info *, const char *);
 248 void                             dfui_info_set_long_desc(struct dfui_info *, const char *);
 249
 250 struct dfui_property            *dfui_property_new(const char *, const char *);
 251 void                             dfui_property_free(struct dfui_property *);
 252 void                             dfui_properties_free(struct dfui_property *);
 253 struct dfui_property            *dfui_property_find(struct dfui_property *, const char *);
 254 const char                      *dfui_property_get(struct dfui_property *, const char *);
 255 struct dfui_property            *dfui_property_set(struct dfui_property **, const char *, const char *);
 256 const char                      *dfui_property_get_name(const struct dfui_property *);
 257 const char                      *dfui_property_get_value(const struct dfui_property *);
 258
 259 struct dfui_celldata            *dfui_celldata_new(const char *, const char *);
 260 void                             dfui_celldata_free(struct dfui_celldata *);
 261 void                             dfui_celldatas_free(struct dfui_celldata *);
 262 struct dfui_celldata            *dfui_celldata_find(struct dfui_celldata *, const char *);
 263 struct dfui_celldata            *dfui_celldata_get_next(const struct dfui_celldata *);
 264 const char *                     dfui_celldata_get_field_id(const struct dfui_celldata *);
 265 const char *                     dfui_celldata_get_value(const struct dfui_celldata *);
 266
 267 struct dfui_dataset             *dfui_dataset_new(void);
 268 struct dfui_dataset             *dfui_dataset_dup(const struct dfui_dataset *);
 269 void                             dfui_dataset_free(struct dfui_dataset *);
 270 void                             dfui_datasets_free(struct dfui_dataset *);
 271 struct dfui_celldata            *dfui_dataset_celldata_add(struct dfui_dataset *,
 272                                         const char *, const char *);
 273 struct dfui_celldata            *dfui_dataset_celldata_get_first(const struct dfui_dataset *);
 274 struct dfui_celldata            *dfui_dataset_celldata_find(const struct dfui_dataset *, const char *);
 275 struct dfui_dataset             *dfui_dataset_get_next(const struct dfui_dataset *);
 276 const char                      *dfui_dataset_get_value(const struct dfui_dataset *, const char *);
 277 char                            *dfui_dataset_dup_value(const struct dfui_dataset *, const char *);
 278
 279 struct dfui_field               *dfui_field_new(const char *, struct dfui_info *);
 280 void                             dfui_field_free(struct dfui_field *);
 281 void                             dfui_fields_free(struct dfui_field *);
 282 struct dfui_option              *dfui_field_option_add(struct dfui_field *, const char *);
 283 struct dfui_option              *dfui_field_option_get_first(const struct dfui_field *);
 284 struct dfui_property            *dfui_field_property_set(struct dfui_field *, const char *, const char *);
 285 const char                      *dfui_field_property_get(const struct dfui_field *, const char *);
 286 int                              dfui_field_property_is(const struct dfui_field *, const char *, const char *);
 287 struct dfui_field               *dfui_field_get_next(const struct dfui_field *);
 288 const char                      *dfui_field_get_id(const struct dfui_field *);
 289 struct dfui_info                *dfui_field_get_info(const struct dfui_field *);
 290
 291 struct dfui_option              *dfui_option_new(const char *);
 292 void                             dfui_option_free(struct dfui_option *);
 293 void                             dfui_options_free(struct dfui_option *);
 294 struct dfui_option              *dfui_option_get_next(const struct dfui_option *);
 295 const char                      *dfui_option_get_value(const struct dfui_option *);
 296
 297 struct dfui_action              *dfui_action_new(const char *, struct dfui_info *);
 298 void                             dfui_action_free(struct dfui_action *);
 299 void                             dfui_actions_free(struct dfui_action *);
 300 struct dfui_action              *dfui_action_get_next(const struct dfui_action *);
 301 struct dfui_property            *dfui_action_property_set(struct dfui_action *, const char *, const char *);
 302 const char                      *dfui_action_property_get(const struct dfui_action *, const char *);
 303 int                              dfui_action_property_is(const struct dfui_action *, const char *, const char *);
 304 const char                      *dfui_action_get_id(const struct dfui_action *);
 305 struct dfui_info                *dfui_action_get_info(const struct dfui_action *);
 306
 307 struct dfui_form                *dfui_form_new(const char *, struct dfui_info *);
 308 struct dfui_form                *dfui_form_create(const char *, const char *, const char *, const char *, ...);
 309 void                             dfui_form_free(struct dfui_form *);
 310 struct dfui_field               *dfui_form_field_add(struct dfui_form *,
 311                                         const char *, struct dfui_info *);
 312 struct dfui_field               *dfui_form_field_attach(struct dfui_form *,
 313                                         struct dfui_field *);
 314 struct dfui_action              *dfui_form_action_add(struct dfui_form *,
 315                                         const char *, struct dfui_info *);
 316 struct dfui_action              *dfui_form_action_attach(struct dfui_form *,
 317                                         struct dfui_action *);
 318 void                             dfui_form_dataset_add(struct dfui_form *,
 319                                         struct dfui_dataset *);
 320 struct dfui_dataset             *dfui_form_dataset_get_first(const struct dfui_form *);
 321 int                              dfui_form_dataset_count(const struct dfui_form *);
 322 void                             dfui_form_datasets_free(struct dfui_form *);
 323 struct dfui_property            *dfui_form_property_set(struct dfui_form *, const char *, const char *);
 324 const char                      *dfui_form_property_get(const struct dfui_form *, const char *);
 325 int                              dfui_form_property_is(const struct dfui_form *, const char *, const char *);
 326 struct dfui_field               *dfui_form_field_find(const struct dfui_form *, const char *);
 327 struct dfui_field               *dfui_form_field_get_first(const struct dfui_form *);
 328 int                              dfui_form_field_count(const struct dfui_form *);
 329 struct dfui_action              *dfui_form_action_find(const struct dfui_form *, const char *);
 330 struct dfui_action              *dfui_form_action_get_first(const struct dfui_form *);
 331 int                              dfui_form_action_count(const struct dfui_form *);
 332 const char                      *dfui_form_get_id(const struct dfui_form *);
 333 struct dfui_info                *dfui_form_get_info(const struct dfui_form *);
 334 void                             dfui_form_set_multiple(struct dfui_form *, int);
 335 int                              dfui_form_is_multiple(const struct dfui_form *);
 336 void                             dfui_form_set_extensible(struct dfui_form *, int);
 337 int                              dfui_form_is_extensible(const struct dfui_form *);
 338
 339 struct dfui_response            *dfui_response_new(const char *, const char *);
 340 void                             dfui_response_free(struct dfui_response *);
 341 void                             dfui_response_dataset_add(struct dfui_response *,
 342                                         struct dfui_dataset *);
 343 struct dfui_dataset             *dfui_response_dataset_get_first(const struct dfui_response *);
 344 int                              dfui_response_dataset_count(const struct dfui_response *);
 345 const char                      *dfui_response_get_form_id(const struct dfui_response *);
 346 const char                      *dfui_response_get_action_id(const struct dfui_response *);
 347
 348 struct dfui_progress            *dfui_progress_new(struct dfui_info *, int);
 349 void                             dfui_progress_free(struct dfui_progress *);
 350 struct dfui_info                *dfui_progress_get_info(const struct dfui_progress *);
 351 void                             dfui_progress_set_amount(struct dfui_progress *, int);
 352 int                              dfui_progress_get_amount(const struct dfui_progress *);
 353 void                             dfui_progress_set_streaming(struct dfui_progress *, int);
 354 int                              dfui_progress_get_streaming(const struct dfui_progress *);
 355 void                             dfui_progress_set_msg_line(struct dfui_progress *, const char *);
 356 const char                      *dfui_progress_get_msg_line(const struct dfui_progress *);
 357
 358 void                             dfui_payload_free(struct dfui_payload *);
 359 char                             dfui_payload_get_msg_type(const struct dfui_payload *);
 360 struct dfui_form                *dfui_payload_get_form(const struct dfui_payload *);
 361 struct dfui_progress            *dfui_payload_get_progress(const struct dfui_payload *);
 362
 363 /*
 364  * PROTOCOL
 365  */
 366
 367 struct dfui_connection  *dfui_connection_new(int, const char *);
 368 void                     dfui_connection_free(struct dfui_connection *);
 369
 370 /*
 371  * BACKEND VERY HIGH LEVEL INTERFACE
 372  */
 373
 374 int                      dfui_be_present_dialog(struct dfui_connection *,
 375                              const char *, const char *, const char *, ...)
 376                              __printflike(4, 5);
 377
 378 /*
 379  * BACKEND HIGH LEVEL INTERFACE
 380  */
 381 dfui_err_t              dfui_be_start(struct dfui_connection *);
 382 dfui_err_t              dfui_be_stop(struct dfui_connection *);
 383
 384 dfui_err_t              dfui_be_present(struct dfui_connection *,
 385                                         struct dfui_form *, struct dfui_response **);
 386 dfui_err_t              dfui_be_progress_begin(struct dfui_connection *,
 387                                                 struct dfui_progress *);
 388 dfui_err_t              dfui_be_progress_update(struct dfui_connection *,
 389                                                 struct dfui_progress *, int *);
 390 dfui_err_t              dfui_be_progress_end(struct dfui_connection *);
 391
 392 dfui_err_t              dfui_be_set_global_setting(struct dfui_connection *,
 393                                                    const char *, const char *, int *);
 394
 395 /*
 396  * FRONTEND HIGH LEVEL INTERFACE
 397  */
 398 dfui_err_t              dfui_fe_connect(struct dfui_connection *);
 399 dfui_err_t              dfui_fe_disconnect(struct dfui_connection *);
 400
 401 dfui_err_t              dfui_fe_receive(struct dfui_connection *, char *, void **);
 402 struct dfui_payload    *dfui_fe_receive_payload(struct dfui_connection *);
 403 dfui_err_t              dfui_fe_submit(struct dfui_connection *, struct dfui_response *);
 404 dfui_err_t              dfui_fe_progress_continue(struct dfui_connection *);
 405 dfui_err_t              dfui_fe_progress_cancel(struct dfui_connection *);
 406 dfui_err_t              dfui_fe_confirm_set_global(struct dfui_connection *);
 407 dfui_err_t              dfui_fe_cancel_set_global(struct dfui_connection *);
 408 dfui_err_t              dfui_fe_confirm_stop(struct dfui_connection *);
 409 dfui_err_t              dfui_fe_abort(struct dfui_connection *);
 410
 411 DFUI_ENDDECLS
 412
 413 #endif /* !__DFUI_H */