Struct JackConnection 

pub struct JackConnection<T> { /* private fields */ }

A connection to a JACK server (known as a “client” in the JACK docs).

Exists in two types: JackConnection<Activated> when activate() has been called (i.e. audio is being processed), and <Deactivated> when this has not happened, or deactivate() has been called.

Implementations

impl<T> JackConnection<T>

pub fn as_ptr(&self) -> *const jack_client_t

pub fn sample_rate(&self) -> jack_nframes_t

Get the sample rate of the JACK server.

pub fn cpu_load(&self) -> c_float

Get the CPU load of the JACK server.

pub fn buffer_size(&self) -> jack_nframes_t

Get the buffer size passed to the process() callback.

pub fn set_buffer_size(&mut self, bufsize: jack_nframes_t) -> JackResult<()>

Change the buffer size passed to the process() callback.

This operation stops the JACK engine process cycle, then calls all registered bufsize_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.

Parameters

• bufsize: new buffer size. Must be a power of two.

Errors

• NotPowerOfTwo: if the new buffer size isn’t a power of two
• UnknownErrorCode

pub fn connect_ports( &mut self, from: &JackPort, to: &JackPort, ) -> JackResult<()>

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.

Preconditions

• The port types must be identical.
• The JackPortFlags of the source_port must include PORT_IS_OUTPUT.
• The JackPortFlags of the destination_port must include PORT_IS_INPUT.

Errors

• InvalidPortType: when the types are not identical
• InvalidPortFlags: when the flags do not satisfy the preconditions above
• UnknownErrorCode

Examples found in repository

examples/sawtooth.rs (line 43)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("Very Annoying Sawtooth Generator", None)?;
    let out1 = conn.register_port("output_1", PORT_IS_OUTPUT)?;
    let out2 = conn.register_port("output_2", PORT_IS_OUTPUT)?;
    let data = Sawtooth {
        out1: out1,
        out2: out2,
        left_saw: 0.0,
        right_saw: 0.0
    };
    conn.set_handler(data)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 2 {
        conn.connect_ports(&out1, &ports[0])?;
        conn.connect_ports(&out2, &ports[1])?;
    }
    thread::sleep(::std::time::Duration::new(5, 0));
    Ok(())
}

examples/simple_client.rs (line 34)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("simple_client", None)?;
    let inp = conn.register_port("input", PORT_IS_INPUT)?;
    let out = conn.register_port("output", PORT_IS_OUTPUT)?;
    let ports = Ports {
        inp: inp,
        out: out
    };
    conn.set_handler(ports)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&out, &ports[0])?;
        println!("Connected output port to {}", ports[0].get_name(false)?);
    }
    let ports = conn.get_ports(None, None, Some(PORT_IS_OUTPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&ports[0], &inp)?;
        println!("Connected input port to {}", ports[0].get_name(false)?);
    }
    thread::sleep(::std::time::Duration::new(60 * 60, 0));
    Ok(())
}

pub fn disconnect_ports( &mut self, from: &JackPort, to: &JackPort, ) -> JackResult<()>

Remove 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.

Preconditions

• The port types must be identical.
• The JackPortFlags of the source_port must include PORT_IS_OUTPUT.
• The JackPortFlags of the destination_port must include PORT_IS_INPUT.

Errors

• InvalidPortType: when the types are not identical
• InvalidPortFlags: when the flags do not satisfy the preconditions above
• UnknownErrorCode

pub fn get_port_by_name(&self, name: &str) -> JackResult<JackPort>

Get a port from the JACK server by its name.

Errors

• PortNotFound: if no port with that name was found
• NulError: if any &str argument contains a NUL byte (\0).

pub fn get_ports( &self, port_filter: Option<&str>, type_filter: Option<&str>, flags_filter: Option<JackPortFlags>, ) -> JackResult<Vec<JackPort>>

Get all (or a selection of) ports available in the JACK server.

Parameters

• port_filter: A regular expression used to select ports by name. If None, no selection based on name will be carried out.
• type_filter: A regular expression used to select ports by type. If None, no selection based on type will be carried out.
• flags_filter: A value used to select ports by their flags. If None, no selection based on flags will be carried out.

Errors

• NulError: if any &str argument contains a NUL byte (\0).
• ProgrammerError: if I’ve made a mistake, or your program is utterly degenerate

Examples found in repository

