Struct jack::Client

pub struct Client<T: JackHandler> { /* fields omitted */ }

A client to interact with a Jack server.

Example

// TODO: make example

Methods

impl<T: JackHandler> Client<T>

fn name_size() -> usize

The maximum length of the Jack client name string. Unlike the "C" Jack API, this does not take into account the final NULL character and instead corresponds directly to .len(). This value is constant.

unsafe fn type_buffer_size(&self, port_type: &str) -> usize

The buffer size of a port type

Unsafe

• This function may only be called in a buffer size callback.

fn open(client_name: &str, options: ClientOptions) -> Result<Self, JackErr>

Opens a Jack client with the given name and options. If the client is successfully opened, then Ok(client) is returned. If there is a failure, then Err(JackErr::ClientError(status)) will be returned.

Although the client may be successful in opening, there still may be some errors minor errors when attempting to opening. To access these, check Client::status().

fn close(self)

Disconnects the client from the Jack server. This does not need to manually be called, as the client will automatically close when the client object is dropped.

fn status(&self) -> ClientStatus

Get the status of the client.

fn name<'a>(&'a self) -> &'a str

Get the name of the current client. This may differ from the name requested by Client::open as Jack will may rename a client if necessary (ie: name collision, name too long). If the name has changed, it should be indicated by Client::status.

fn uuid<'a>(&'a self) -> &'a str

Get the uuid of the current client.

fn thread_id<P>(&self) -> P

Get the pthread ID of the thread running the Jack client side code.

TODO

• Integrate a pthread library
• Implement, do people need this though?

fn name_by_uuid<'a>(&'a self, uuid: &str) -> Option<&'a str>

Get the name of the client with the UUID specified by uuid. If the client is found then Some(name) is returned, if not, then None is returned.

fn uuid_by_name<'a>(&'a self, name: &str) -> Option<&'a str>

Get the uuid of the client with the name specified by name. If the client is found then Some(uuid) is returned, if not, then None is returned.

fn ports(&self, port_name_pattern: Option<&str>, type_name_pattern: Option<&str>, flags: PortFlags) -> Vec<String>

Returns a vector of ports that match the specified arguments

port_name_pattern - A regular expression used to select ports by name. If None or zero lengthed, no selection based on name will be carried out.

type_name_pattern - A regular expression used to select ports by type. If None or zero lengthed, no selection based on type will be carried out.

flags - A value used to select ports by their flags. Use PortFlags::empty() for no flag selection.

fn port_by_name(&self, port_name: &str) -> Option<Port>

Get a Port by its port name.

fn port_by_id(&self, port_id: u32) -> Option<Port>

Get a Port by its port id.

fn activate(&mut self, handler: T) -> Result<(), JackErr>

Tell the Jack server that the program is ready to start processing audio. Jack will call the methods specified by the JackHandler trait, from handler.

On failure, either Err(JackErr::CallbackRegistrationError) or Err(JackErr::ClientActivationError) is returned.

handler is consumed, but it is returned when Client::deactivate is called.

fn deactivate(&mut self) -> Result<Box<T>, JackErr>

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.

The handler that was used for Client::activate is returned on success. Its state may have changed due to Jack calling its methods.

fn register_port(&mut self, port_name: &str, port_type: &str, flags: PortFlags, buffer_size: Option<usize>) -> Result<Port, JackErr>

Create a new port for the client. This is an object used for moving data of any type in or out of the client. Ports may be connected in various ways.

Each port has a short name. The port's full name contains the name of the client concatenated with a colon (:) followed by its short name. Port::name_size() is the maximum length of the full name. Exceeding that will cause the port registration to fail and return Err(()).

The port_name must be unique among all ports owned by this client. If the name is not unique, the registration will fail.

All ports have a type, which may be any non empty string, passed as an argument. Some port types are built into the Jack API, like DEFAULT_AUDIO_TYPE and DEFAULT_MIDI_TYPE.

Parameters

port_name - non-empty short name for the new port (not including the lading "client_name:"). Must be unique.

