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 */ 413