examples/sawtooth.rs (line 41)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("Very Annoying Sawtooth Generator", None)?;
    let out1 = conn.register_port("output_1", PORT_IS_OUTPUT)?;
    let out2 = conn.register_port("output_2", PORT_IS_OUTPUT)?;
    let data = Sawtooth {
        out1: out1,
        out2: out2,
        left_saw: 0.0,
        right_saw: 0.0
    };
    conn.set_handler(data)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 2 {
        conn.connect_ports(&out1, &ports[0])?;
        conn.connect_ports(&out2, &ports[1])?;
    }
    thread::sleep(::std::time::Duration::new(5, 0));
    Ok(())
}

examples/simple_client.rs (line 32)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("simple_client", None)?;
    let inp = conn.register_port("input", PORT_IS_INPUT)?;
    let out = conn.register_port("output", PORT_IS_OUTPUT)?;
    let ports = Ports {
        inp: inp,
        out: out
    };
    conn.set_handler(ports)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&out, &ports[0])?;
        println!("Connected output port to {}", ports[0].get_name(false)?);
    }
    let ports = conn.get_ports(None, None, Some(PORT_IS_OUTPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&ports[0], &inp)?;
        println!("Connected input port to {}", ports[0].get_name(false)?);
    }
    thread::sleep(::std::time::Duration::new(60 * 60, 0));
    Ok(())
}

pub fn register_port( &mut self, name: &str, ty: JackPortFlags, ) -> JackResult<JackPort>

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. The jack_port_name_size() is the maximum length of this full name. Exceeding that will cause the port registration to fail and return ProgrammerError.

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-NULL and non-zero length string, passed as an argument. Some port types are built into the JACK API, like JACK_DEFAULT_AUDIO_TYPE or JACK_DEFAULT_MIDI_TYPE. [By default, sqa-jack makes a JACK_DEFAULT_AUDIO_TYPE port - this will be changeable in later releases.]

Errors

• NulError: if any &str argument contains a NUL byte (\0).
• PortRegistrationFailed: if port registration failed (TODO: why could this happen?)

Examples found in repository

examples/sawtooth.rs (line 28)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("Very Annoying Sawtooth Generator", None)?;
    let out1 = conn.register_port("output_1", PORT_IS_OUTPUT)?;
    let out2 = conn.register_port("output_2", PORT_IS_OUTPUT)?;
    let data = Sawtooth {
        out1: out1,
        out2: out2,
        left_saw: 0.0,
        right_saw: 0.0
    };
    conn.set_handler(data)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 2 {
        conn.connect_ports(&out1, &ports[0])?;
        conn.connect_ports(&out2, &ports[1])?;
    }
    thread::sleep(::std::time::Duration::new(5, 0));
    Ok(())
}

examples/simple_client.rs (line 21)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("simple_client", None)?;
    let inp = conn.register_port("input", PORT_IS_INPUT)?;
    let out = conn.register_port("output", PORT_IS_OUTPUT)?;
    let ports = Ports {
        inp: inp,
        out: out
    };
    conn.set_handler(ports)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&out, &ports[0])?;
        println!("Connected output port to {}", ports[0].get_name(false)?);
    }
    let ports = conn.get_ports(None, None, Some(PORT_IS_OUTPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&ports[0], &inp)?;
        println!("Connected input port to {}", ports[0].get_name(false)?);
    }
    thread::sleep(::std::time::Duration::new(60 * 60, 0));
    Ok(())
}

pub fn unregister_port(&mut self, port: JackPort) -> JackResult<()>

Remove the port from the client, disconnecting any existing connections.

Errors

• PortNotMine: if you deregister a port that this client doesn’t own
• InvalidPort
• UnknownErrorCode

impl JackConnection<Deactivated>

pub fn connect( client_name: &str, opts: Option<JackOpenOptions>, ) -> JackResult<Self>

Open an external client session with a JACK server, optionally specifying a number of JackOpenOptions.

Errors

• JackOpenFailed(status): if the connection could not be opened. Contains a JackStatus detailing what went wrong.
• NulError: if any &str argument contains a NUL byte (\0).

Examples found in repository

examples/sawtooth.rs (line 27)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("Very Annoying Sawtooth Generator", None)?;
    let out1 = conn.register_port("output_1", PORT_IS_OUTPUT)?;
    let out2 = conn.register_port("output_2", PORT_IS_OUTPUT)?;
    let data = Sawtooth {
        out1: out1,
        out2: out2,
        left_saw: 0.0,
        right_saw: 0.0
    };
    conn.set_handler(data)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 2 {
        conn.connect_ports(&out1, &ports[0])?;
        conn.connect_ports(&out2, &ports[1])?;
    }
    thread::sleep(::std::time::Duration::new(5, 0));
    Ok(())
}

