1 /* 2 Copyright (C) 2003 Bob Ham <rah@bash.sh> 3 Copyright (C) 2008 Nedko Arnaudov <nedko@arnaudov.name> 4 5 This program is free software; you can redistribute it and/or modify 6 it under the terms of the GNU Lesser General Public License as published by 7 the Free Software Foundation; either version 2.1 of the License, or 8 (at your option) any later version. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU Lesser General Public License for more details. 14 15 You should have received a copy of the GNU Lesser General Public License 16 along with this program; if not, write to the Free Software 17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 18 19 */ 20 21 #ifndef __jack_driver_interface_h__ 22 #define __jack_driver_interface_h__ 23 24 #ifdef __cplusplus 25 extern "C" 26 { 27 #endif 28 29 #include <limits.h> 30 #include "jslist.h" 31 32 #include "JackCompilerDeps.h" 33 #include "JackSystemDeps.h" 34 35 #define JACK_DRIVER_NAME_MAX 15 36 #define JACK_DRIVER_PARAM_NAME_MAX 15 37 #define JACK_DRIVER_PARAM_STRING_MAX 127 38 #define JACK_DRIVER_PARAM_DESC 255 39 #define JACK_PATH_MAX 511 40 41 #define JACK_CONSTRAINT_FLAG_RANGE ((uint32_t)1) /**< if set, constraint is a range (min-max) */ 42 #define JACK_CONSTRAINT_FLAG_STRICT ((uint32_t)2) /**< if set, constraint is strict, i.e. supplying non-matching value will not work */ 43 #define JACK_CONSTRAINT_FLAG_FAKE_VALUE ((uint32_t)4) /**< if set, values have no user meaningful meaning */ 44 45 /** Driver parameter types */ 46 typedef enum 47 { 48 JackDriverParamInt = 1, 49 JackDriverParamUInt, 50 JackDriverParamChar, 51 JackDriverParamString, 52 JackDriverParamBool 53 } jack_driver_param_type_t; 54 55 /** Driver types */ 56 typedef enum 57 { 58 JackDriverMaster = 1, 59 JackDriverSlave, 60 JackDriverNone, 61 } jack_driver_type_t; 62 63 /** Driver parameter value */ 64 typedef union 65 { 66 uint32_t ui; 67 int32_t i; 68 char c; 69 char str[JACK_DRIVER_PARAM_STRING_MAX + 1]; 70 } jack_driver_param_value_t; 71 72 typedef struct { 73 jack_driver_param_value_t value; 74 char short_desc[64]; /**< A short (~30 chars) description for the user */ 75 } jack_driver_param_value_enum_t; 76 77 struct jack_constraint_enum_uint32_descriptor { 78 uint32_t value; 79 const char * short_desc; 80 }; 81 82 struct jack_constraint_enum_sint32_descriptor { 83 int32_t value; 84 const char * short_desc; 85 }; 86 87 struct jack_constraint_enum_char_descriptor { 88 char value; 89 const char * short_desc; 90 }; 91 92 struct jack_constraint_enum_str_descriptor { 93 const char * value; 94 const char * short_desc; 95 }; 96 97 typedef struct { 98 uint32_t flags; /**< JACK_CONSTRAINT_FLAG_XXX */ 99 union { 100 struct { 101 jack_driver_param_value_t min; 102 jack_driver_param_value_t max; 103 } range; /**< valid when JACK_CONSTRAINT_FLAG_RANGE flag is set */ 104 105 struct { 106 uint32_t count; 107 jack_driver_param_value_enum_t * possible_values_array; 108 } enumeration; /**< valid when JACK_CONSTRAINT_FLAG_RANGE flag is not set */ 109 } constraint; 110 } jack_driver_param_constraint_desc_t; 111 112 /** A driver parameter descriptor */ 113 typedef struct { 114 char name[JACK_DRIVER_NAME_MAX + 1]; /**< The parameter's name */ 115 char character; /**< The parameter's character (for getopt, etc) */ 116 jack_driver_param_type_t type; /**< The parameter's type */ 117 jack_driver_param_value_t value; /**< The parameter's (default) value */ 118 jack_driver_param_constraint_desc_t * constraint; /**< Pointer to parameter constraint descriptor. NULL if there is no constraint */ 119 char short_desc[64]; /**< A short (~30 chars) description for the user */ 120 char long_desc[1024]; /**< A longer description for the user */ 121 } 122 jack_driver_param_desc_t; 123 124 /** A driver parameter */ 125 typedef struct { 126 char character; 127 jack_driver_param_value_t value; 128 } 129 jack_driver_param_t; 130 131 /** A struct for describing a jack driver */ 132 typedef struct { 133 char name[JACK_DRIVER_NAME_MAX + 1]; /**< The driver's canonical name */ 134 jack_driver_type_t type; /**< The driver's type */ 135 char desc[JACK_DRIVER_PARAM_DESC + 1]; /**< The driver's extended description */ 136 #ifdef WIN32 137 wchar_t file[JACK_PATH_MAX + 1]; /**< The filename of the driver's shared object file */ 138 #else 139 char file[JACK_PATH_MAX + 1]; /**< The filename of the driver's shared object file */ 140 #endif 141 uint32_t nparams; /**< The number of parameters the driver has */ 142 jack_driver_param_desc_t * params; /**< An array of parameter descriptors */ 143 } 144 jack_driver_desc_t; 145 146 typedef struct { 147 uint32_t size; /* size of the param array, in elements */ 148 } 149 jack_driver_desc_filler_t; 150 151 int jack_parse_driver_params(jack_driver_desc_t * desc, int argc, char* argv[], JSList ** param_ptr); 152 153 // To be used by drivers 154 155 SERVER_EXPORT jack_driver_desc_t * /* Newly allocated driver descriptor, NULL on failure */ 156 jack_driver_descriptor_construct( 157 const char * name, /* Driver name */ 158 jack_driver_type_t type, /* Driver type */ 159 const char * description, /* Driver description */ 160 jack_driver_desc_filler_t * filler); /* Pointer to stack var to be supplied to jack_driver_descriptor_add_parameter() as well. 161 Can be NULL for drivers that have no parameters. */ 162 163 SERVER_EXPORT int /* 0 on failure */ 164 jack_driver_descriptor_add_parameter( 165 jack_driver_desc_t * driver_descr, /* Pointer to driver descriptor as returned by jack_driver_descriptor_construct() */ 166 jack_driver_desc_filler_t * filler, /* Pointer to the stack var that was supplied to jack_driver_descriptor_add_parameter(). */ 167 const char * name, /* Parameter's name */ 168 char character, /* Parameter's character (for getopt, etc) */ 169 jack_driver_param_type_t type, /* The parameter's type */ 170 const jack_driver_param_value_t * value_ptr, /* Pointer to parameter's (default) value */ 171 jack_driver_param_constraint_desc_t * constraint, /* Pointer to parameter constraint descriptor. NULL if there is no constraint */ 172 const char * short_desc, /* A short (~30 chars) description for the user */ 173 const char * long_desc); /* A longer description for the user, if NULL short_desc will be used */ 174 175 SERVER_EXPORT 176 int jack_constraint_add_enum( 177 jack_driver_param_constraint_desc_t ** constraint_ptr_ptr, 178 uint32_t * array_size_ptr, 179 jack_driver_param_value_t * value_ptr, 180 const char * short_desc); 181 182 SERVER_EXPORT 183 void jack_constraint_free(jack_driver_param_constraint_desc_t * constraint_ptr); 184 185 #define JACK_CONSTRAINT_COMPOSE_ENUM(type) \ 186 SERVER_EXPORT \ 187 jack_driver_param_constraint_desc_t * \ 188 jack_constraint_compose_enum_ ## type( \ 189 uint32_t flags, \ 190 struct jack_constraint_enum_ ## type ## _descriptor * descr_array_ptr) 191 192 JACK_CONSTRAINT_COMPOSE_ENUM(uint32); 193 JACK_CONSTRAINT_COMPOSE_ENUM(sint32); 194 JACK_CONSTRAINT_COMPOSE_ENUM(char); 195 JACK_CONSTRAINT_COMPOSE_ENUM(str); 196 197 typedef jack_driver_desc_t * (*JackDriverDescFunction) (); 198 199 #ifdef __cplusplus 200 } 201 #endif 202 203 #endif /* __jack_driver_interface_h__ */ 204 205 206