(**
  * Bindings to the jack audio connexion kit.
  *
  * @author Samuel Mimram
  *)

(* $Id: jack.mli 2604 2006-07-07 09:35:43Z smimram $ *)

(** Set the callback function called on error, with the error message as
  * argument.
  *)
val set_error_function : (string -> unit) -> unit

val get_sample_size : unit -> int

(** Lock-free ringbuffers. **)
module Ringbuffer : sig
  (** Type for ringbuffers. *)
  type t

  (** Create a ringbuffer of the specified size (in bytes). *)
  val create : int -> t

  (** [read rb buf ofs len] try to read [len] bytes in the ringbuffer [rb] and
    * put them in [buf] starting at position [ofs]. The actual number of bytes
    * read is returned.
    *)
  val read : t -> string -> int -> int -> int

  (** Advance the read pointer. *)
  val read_advance : t -> int -> unit

  (** Get the number of bytes available for reading. *)
  val read_space : t -> int

  (** Reset the read and write pointers, making an empty buffer. *)
  val reset : t -> unit

  (** [write rb buf ofs len] tries to take [len] bytes in [buf], starting at
    * position [ofs], and put them in the ringbuffer [rb]. The actual number of
    * bytes written is returned.
    *)
  val write : t -> string -> int -> int -> int

  (** Advance the write pointer. *)
  val write_advance : t -> int -> unit

  (** Get the numbfer of bytes available for writing. *)
  val write_space : t -> int
end

(** Jack ports. *)
module Port :
sig
  (** Type for ports. *)
  type t

  (** Get the full name of a port (including the "client_name:" prefix). *)
  val name : t -> string

  (** Get the short  name of a port (not including the "client_name:" prefix). *)
  val short_name : t -> string

  type flags =
    | Input
    | Output
    | Pysical
    | Can_monitor
    | Terminal

  val flags : t -> flags list

  (** Get port type. *)
  val port_type : t -> string

  val connected : t -> int

  val connected_to : t -> string -> bool
end

(** Jack clients. *)
module Client :
sig
  (** Type for jack clients. *)
  type t

  (** Create a new jack client with a given name. *)
  val create : string -> t

  (** Close a jack client. *)
  val close : t -> unit

  (** Check if the jack system is running in realtime mode (-R). *)
  val is_realtime : t -> bool

  val get_max_buffer_size : t -> int

  type direction = Read | Write

  val set_process_ringbuffer_callback : t -> (Port.t * Ringbuffer.t * direction) list -> unit

  val sync : t -> unit

  (** Tell the Jack server that the client is ready to start processing audio. *)
  val activate : t -> unit

  (** Tell the Jack server to remove this client from the process graph. Also,
    * disconnect all ports belonging to it, since inactive clients have no port
    * connections.
    *)
  val deactivate : t -> unit

  val on_shutdown : t -> (unit -> unit) -> unit

  val register_port : t -> string -> string -> Port.flags list -> int -> Port.t

  val get_sample_rate : t -> int
end