1 /* -*- Mode: C ; c-basic-offset: 4 -*- */ 2 /* 3 JACK control API 4 5 Copyright (C) 2008 Nedko Arnaudov 6 Copyright (C) 2008 GRAME 7 8 This program is free software; you can redistribute it and/or modify 9 it under the terms of the GNU General Public License as published by 10 the Free Software Foundation; version 2 of the License. 11 12 This program is distributed in the hope that it will be useful, 13 but WITHOUT ANY WARRANTY; without even the implied warranty of 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 GNU General Public License for more details. 16 17 You should have received a copy of the GNU General Public License 18 along with this program; if not, write to the Free Software 19 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 20 21 */ 22 /** 23 * @file jack/control.h 24 * @ingroup publicheader 25 * @brief JACK control API 26 * 27 */ 28 29 #ifndef JACKCTL_H__2EEDAD78_DF4C_4B26_83B7_4FF1A446A47E__INCLUDED 30 #define JACKCTL_H__2EEDAD78_DF4C_4B26_83B7_4FF1A446A47E__INCLUDED 31 32 #include <jack/types.h> 33 #include <jack/jslist.h> 34 #include <jack/systemdeps.h> 35 #if !defined(sun) && !defined(__sun__) 36 #include <stdbool.h> 37 #endif 38 39 /** Parameter types, intentionally similar to jack_driver_param_type_t */ 40 typedef enum 41 { 42 JackParamInt = 1, /**< @brief value type is a signed integer */ 43 JackParamUInt, /**< @brief value type is an unsigned integer */ 44 JackParamChar, /**< @brief value type is a char */ 45 JackParamString, /**< @brief value type is a string with max size of ::JACK_PARAM_STRING_MAX+1 chars */ 46 JackParamBool, /**< @brief value type is a boolean */ 47 } jackctl_param_type_t; 48 49 /** Driver types */ 50 typedef enum 51 { 52 JackMaster = 1, /**< @brief master driver */ 53 JackSlave /**< @brief slave driver */ 54 } jackctl_driver_type_t; 55 56 /** @brief Max value that jackctl_param_type_t type can have */ 57 #define JACK_PARAM_MAX (JackParamBool + 1) 58 59 /** @brief Max length of string parameter value, excluding terminating null char */ 60 #define JACK_PARAM_STRING_MAX 127 61 62 /** @brief Type for parameter value */ 63 /* intentionally similar to jack_driver_param_value_t */ 64 union jackctl_parameter_value 65 { 66 uint32_t ui; /**< @brief member used for ::JackParamUInt */ 67 int32_t i; /**< @brief member used for ::JackParamInt */ 68 char c; /**< @brief member used for ::JackParamChar */ 69 char str[JACK_PARAM_STRING_MAX + 1]; /**< @brief member used for ::JackParamString */ 70 bool b; /**< @brief member used for ::JackParamBool */ 71 }; 72 73 /** opaque type for server object */ 74 typedef struct jackctl_server jackctl_server_t; 75 76 /** opaque type for driver object */ 77 typedef struct jackctl_driver jackctl_driver_t; 78 79 /** opaque type for internal client object */ 80 typedef struct jackctl_internal jackctl_internal_t; 81 82 /** opaque type for parameter object */ 83 typedef struct jackctl_parameter jackctl_parameter_t; 84 85 /** opaque type for sigmask object */ 86 typedef struct jackctl_sigmask jackctl_sigmask_t; 87 88 #ifdef __cplusplus 89 extern "C" { 90 #endif 91 #if 0 92 } /* Adjust editor indent */ 93 #endif 94 95 /** 96 * @defgroup ControlAPI The API for starting and controlling a JACK server 97 * @{ 98 */ 99 100 /** 101 * Call this function to setup process signal handling. As a general 102 * rule, it is required for proper operation for the server object. 103 * 104 * @param flags signals setup flags, use 0 for none. Currently no 105 * flags are defined 106 * 107 * @return the configurated signal set. 108 */ 109 jackctl_sigmask_t * 110 jackctl_setup_signals( 111 unsigned int flags); 112 113 /** 114 * Call this function to wait on a signal set. 115 * 116 * @param signals signals set to wait on 117 */ 118 void 119 jackctl_wait_signals( 120 jackctl_sigmask_t * signals); 121 122 /** 123 * \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN 124 * NEW JACK PROJECTS 125 * 126 * @deprecated Please use jackctl_server_create2(). 127 */ 128 jackctl_server_t * 129 jackctl_server_create( 130 bool (* on_device_acquire)(const char * device_name), 131 void (* on_device_release)(const char * device_name)); 132 133 /** 134 * Call this function to create server object. 135 * 136 * @param on_device_acquire - Optional callback to be called before device is acquired. If false is returned, device usage will fail 137 * @param on_device_release - Optional callback to be called after device is released. 138 * @param on_device_reservation_loop - Optional callback to be called when looping/idling the reservation. 139 * 140 * @return server object handle, NULL if creation of server object 141 * failed. Successfully created server object must be destroyed with 142 * paired call to ::jackctl_server_destroy 143 */ 144 jackctl_server_t * 145 jackctl_server_create2( 146 bool (* on_device_acquire)(const char * device_name), 147 void (* on_device_release)(const char * device_name), 148 void (* on_device_reservation_loop)(void)); 149 150 /** 151 * Call this function to destroy server object. 152 * 153 * @param server server object handle to destroy 154 */ 155 void 156 jackctl_server_destroy( 157 jackctl_server_t * server); 158 159 /** 160 * Call this function to open JACK server 161 * 162 * @param server server object handle 163 * @param driver driver to use 164 * 165 * @return success status: true - success, false - fail 166 */ 167 bool 168 jackctl_server_open( 169 jackctl_server_t * server, 170 jackctl_driver_t * driver); 171 172 /** 173 * Call this function to start JACK server 174 * 175 * @param server server object handle 176 * 177 * @return success status: true - success, false - fail 178 */ 179 bool 180 jackctl_server_start( 181 jackctl_server_t * server); 182 183 /** 184 * Call this function to stop JACK server 185 * 186 * @param server server object handle 187 * 188 * @return success status: true - success, false - fail 189 */ 190 bool 191 jackctl_server_stop( 192 jackctl_server_t * server); 193 194 /** 195 * Call this function to close JACK server 196 * 197 * @param server server object handle 198 * 199 * @return success status: true - success, false - fail 200 */ 201 bool 202 jackctl_server_close( 203 jackctl_server_t * server); 204 205 /** 206 * Call this function to get list of available drivers. List node data 207 * pointers is a driver object handle (::jackctl_driver_t). 208 * 209 * @param server server object handle to get drivers for 210 * 211 * @return Single linked list of driver object handles. Must not be 212 * modified. Always same for same server object. 213 */ 214 const JSList * 215 jackctl_server_get_drivers_list( 216 jackctl_server_t * server); 217 218 /** 219 * Call this function to get list of server parameters. List node data 220 * pointers is a parameter object handle (::jackctl_parameter_t). 221 * 222 * @param server server object handle to get parameters for 223 * 224 * @return Single linked list of parameter object handles. Must not be 225 * modified. Always same for same server object. 226 */ 227 const JSList * 228 jackctl_server_get_parameters( 229 jackctl_server_t * server); 230 231 /** 232 * Call this function to get list of available internal clients. List node data 233 * pointers is a internal client object handle (::jackctl_internal_t). 234 * 235 * @param server server object handle to get internal clients for 236 * 237 * @return Single linked list of internal client object handles. Must not be 238 * modified. Always same for same server object. 239 */ 240 const JSList * 241 jackctl_server_get_internals_list( 242 jackctl_server_t * server); 243 244 /** 245 * Call this function to load one internal client. 246 * (can be used when the server is running) 247 * 248 * @param server server object handle 249 * @param internal internal to use 250 * 251 * @return success status: true - success, false - fail 252 */ 253 bool 254 jackctl_server_load_internal( 255 jackctl_server_t * server, 256 jackctl_internal_t * internal); 257 258 /** 259 * Call this function to unload one internal client. 260 * (can be used when the server is running) 261 * 262 * @param server server object handle 263 * @param internal internal to unload 264 * 265 * @return success status: true - success, false - fail 266 */ 267 bool 268 jackctl_server_unload_internal( 269 jackctl_server_t * server, 270 jackctl_internal_t * internal); 271 272 /** 273 * Call this function to load a session file. 274 * (can be used when the server is running) 275 * 276 * @param server server object handle 277 * @param file the session file to load, containing a list of 278 * internal clients and connections to be made. 279 * 280 * @return success status: true - success, false - fail 281 */ 282 bool jackctl_server_load_session_file( 283 jackctl_server_t * server_ptr, 284 const char * file); 285 286 /** 287 * Call this function to add a slave in the driver slave list. 288 * (cannot be used when the server is running that is between 289 * jackctl_server_start and jackctl_server_stop) 290 * 291 * @param server server object handle 292 * @param driver driver to add in the driver slave list. 293 * 294 * @return success status: true - success, false - fail 295 */ 296 bool 297 jackctl_server_add_slave(jackctl_server_t * server, 298 jackctl_driver_t * driver); 299 300 /** 301 * Call this function to remove a slave from the driver slave list. 302 * (cannot be used when the server is running that is between 303 * jackctl_server_start and jackctl_server_stop) 304 * 305 * @param server server object handle 306 * @param driver driver to remove from the driver slave list. 307 * 308 * @return success status: true - success, false - fail 309 */ 310 bool 311 jackctl_server_remove_slave(jackctl_server_t * server, 312 jackctl_driver_t * driver); 313 314 /** 315 * Call this function to switch master driver. 316 * 317 * @param server server object handle 318 * @param driver driver to switch to 319 * 320 * @return success status: true - success, false - fail 321 */ 322 bool 323 jackctl_server_switch_master(jackctl_server_t * server, 324 jackctl_driver_t * driver); 325 326 327 /** 328 * Call this function to get name of driver. 329 * 330 * @param driver driver object handle to get name of 331 * 332 * @return driver name. Must not be modified. Always same for same 333 * driver object. 334 */ 335 const char * 336 jackctl_driver_get_name( 337 jackctl_driver_t * driver); 338 339 /** 340 * Call this function to get type of driver. 341 * 342 * @param driver driver object handle to get name of 343 * 344 * @return driver type. Must not be modified. Always same for same 345 * driver object. 346 */ 347 jackctl_driver_type_t 348 jackctl_driver_get_type( 349 jackctl_driver_t * driver); 350 351 /** 352 * Call this function to get list of driver parameters. List node data 353 * pointers is a parameter object handle (::jackctl_parameter_t). 354 * 355 * @param driver driver object handle to get parameters for 356 * 357 * @return Single linked list of parameter object handles. Must not be 358 * modified. Always same for same driver object. 359 */ 360 const JSList * 361 jackctl_driver_get_parameters( 362 jackctl_driver_t * driver); 363 364 /** 365 * Call this function to parse parameters for a driver. 366 * 367 * @param driver driver object handle 368 * @param argc parameter list len 369 * @param argv parameter list, as an array of char* 370 * 371 * @return success status: true - success, false - fail 372 */ 373 int 374 jackctl_driver_params_parse( 375 jackctl_driver_t * driver, 376 int argc, 377 char* argv[]); 378 379 /** 380 * Call this function to get name of internal client. 381 * 382 * @param internal internal object handle to get name of 383 * 384 * @return internal name. Must not be modified. Always same for same 385 * internal object. 386 */ 387 const char * 388 jackctl_internal_get_name( 389 jackctl_internal_t * internal); 390 391 /** 392 * Call this function to get list of internal parameters. List node data 393 * pointers is a parameter object handle (::jackctl_parameter_t). 394 * 395 * @param internal internal object handle to get parameters for 396 * 397 * @return Single linked list of parameter object handles. Must not be 398 * modified. Always same for same internal object. 399 */ 400 const JSList * 401 jackctl_internal_get_parameters( 402 jackctl_internal_t * internal); 403 404 /** 405 * Call this function to get parameter name. 406 * 407 * @param parameter parameter object handle to get name of 408 * 409 * @return parameter name. Must not be modified. Always same for same 410 * parameter object. 411 */ 412 const char * 413 jackctl_parameter_get_name( 414 jackctl_parameter_t * parameter); 415 416 /** 417 * Call this function to get parameter short description. 418 * 419 * @param parameter parameter object handle to get short description of 420 * 421 * @return parameter short description. Must not be modified. Always 422 * same for same parameter object. 423 */ 424 const char * 425 jackctl_parameter_get_short_description( 426 jackctl_parameter_t * parameter); 427 428 /** 429 * Call this function to get parameter long description. 430 * 431 * @param parameter parameter object handle to get long description of 432 * 433 * @return parameter long description. Must not be modified. Always 434 * same for same parameter object. 435 */ 436 const char * 437 jackctl_parameter_get_long_description( 438 jackctl_parameter_t * parameter); 439 440 /** 441 * Call this function to get parameter type. 442 * 443 * @param parameter parameter object handle to get type of 444 * 445 * @return parameter type. Always same for same parameter object. 446 */ 447 jackctl_param_type_t 448 jackctl_parameter_get_type( 449 jackctl_parameter_t * parameter); 450 451 /** 452 * Call this function to get parameter character. 453 * 454 * @param parameter parameter object handle to get character of 455 * 456 * @return character. 457 */ 458 char 459 jackctl_parameter_get_id( 460 jackctl_parameter_t * parameter); 461 462 /** 463 * Call this function to check whether parameter has been set, or its 464 * default value is being used. 465 * 466 * @param parameter parameter object handle to check 467 * 468 * @return true - parameter is set, false - parameter is using default 469 * value. 470 */ 471 bool 472 jackctl_parameter_is_set( 473 jackctl_parameter_t * parameter); 474 475 /** 476 * Call this function to reset parameter to its default value. 477 * 478 * @param parameter parameter object handle to reset value of 479 * 480 * @return success status: true - success, false - fail 481 */ 482 bool 483 jackctl_parameter_reset( 484 jackctl_parameter_t * parameter); 485 486 /** 487 * Call this function to get parameter value. 488 * 489 * @param parameter parameter object handle to get value of 490 * 491 * @return parameter value. 492 */ 493 union jackctl_parameter_value 494 jackctl_parameter_get_value( 495 jackctl_parameter_t * parameter); 496 497 /** 498 * Call this function to set parameter value. 499 * 500 * @param parameter parameter object handle to get value of 501 * @param value_ptr pointer to variable containing parameter value 502 * 503 * @return success status: true - success, false - fail 504 */ 505 bool 506 jackctl_parameter_set_value( 507 jackctl_parameter_t * parameter, 508 const union jackctl_parameter_value * value_ptr); 509 510 /** 511 * Call this function to get parameter default value. 512 * 513 * @param parameter parameter object handle to get default value of 514 * 515 * @return parameter default value. 516 */ 517 union jackctl_parameter_value 518 jackctl_parameter_get_default_value( 519 jackctl_parameter_t * parameter); 520 521 /** 522 * Call this function check whether parameter has range constraint. 523 * 524 * @param parameter object handle of parameter to check 525 * 526 * @return whether parameter has range constraint. 527 */ 528 bool 529 jackctl_parameter_has_range_constraint( 530 jackctl_parameter_t * parameter); 531 532 /** 533 * Call this function check whether parameter has enumeration constraint. 534 * 535 * @param parameter object handle of parameter to check 536 * 537 * @return whether parameter has enumeration constraint. 538 */ 539 bool 540 jackctl_parameter_has_enum_constraint( 541 jackctl_parameter_t * parameter); 542 543 /** 544 * Call this function get how many enumeration values parameter has. 545 * 546 * @param parameter object handle of parameter 547 * 548 * @return number of enumeration values 549 */ 550 uint32_t 551 jackctl_parameter_get_enum_constraints_count( 552 jackctl_parameter_t * parameter); 553 554 /** 555 * Call this function to get parameter enumeration value. 556 * 557 * @param parameter object handle of parameter 558 * @param index index of parameter enumeration value 559 * 560 * @return enumeration value. 561 */ 562 union jackctl_parameter_value 563 jackctl_parameter_get_enum_constraint_value( 564 jackctl_parameter_t * parameter, 565 uint32_t index); 566 567 /** 568 * Call this function to get parameter enumeration value description. 569 * 570 * @param parameter object handle of parameter 571 * @param index index of parameter enumeration value 572 * 573 * @return enumeration value description. 574 */ 575 const char * 576 jackctl_parameter_get_enum_constraint_description( 577 jackctl_parameter_t * parameter, 578 uint32_t index); 579 580 /** 581 * Call this function to get parameter range. 582 * 583 * @param parameter object handle of parameter 584 * @param min_ptr pointer to variable receiving parameter minimum value 585 * @param max_ptr pointer to variable receiving parameter maximum value 586 */ 587 void 588 jackctl_parameter_get_range_constraint( 589 jackctl_parameter_t * parameter, 590 union jackctl_parameter_value * min_ptr, 591 union jackctl_parameter_value * max_ptr); 592 593 /** 594 * Call this function to check whether parameter constraint is strict, 595 * i.e. whether supplying non-matching value will not work for sure. 596 * 597 * @param parameter parameter object handle to check 598 * 599 * @return whether parameter constraint is strict. 600 */ 601 bool 602 jackctl_parameter_constraint_is_strict( 603 jackctl_parameter_t * parameter); 604 605 /** 606 * Call this function to check whether parameter has fake values, 607 * i.e. values have no user meaningful meaning and only value 608 * description is meaningful to user. 609 * 610 * @param parameter parameter object handle to check 611 * 612 * @return whether parameter constraint is strict. 613 */ 614 bool 615 jackctl_parameter_constraint_is_fake_value( 616 jackctl_parameter_t * parameter); 617 618 /** 619 * Call this function to log an error message. 620 * 621 * @param format string 622 */ 623 void 624 jack_error( 625 const char *format, 626 ...); 627 628 /** 629 * Call this function to log an information message. 630 * 631 * @param format string 632 */ 633 void 634 jack_info( 635 const char *format, 636 ...); 637 638 /** 639 * Call this function to log an information message but only when 640 * verbose mode is enabled. 641 * 642 * @param format string 643 */ 644 void 645 jack_log( 646 const char *format, 647 ...); 648 649 /* @} */ 650 651 #if 0 652 { /* Adjust editor indent */ 653 #endif 654 #ifdef __cplusplus 655 } /* extern "C" */ 656 #endif 657 658 #endif /* #ifndef JACKCTL_H__2EEDAD78_DF4C_4B26_83B7_4FF1A446A47E__INCLUDED */ 659