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