port_type - port type name. If longer than Port::type_size(), only that many characters are significant.

flags - PortFlags bit mask.

buffer_size - Must be Some(n) if this is not a built-in port_type. Otherwise, it is ignored.

fn is_mine(&self, port: &Port) -> bool

Returns true if the port port belongs to this client.

fn request_monitor(&self, port_name: &str, enable_monitor: bool) -> Result<(), JackErr>

Toggle input monitoring for the port with name port_name.

Err(JackErr::PortMonitorError) is returned on failure.

Only works if the port has the CAN_MONITOR flag, or else nothing happens.

fn connect_ports(&self, source_port: &str, destination_port: &str) -> Result<(), JackErr>

Establish a connection between two ports.

When a connection exists, data written to the source port will be available to be read at the destination port.

On failure, either a PortNotFound or PortConnectionError is returned.

Preconditions

1. The port types must be identical
2. The port flags of the source_port must include IS_OUTPUT
3. The port flags of the destination_port must include IS_INPUT.

fn disconnect_ports(&self, source_port: &str, destination_port: &str) -> Result<(), JackErr>

Remove a connection between two ports.

fn sample_rate(&self) -> usize

The sample rate of the jack system, as set by the user when jackd was started.

fn buffer_size(&self) -> usize

The current maximum size that will every be passed to the process callback.

It should only be used before the client has been activated. This size may change,c lients that depend on it must register a buffer size callback so they will be notified if it does.

fn cpu_load(&self) -> f32

The current CPU load estimated by Jack.

This is a running average of the time it takes to execute a full process cycle for all clients as a percentage of the real time available per cycle determined by the buffer size and sample rate.

fn set_freewheel(&self, enable: bool) -> Result<(), JackErr>

Start/Stop Jack's "freewheel" mode.

When in "freewheel" mode, Jack no longer waits for any external event to begin the start of the next process cycle. As a result, freewheel mode causes "faster than real-time" execution of a Jack graph. If possessed, real-time scheduling is dropped when entering freewheel mode, and if appropriate it is reacquired when stopping.

IMPORTANT: on systems using capabilities to provide real-time scheduling (i.e. Linux Kernel 2.4), if enabling freewheel, this function must be called from the thread that originally called self.activate(). This restriction does not apply to other systems (e.g. Linux Kernel 2.6 or OS X).

fn set_buffer_size(&self, n_frames: usize) -> Result<(), JackErr>

Change the buffer size passed to the process callback.

This operation stops the jack engine process cycle, then calls all registered buffer size callback functions before restarting the process cycle. This will cause a gap in the audio flow, so it should only be done at appropriate stopping points.

fn frames_since_cycle_start(&self) -> u32

The estimated time in frames that has passed since the Jack server began the current process cycle.

fn frame_time(&self) -> u32

The estimated current time in frames. This function is intended for use in other threads (not the process callback). The return value can be compared with the value of last_frame_time to relate time in other threads to Jack time.

fn last_frame_time(&self) -> u32

The precise time at the start of the current process cycle. This function may only be used from the process callback, and can be used to interpret timestamps generated by self.frame_time() in other threads, with respect to the current process cycle.

fn cycle_times(&self) -> Result<CycleTimes, JackErr>

This function may only be used from the process callback. It provides the internal cycle timing information as used by most of the other time related functions. This allows the caller to map between frame counts and microseconds with full precision (i.e. without rounding frame times to integers), and also provides e.g. the microseconds time of the start of the current cycle directly (it has to be computed otherwise).

Err(JackErr::TimeError) is returned on failure.

fn frames_to_time(&self, n_frames: u32) -> u64

The estimated time in microseconds of the specified frame time

fn time_to_frames(&self, t: u64) -> u32

The estimated time in frames for the specified system time.

Trait Implementations

impl<T: Debug + JackHandler> Debug for Client<T>

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: JackHandler> Drop for Client<T>

Closes the client, no need to manually call Client::close().

fn drop(&mut self)

A method called when the value goes out of scope.