;; == Configuration Interface
; https://alsa-project.org/alsa-doc/alsa-lib/group___config.html

;; Type: snd_config_t
; This is an opaque internal struct for configuration nodes. The ALSA
; library uses pointers to this structure as handles to configuration
; nodes. Applications don't access contents directly.

;; Type: snd_config_update_t
; This is an opaque internal struct for configuration private update
; objects. The ALSA library uses this structure to save private update
; information.

;; Type: snd_config_iterator_t
; This is a pointer to the opaque struct type used for configuration
; compound iterators. The ALSA library uses these as handles for
; configuration compound iterators. Applications don't access contents
; directly.

;; Enum: snd_config_type_t
(constant
 'SND_CONFIG_TYPE_INTEGER 0
 'SND_CONFIG_TYPE_INTEGER64 1
 'SND_CONFIG_TYPE_REAL 2
 'SND_CONFIG_TYPE_STRING 3
 'SND_CONFIG_TYPE_POINTER 4
 'SND_CONFIG_TYPE_COMPOUND 1024
 )

;; Type snd_devname_t
(struct 'snd_devname_t
        "char*" ; char * name
        "char*" ; char * comment
        "void*" ; snd_devname_t * next
 )

;; Variable: snd_config_t *snd_config
; Holds the ALSA configuration tree.
(import LIB "snd_config")
(define (snd_config@)
  ((unpack "Lu" (address snd_config)) 0))

;; Function: int snd_config_update()
; Updates variable snd_config by rereading the global configuration
; files (if needed).
(import LIB "snd_config_update" "int" "void")
(when (< (setf E (snd_config_update)))
  (die 1 "** Cannot load the ALSA configuration tree: " E)
  )

;; Function: int snd_config_expand
;; [in] snd_config_t *node = Handle to the expansion node
;; [in] snd_config_t *root = Handle to the configuration root node
;; [in] const char *args = Arguments string, can be NULL (last must be null)
;; [in] snd_config_t *private_data = Handle to private data node for functions
;; [out] snd_config_t **result
; Expands a configuration node, applying arguments and functions. If
; config has arguments (defined by a child with id @args), this
; function replaces any string node beginning with $ with the
; respective argument value, or the default argument value, or
; nothing. Furthermore, any functions are evaluated (see
; snd_config_evaluate). The resulting copy of config is returned in
; result.
;
; Returns a non-negative value if successful, otherwise a negative
; error code.
;
; The import is wrapped to return the result pointer or (negative)
; error code.
(import** LIB "snd_config_expand"
          "int" ; int snd_config_expand
	  "void*" ; snd_config_t *config
          "void*" ; snd_config_t *root
          "void*" ; const char *args
          "void*" ; snd_config_t *private_data
          ()      ; snd_config_t **result
          )

;; Function: int snd_config_evaluate
;; [in,out] snd_config_t *node = node in root to evaluate
;; [in] snd_config_t *root = configuration root
;; [in] snd_config_t *private_data
;; [*] snd_config_t **result = must be null!
; Evaluates a configuration node at runtime. This function evaluates
; any functions (@func) in config and replaces those nodes with the
; respective function results. Returns a non-negative value if
; successful, otherwise a negative error code.
(import LIB "snd_config_evaluate"
        "int" ; int snd_config_evaluate
        "void*" ; snd_config_t *config
        "void*" ; snd_config_t *root
        "void*" ;snd_config_t *private_data
        "void*" ;snd_config_t **result 
        )

;; Function: int snd_config_search
;; [in] snd_config_t *config = root of the configuration (sub)tree to search
;; [in] const char *key = one or more node ids, separated with dots
;; [out] snd_config_t **result
; This function searches for a child node of config that is identified
; by key, which contains either the id of a direct child node of
; config, or a series of ids, separated with dots, where each id
; specifies a node that is contained in the previous compound node.
;; Returns 0 on success.
(import LIB "snd_config_search"
	"int" ; int snd_config_search
	"void*" ; snd_config_t *config
        "char*" ; const char *key
        "void*" ; snd_config_t **result
        )

;; Term: (snd_config_get_id NODE)
; Returns the id string for a configuration node.
;
;; Function: int snd_config_get_id(char** id)
;; [in] const snd_config_t *config - Handle to the configuration node.
;; [out] config, const char **value - node id
; Returns 0 if successful, otherwise a negative error code. The
; returned string is owned by the configuration node; the application
; must not modify or delete it, and the string becomes invalid when
; the node's id changes or when the node is freed. If the node does
; not have an id, *id is set to NULL.
;
; The import is wrapped to return the id string or (negative) error
; code.
(import** LIB "snd_config_get_id"
          "int" ;; int snd_config_get_id
          "void*"           ; [in] const snd_config_t *config,
          (get-string-safe) ; [out] const char **id
          )

;; Function: int snd_config_get_integer(snd_config_t *node,int *value)
; Returns the value of an integer ("lu") configuration node.
;
; @param node - the configuration node concerned.
;
; @param value - pointer for the return value.
; 
; The import is wrapped to return the integer as such, or (negative)
; error code.
(import** LIB "snd_config_get_integer"
          "int" ; int snd_config_get_integer
          "void*" ; const snd_config_t *config,
          () ; long *value
          )

