lsp-alsa/libasound-config.lsp

   1 ;; == Configuration Interface
   2 ; https://alsa-project.org/alsa-doc/alsa-lib/group___config.html
   3
   4 ;; Type: snd_config_t
   5 ; This is an opaque internal struct for configuration nodes. The ALSA
   6 ; library uses pointers to this structure as handles to configuration
   7 ; nodes. Applications don't access contents directly.
   8
   9 ;; Type: snd_config_update_t
  10 ; This is an opaque internal struct for configuration private update
  11 ; objects. The ALSA library uses this structure to save private update
  12 ; information.
  13
  14 ;; Type: snd_config_iterator_t
  15 ; This is a pointer to the opaque struct type used for configuration
  16 ; compound iterators. The ALSA library uses these as handles for
  17 ; configuration compound iterators. Applications don't access contents
  18 ; directly.
  19
  20 ;; Enum: snd_config_type_t
  21 (constant
  22  'SND_CONFIG_TYPE_INTEGER 0
  23  'SND_CONFIG_TYPE_INTEGER64 1
  24  'SND_CONFIG_TYPE_REAL 2
  25  'SND_CONFIG_TYPE_STRING 3
  26  'SND_CONFIG_TYPE_POINTER 4
  27  'SND_CONFIG_TYPE_COMPOUND 1024
  28  )
  29
  30 ;; Type snd_devname_t
  31 (struct 'snd_devname_t
  32         "char*" ; char * name
  33         "char*" ; char * comment
  34         "void*" ; snd_devname_t * next
  35  )
  36
  37 ;; Variable: snd_config_t *snd_config
  38 ; Holds the ALSA configuration tree.
  39 (import LIB "snd_config")
  40 (define (snd_config@)
  41   ((unpack "Lu" (address snd_config)) 0))
  42
  43 ;; Function: int snd_config_update()
  44 ; Updates variable snd_config by rereading the global configuration
  45 ; files (if needed).
  46 (import LIB "snd_config_update" "int" "void")
  47 (when (< (setf E (snd_config_update)))
  48   (die 1 "** Cannot load the ALSA configuration tree: " E)
  49   )
  50
  51 ;; Function: int snd_config_expand
  52 ;; [in] snd_config_t *node = Handle to the expansion node
  53 ;; [in] snd_config_t *root = Handle to the configuration root node
  54 ;; [in] const char *args = Arguments string, can be NULL (last must be null)
  55 ;; [in] snd_config_t *private_data = Handle to private data node for functions
  56 ;; [out] snd_config_t **result
  57 ; Expands a configuration node, applying arguments and functions. If
  58 ; config has arguments (defined by a child with id @args), this
  59 ; function replaces any string node beginning with $ with the
  60 ; respective argument value, or the default argument value, or
  61 ; nothing. Furthermore, any functions are evaluated (see
  62 ; snd_config_evaluate). The resulting copy of config is returned in
  63 ; result.
  64 ;
  65 ; Returns a non-negative value if successful, otherwise a negative
  66 ; error code.
  67 ;
  68 ; The import is wrapped to return the result pointer or (negative)
  69 ; error code.
  70 (import** LIB "snd_config_expand"
  71           "int" ; int snd_config_expand
  72           "void*" ; snd_config_t *config
  73           "void*" ; snd_config_t *root
  74           "void*" ; const char *args
  75           "void*" ; snd_config_t *private_data
  76           ()      ; snd_config_t **result
  77           )
  78
  79 ;; Function: int snd_config_evaluate
  80 ;; [in,out] snd_config_t *node = node in root to evaluate
  81 ;; [in] snd_config_t *root = configuration root
  82 ;; [in] snd_config_t *private_data
  83 ;; [*] snd_config_t **result = must be null!
  84 ; Evaluates a configuration node at runtime. This function evaluates
  85 ; any functions (@func) in config and replaces those nodes with the
  86 ; respective function results. Returns a non-negative value if
  87 ; successful, otherwise a negative error code.
  88 (import LIB "snd_config_evaluate"
  89         "int" ; int snd_config_evaluate
  90         "void*" ; snd_config_t *config
  91         "void*" ; snd_config_t *root
  92         "void*" ;snd_config_t *private_data
  93         "void*" ;snd_config_t **result
  94         )
  95
  96 ;; Function: int snd_config_search
  97 ;; [in] snd_config_t *config = root of the configuration (sub)tree to search
  98 ;; [in] const char *key = one or more node ids, separated with dots
  99 ;; [out] snd_config_t **result
 100 ; This function searches for a child node of config that is identified
 101 ; by key, which contains either the id of a direct child node of
 102 ; config, or a series of ids, separated with dots, where each id
 103 ; specifies a node that is contained in the previous compound node.
 104 ;; Returns 0 on success.
 105 (import LIB "snd_config_search"
 106         "int" ; int snd_config_search
 107         "void*" ; snd_config_t *config
 108         "char*" ; const char *key
 109         "void*" ; snd_config_t **result
 110         )
 111
 112 ;; Term: (snd_config_get_id NODE)
 113 ; Returns the id string for a configuration node.
 114 ;
 115 ;; Function: int snd_config_get_id(char** id)
 116 ;; [in] const snd_config_t *config - Handle to the configuration node.
 117 ;; [out] config, const char **value - node id
 118 ; Returns 0 if successful, otherwise a negative error code. The
 119 ; returned string is owned by the configuration node; the application
 120 ; must not modify or delete it, and the string becomes invalid when
 121 ; the node's id changes or when the node is freed. If the node does
 122 ; not have an id, *id is set to NULL.
 123 ;
 124 ; The import is wrapped to return the id string or (negative) error
 125 ; code.
 126 (import** LIB "snd_config_get_id"
 127           "int" ;; int snd_config_get_id
 128           "void*"           ; [in] const snd_config_t *config,
 129           (get-string-safe) ; [out] const char **id
 130           )
 131
 132 ;; Function: int snd_config_get_integer(snd_config_t *node,int *value)
 133 ; Returns the value of an integer ("lu") configuration node.
 134 ;
 135 ; @param node - the configuration node concerned.
 136 ;
 137 ; @param value - pointer for the return value.
 138 ;
 139 ; The import is wrapped to return the integer as such, or (negative)
 140 ; error code.
 141 (import** LIB "snd_config_get_integer"
 142           "int" ; int snd_config_get_integer
 143           "void*" ; const snd_config_t *config,
 144           () ; long *value
 145           )
 146
 147 ;; Function: int snd_config_get_integer64
 148 ; [in] snd_config_t *config
 149 ; [out] int64_t *value
 150 ;
 151 ; Returns the value of a 64-bit-integer ("Lu") configuration node.
 152 ;
 153 ; The import is wrapped to return the integer as such, or (negative)
 154 ; error code.
 155 (import** LIB "snd_config_get_integer64"
 156           "int" ; int snd_config_get_integer64
 157           "void*" ; const snd_config_t *config,
 158           () ; long long *value
 159           )
 160
 161 ;; Function: int snd_config_get_real
 162 ;; [in] const snd_config_t *node
 163 ;; [out] double *value
 164 ;
 165 ; Returns the value of a real-number configuration node.
 166 ;
 167 ; The import is wrapped to return the double as such, or (negative)
 168 ; error code.
 169 (import** LIB "snd_config_get_real"
 170           "int" ; int snd_config_get_real
 171           "void*" ; const snd_config_t *node,
 172           ("lf") ; double *value
 173           )
 174
 175 ; Returns the value of a real or integer configuration node as double.
 176 ; API function to return the double as such, or (negative) error code.
 177 (import** LIB "snd_config_get_ireal"
 178           "int" ; int snd_config_get_real
 179           "void*" ; const snd_config_t *config,
 180           ("lf") ; double *value)
 181           )
 182
 183 ; Returns the value of a string configuration node. The returned
 184 ; string is owned by the configuration node; the application must not
 185 ; modify or delete it, and the string becomes invalid when the node's
 186 ; value changes or when the node is freed.
 187 ;
 188 ;; API function to return the string (copied), or (negative) error
 189 ;; code.
 190 (import** LIB "snd_config_get_string"
 191           "int" ; int snd_config_get_string (
 192           "void*" ; const snd_config_t *config,
 193           (get-string) ; const char **value)
 194           )
 195
 196 ; Changes the value of a string configuration node. function deletes
 197 ; the old string in the node and stores a copy of value string in the
 198 ; node. Returns 0 if successful, otherwise a negative error code.
 199 (import LIB "snd_config_set_string"
 200         "int" ; int snd_config_set_string(
 201         "void*" ; snd_config_t *config,
 202         "char*" ; const char *value )
 203         )
 204
 205 ;; int  snd_config_get_ascii (const snd_config_t *config, char **value)
 206 ; Returns the value of a configuration node as a string. This function
 207 ; dynamically allocates the returned string. The application is
 208 ; responsible for deleting it with free() when it is no longer used.
 209 ; For a string node with NULL value, the returned string is NULL.
 210
 211 ; Returns the value of a pointer configuration node.
 212 ;
 213 ;; API function to return the pointer (value), or (negative) error.
 214 (import** LIB "snd_config_get_pointer"
 215           "int" ; int snd_config_get_pointer (
 216           "void*" ; const snd_config_t *config,
 217           () ; const void **value)
 218         )
 219
 220 ; Returns the type of a configuration node.
 221 (import LIB "snd_config_get_type"
 222         "unsigned int" ; snd_config_type_t snd_config_get_type
 223         "void*" ; const snd_config_t *config
 224         )
 225
 226 ; Returns count of items in array, zero when the compound is not an
 227 ; array, otherwise a negative error code.
 228 (import LIB "snd_config_is_array"
 229         "int" ; int snd_config_is_array
 230         "void*" ; const snd_config_t *config
 231         )
 232
 233 ;; ------- iterator functions --------
 234
 235 ; Returns an iterator pointing to a node's first child. More...
 236 (import LIB "snd_config_iterator_first"
 237         "void*" ;; snd_config_iterator_t snd_config_iterator_first
 238         "void*" ; const snd_config_t *node
 239         )
 240
 241 ; Returns an iterator pointing to the next sibling. More...
 242 (import LIB "snd_config_iterator_next"
 243         "void*" ; snd_config_iterator_t snd_config_iterator_next
 244         "void*" ; const snd_config_iterator_t iterator
 245         )
 246
 247 ; Returns an iterator that ends a node's children list.
 248 ;; Parameters
 249 ; [in]  config  Handle to a configuration node.
 250 ;;
 251 ; Returns n iterator that indicates the end of config's children list.
 252 ; config must be a compound node. The return value can be understood
 253 ; as pointing past the last child of config.
 254 (import LIB "snd_config_iterator_end"
 255         "void*" ; snd_config_iterator_t snd_config_iterator_end
 256         "void*" ; const snd_config_t *config
 257         )
 258
 259 ; Returns the configuration node handle pointed to by an iterator.
 260 (import LIB "snd_config_iterator_entry"
 261         "void*" ; snd_config_t * snd_config_iterator_entry
 262         "void*" ; const snd_config_iterator_t iterator
 263         )
 264
 265 ;;
 266
 267 ;;======================================================================
 268 ; Extended API
 269
 270 ;; Term: (iterate NODE)
 271 ; Make a list of a compound node's children by iterating over them.
 272 (define (iterate NODE)
 273   (let ((CUR (snd_config_iterator_first NODE))
 274         (END (snd_config_iterator_end NODE))
 275         (RES '()))
 276     (while (!= CUR END)
 277       (push (traverse (snd_config_iterator_entry CUR)) RES -1)
 278       (setf CUR (snd_config_iterator_next CUR)))
 279     (if (snd_config_is_array NODE)
 280         (map list (sequence 0 (- (length RES) 1)) RES)
 281       RES)))
 282
 283 ;; Term: (traverse NODE)
 284 ; Return the pair (ID value) for a node. The value of a compound node
 285 ; is the list of its child nodes.
 286 (define (traverse NODE)
 287   (let ((TYPE (snd_config_get_type NODE))
 288         (ID (snd_config_get_id NODE)))
 289     (list ID
 290           (case TYPE
 291             (0 (snd_config_get_integer NODE))
 292             (1 (snd_config_get_integer64 NODE))
 293             (2 (snd_config_get_real NODE))
 294             (3 (snd_config_get_string NODE))
 295             (4 (snd_config_get_integer NODE))
 296             (5 (sym (string ">" (snd_config_get_pointer NODE))))
 297             (1024 (iterate NODE))
 298             (true (list 'unknown NODE TYPE))))))
 299
 300 "libasound-config.lsp"