common/jack/control.h

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