;; Function: int snd_config_get_integer64
; [in] snd_config_t *config
; [out] int64_t *value
;
; Returns the value of a 64-bit-integer ("Lu") configuration node.
; 
; The import is wrapped to return the integer as such, or (negative)
; error code.
(import** LIB "snd_config_get_integer64"
          "int" ; int snd_config_get_integer64
          "void*" ; const snd_config_t *config,
          () ; long long *value
          )

;; Function: int snd_config_get_real
;; [in] const snd_config_t *node
;; [out] double *value
;
; Returns the value of a real-number configuration node.
;
; The import is wrapped to return the double as such, or (negative)
; error code.
(import** LIB "snd_config_get_real"
          "int" ; int snd_config_get_real
          "void*" ; const snd_config_t *node,
          ("lf") ; double *value
          )

; Returns the value of a real or integer configuration node as double.
; API function to return the double as such, or (negative) error code.
(import** LIB "snd_config_get_ireal"
          "int" ; int snd_config_get_real
          "void*" ; const snd_config_t *config,
          ("lf") ; double *value)
          )

; Returns the value of a string configuration node. The returned
; string is owned by the configuration node; the application must not
; modify or delete it, and the string becomes invalid when the node's
; value changes or when the node is freed.
;
;; API function to return the string (copied), or (negative) error
;; code.
(import** LIB "snd_config_get_string"
          "int" ; int snd_config_get_string (
          "void*" ; const snd_config_t *config,
          (get-string) ; const char **value)
          )

; Changes the value of a string configuration node. function deletes
; the old string in the node and stores a copy of value string in the
; node. Returns 0 if successful, otherwise a negative error code.
(import LIB "snd_config_set_string"
	"int" ; int snd_config_set_string(
	"void*" ; snd_config_t *config,
        "char*" ; const char *value )
        )

;; int 	snd_config_get_ascii (const snd_config_t *config, char **value)
; Returns the value of a configuration node as a string. This function
; dynamically allocates the returned string. The application is
; responsible for deleting it with free() when it is no longer used.
; For a string node with NULL value, the returned string is NULL.

; Returns the value of a pointer configuration node.
;
;; API function to return the pointer (value), or (negative) error.
(import** LIB "snd_config_get_pointer"
          "int" ; int snd_config_get_pointer (
          "void*" ; const snd_config_t *config,
          () ; const void **value)
        )

; Returns the type of a configuration node.
(import LIB "snd_config_get_type"
        "unsigned int" ; snd_config_type_t snd_config_get_type
        "void*" ; const snd_config_t *config
        )

; Returns count of items in array, zero when the compound is not an
; array, otherwise a negative error code.
(import LIB "snd_config_is_array"
        "int" ; int snd_config_is_array
        "void*" ; const snd_config_t *config
        )

;; ------- iterator functions --------

; Returns an iterator pointing to a node's first child. More...
(import LIB "snd_config_iterator_first"
        "void*" ;; snd_config_iterator_t snd_config_iterator_first
        "void*" ; const snd_config_t *node
        )

; Returns an iterator pointing to the next sibling. More...
(import	LIB "snd_config_iterator_next"
        "void*" ; snd_config_iterator_t snd_config_iterator_next
        "void*" ; const snd_config_iterator_t iterator
        )

; Returns an iterator that ends a node's children list.
;; Parameters
; [in]	config	Handle to a configuration node.
;;
; Returns n iterator that indicates the end of config's children list.
; config must be a compound node. The return value can be understood
; as pointing past the last child of config.
(import LIB "snd_config_iterator_end"
        "void*" ; snd_config_iterator_t snd_config_iterator_end
	"void*" ; const snd_config_t *config
        )

; Returns the configuration node handle pointed to by an iterator.
(import LIB "snd_config_iterator_entry"
        "void*" ; snd_config_t * snd_config_iterator_entry
        "void*" ; const snd_config_iterator_t iterator
        )

;;

;;======================================================================
; Extended API

;; Term: (iterate NODE)
; Make a list of a compound node's children by iterating over them.
(define (iterate NODE)
  (let ((CUR (snd_config_iterator_first NODE))
        (END (snd_config_iterator_end NODE))
        (RES '()))
    (while (!= CUR END)
      (push (traverse (snd_config_iterator_entry CUR)) RES -1)
      (setf CUR (snd_config_iterator_next CUR)))
    (if (snd_config_is_array NODE)
        (map list (sequence 0 (- (length RES) 1)) RES)
      RES)))

;; Term: (traverse NODE)
; Return the pair (ID value) for a node. The value of a compound node
; is the list of its child nodes.
(define (traverse NODE)
  (let ((TYPE (snd_config_get_type NODE))
        (ID (snd_config_get_id NODE)))
    (list ID
          (case TYPE
            (0 (snd_config_get_integer NODE))
            (1 (snd_config_get_integer64 NODE))
            (2 (snd_config_get_real NODE))
            (3 (snd_config_get_string NODE))
            (4 (snd_config_get_integer NODE))
            (5 (sym (string ">" (snd_config_get_pointer NODE))))
            (1024 (iterate NODE))
            (true (list 'unknown NODE TYPE))))))

"libasound-config.lsp"