examples/simple_client.rs (line 20)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("simple_client", None)?;
    let inp = conn.register_port("input", PORT_IS_INPUT)?;
    let out = conn.register_port("output", PORT_IS_OUTPUT)?;
    let ports = Ports {
        inp: inp,
        out: out
    };
    conn.set_handler(ports)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&out, &ports[0])?;
        println!("Connected output port to {}", ports[0].get_name(false)?);
    }
    let ports = conn.get_ports(None, None, Some(PORT_IS_OUTPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&ports[0], &inp)?;
        println!("Connected input port to {}", ports[0].get_name(false)?);
    }
    thread::sleep(::std::time::Duration::new(60 * 60, 0));
    Ok(())
}

pub fn set_handler<F>(&mut self, handler: F) -> JackResult<()>

where F: JackHandler,

Register a handler (a struct that implements JackHandler).

Safety

Warning: Your handler will never be deallocated / Dropped.

Errors

• UnknownErrorCode

Examples found in repository

examples/sawtooth.rs (line 36)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("Very Annoying Sawtooth Generator", None)?;
    let out1 = conn.register_port("output_1", PORT_IS_OUTPUT)?;
    let out2 = conn.register_port("output_2", PORT_IS_OUTPUT)?;
    let data = Sawtooth {
        out1: out1,
        out2: out2,
        left_saw: 0.0,
        right_saw: 0.0
    };
    conn.set_handler(data)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 2 {
        conn.connect_ports(&out1, &ports[0])?;
        conn.connect_ports(&out2, &ports[1])?;
    }
    thread::sleep(::std::time::Duration::new(5, 0));
    Ok(())
}

examples/simple_client.rs (line 27)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("simple_client", None)?;
    let inp = conn.register_port("input", PORT_IS_INPUT)?;
    let out = conn.register_port("output", PORT_IS_OUTPUT)?;
    let ports = Ports {
        inp: inp,
        out: out
    };
    conn.set_handler(ports)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&out, &ports[0])?;
        println!("Connected output port to {}", ports[0].get_name(false)?);
    }
    let ports = conn.get_ports(None, None, Some(PORT_IS_OUTPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&ports[0], &inp)?;
        println!("Connected input port to {}", ports[0].get_name(false)?);
    }
    thread::sleep(::std::time::Duration::new(60 * 60, 0));
    Ok(())
}

pub fn activate(self) -> Result<JackConnection<Activated>, (Self, JackError)>

Tell the Jack server that the program is ready to start processing audio.

Returns

Returns the Activated connection type on success, or the current structure and an error on failure.

Errors

• UnknownErrorCode

Examples found in repository

examples/sawtooth.rs (line 37)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("Very Annoying Sawtooth Generator", None)?;
    let out1 = conn.register_port("output_1", PORT_IS_OUTPUT)?;
    let out2 = conn.register_port("output_2", PORT_IS_OUTPUT)?;
    let data = Sawtooth {
        out1: out1,
        out2: out2,
        left_saw: 0.0,
        right_saw: 0.0
    };
    conn.set_handler(data)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 2 {
        conn.connect_ports(&out1, &ports[0])?;
        conn.connect_ports(&out2, &ports[1])?;
    }
    thread::sleep(::std::time::Duration::new(5, 0));
    Ok(())
}

examples/simple_client.rs (line 28)

fn run() -> JackResult<()> {
    let mut conn = JackConnection::connect("simple_client", None)?;
    let inp = conn.register_port("input", PORT_IS_INPUT)?;
    let out = conn.register_port("output", PORT_IS_OUTPUT)?;
    let ports = Ports {
        inp: inp,
        out: out
    };
    conn.set_handler(ports)?;
    let mut conn = match conn.activate() {
        Ok(nc) => nc,
        Err((_, err)) => return Err(err)
    };
    let ports = conn.get_ports(None, None, Some(PORT_IS_INPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&out, &ports[0])?;
        println!("Connected output port to {}", ports[0].get_name(false)?);
    }
    let ports = conn.get_ports(None, None, Some(PORT_IS_OUTPUT | PORT_IS_PHYSICAL))?;
    if ports.len() >= 1 {
        conn.connect_ports(&ports[0], &inp)?;
        println!("Connected input port to {}", ports[0].get_name(false)?);
    }
    thread::sleep(::std::time::Duration::new(60 * 60, 0));
    Ok(())
}

impl JackConnection<Activated>

pub fn deactivate( self, ) -> Result<JackConnection<Deactivated>, (Self, JackError)>

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.

Returns

Returns the Dectivated connection type on success, or the current structure and an error on failure.

Errors

• UnknownErrorCode

Trait Implementations

impl<T> Drop for JackConnection<T>

fn drop(&mut self)

Executes the destructor for this type.