Struct libpulse_binding::stream::Stream

pub struct Stream { /* fields omitted */ }

An opaque stream for playback or recording. This acts as a safe Rust wrapper for the actual C object.

Methods

impl Stream

fn new(
    ctx: &mut Context,
    name: &str,
    ss: &Spec,
    map: Option<&Map>
) -> Option<Self>

Create a new, unconnected stream with the specified name and sample type.

It is recommended to use new_with_proplist instead and specify some initial properties.

Params

• ctx: The context to create this stream in
• name: A name for this stream
• ss: The desired sample format
• map: The desired channel map, or None for default

fn new_with_proplist(
    ctx: &mut Context,
    name: &str,
    ss: &Spec,
    map: Option<&Map>,
    plist: &mut Proplist
) -> Option<Self>

Create a new, unconnected stream with the specified name and sample type, and specify the initial stream property list.

Params

• ctx: The context to create this stream in
• name: A name for this stream
• ss: The desired sample format
• map: The desired channel map, or None for default
• plist: The initial property list

fn new_extended(
    ctx: &mut Context,
    name: &str,
    formats: &[&Info],
    list: &mut Proplist
) -> Option<Self>

Create a new, unconnected stream with the specified name, the set of formats this client can provide, and an initial list of properties. While connecting, the server will select the most appropriate format which the client must then provide.

Params

• ctx: The context to create this stream in
• name: A name for this stream
• formats: The list of formats that can be provided
• plist: The initial property list

fn from_raw(ptr: *mut StreamInternal) -> Self

Create a new Stream from an existing StreamInternal pointer.

fn from_raw_weak(ptr: *mut StreamInternal) -> Self

Create a new Stream from an existing StreamInternal pointer. This is the 'weak' version, for use in callbacks, which avoids destroying the internal object when dropped.

fn get_state(&self) -> State

Return the current state of the stream.

fn get_context(&self) -> Context

Return the context this stream is attached to.

fn get_index(&self) -> Option<u32>

Return the sink input resp. source output index this stream is identified in the server with. This is useful with the introspection functions such as ::context::introspect::Introspector::get_sink_input_info or ::context::introspect::Introspector::get_source_output_info.

fn get_device_index(&self) -> Option<u32>

Return the index of the sink or source this stream is connected to in the server. This is useful with the introspection functions such as ::context::introspect::Introspector::get_sink_info_by_index or ::context::introspect::Introspector::get_source_info_by_index.

Please note that streams may be moved between sinks/sources and thus it is recommended to use set_moved_callback to be notified about this.

fn get_device_name(&self) -> Option<&'static CStr>

Return the name of the sink or source this stream is connected to in the server. This is useful with the introspection functions such as ::context::introspect::Introspector::get_sink_info_by_name or ::context::introspect::Introspector::get_source_info_by_name.

Please note that streams may be moved between sinks/sources and thus it is recommended to use set_moved_callback to be notified about this.

fn is_suspended(&self) -> Result<bool, i32>

Return whether or not the sink or source this stream is connected to has been suspended.

fn is_corked(&self) -> Result<bool, i32>

Return whether or not this stream has been corked.

fn connect_playback(
    &self,
    dev: Option<&str>,
    attr: Option<&BufferAttr>,
    flags: FlagSet,
    volume: Option<&CVolume>,
    sync_stream: Option<&mut Self>
) -> Result<(), i32>

Connect the stream to a sink.

It is strongly recommended to pass None in both dev and volume and to set neither flags::START_MUTED nor flags::START_UNMUTED -- unless these options are directly dependent on user input or configuration.

If you follow this rule then the sound server will have the full flexibility to choose the device, volume and mute status automatically, based on server-side policies, heuristics and stored information from previous uses. Also the server may choose to reconfigure audio devices to make other sinks/sources or capabilities available to be able to accept the stream.

Before PA 0.9.20 it was not defined whether the 'volume' parameter was interpreted relative to the sink's current volume or treated as an absolute device volume. Since PA 0.9.20 it is an absolute volume when the sink is in flat volume mode, and relative otherwise, thus making sure the volume passed here has always the same semantics as the volume passed to ::context::introspect::Introspector::set_sink_input_volume. It is possible to figure out whether flat volume mode is in effect for a given sink by calling ::context::introspect::Introspector::get_sink_info_by_name.

Since PA 5.0, it's possible to specify a single-channel volume even if the stream has multiple channels. In that case the same volume is applied to all channels.

Params

• dev: Name of the sink to connect to, or None for default
• attr: Buffering attributes, or None for default
• flags: Additional flags, or 0 for default
• volume: Initial volume, or None for default
• sync_stream: Synchronize this stream with the specified one, or None for a standalone stream.

fn connect_record(
    &self,
    dev: Option<&str>,
    attr: Option<&BufferAttr>,
    flags: FlagSet
) -> Result<(), i32>

Connect the stream to a source.

Params

• dev: Name of the source to connect to, or None for default
• attr: Buffering attributes, or None for default
• flags: Additional flags, or 0 for default

fn connect_upload(&self, length: usize) -> Result<(), i32>

Make this stream a sample upload stream. (See ::scache).

fn finish_upload(&self) -> Result<(), i32>

Finish the sample upload, the stream name will become the sample name. You cancel a sample upload by issuing disconnect.

fn disconnect(&self) -> Result<(), i32>

Disconnect a stream from a source/sink.

fn begin_write(&self, nbytes: Option<usize>) -> Result<BufferResult, i32>

Prepare writing data to the server (for playback streams).

This function may be used to optimize the number of memory copies when doing playback ("zero-copy"). It is recommended to call this function before each call to write. It is used to obtain a chunk of PA internally allocated memory, into which you can directly write your data before calling write to actually execute the write.

This function should be called with nbytes set to the number of bytes you want to write, or None, in which case the size will be chosen automatically (which is recommended).

Returns either BufferResult::Null, should a null pointer be returned, or a tuple of the pointer and the size in bytes that can be written there, which may be less than or equal to the nbytes requested.

After placing your data in the memory area returned, call write with data set to an address within this memory area and an nbytes value that is smaller or equal to what was returned by this function, to actually execute the write.

If you want to cancel a previously called begin_write without calling write use cancel_write.

Accessing the memory returned after the following write or cancel_write is invalid. The memory should not be explicly freed by the caller.

An invocation of write should follow "quickly" on begin_write. It is not recommended letting an unbounded amount of time pass after calling begin_write and before calling write. Calling begin_write twice without calling write or cancel_write in between will return exactly the same data pointer and nbytes values.

fn cancel_write(&self) -> Result<(), i32>

Reverses the effect of begin_write dropping any data that has already been placed in the memory area returned by begin_write. Only valid to call after a call to begin_write has been made, and neither cancel_write nor write have been called yet. Accessing the memory previously returned by begin_write after calling this function is invalid.

fn write(
    &self,
    data: &[u8],
    free_cb: Option<FreeCb>,
    offset: i64,
    seek: SeekMode
) -> Result<(), i32>

Write some data to the server (for playback streams).

If free_cb is provided, this routine is called when all data has been written out. An internal reference to the specified data is kept, the data is not copied. If None, the data is copied into an internal buffer.

The client may freely seek around in the output buffer. For most applications it is typical to pass 0 and SeekMode::Relative as values for the arguments offset and seek respectively. After a successful write call the write index will be at the position after where this chunk of data has been written to.

As an optimization for avoiding needless memory copies you may call begin_write before this call and then place your audio data directly in the memory area returned by that call. Then, pass a pointer to that memory area to write. After the invocation of write the memory area may no longer be accessed. Any further explicit freeing of the memory area is not necessary. It is OK to write to the memory area returned by begin_write only partially with this call, skipping bytes both at the end and at the beginning of the reserved memory area.

Params

• data: The data to write. The length must be in multiples of the stream's sample spec frame size.
• free_cb: A cleanup routine for the data or None to request an internal copy of the data.
• offset: Offset for seeking. Must be 0 for upload streams. Must be in multiples of the stream's sample spec frame size.
• seek: Seek mode. Must be SeekMode::Relative for upload streams.

fn write_ext_free(
    &self,
    data: &[u8],
    free_cb: Option<FreeCb>,
    free_cb_data: *mut c_void,
    offset: i64,
    seek: SeekMode
) -> Result<(), i32>

Function does exactly the same as write with the difference that free_cb_data is passed to free_cb instead of data.

Params

• data: The data to write. The length must be in multiples of the stream's sample spec frame size.
• free_cb: A cleanup routine for the data or None to request an internal copy of the data.
• free_cb_data: Argument passed to free_cb function.
• offset: Offset for seeking. Must be 0 for upload streams.
• seek: Seek mode, must be SeekMode::Relative for upload streams.

fn peek(&self) -> Result<PeekResult, i32>

Read the next fragment from the buffer (for recording streams).

This function returns one of the PeekResult variants - either Empty, Hole or Data:

• If there is data at the current read index, the Data variant will be returned, which contains a slice giving a view of the data. (The length of this slice can be less or more than a complete fragment). This is pointing into an internal buffer, so obviously you must make a copy of it if you want to keep it.
• If there is no data at the current read index, it means that either the buffer is empty or it contains a hole (that is, the write index is ahead of the read index but there's no data where the read index points at). If the buffer is empty, the Empty result variant will be returned. If there is a hole, the Hole variant will be returned, containing the length of the hole in bytes.

Use discard to actually remove the data from the buffer and move the read index forward. discard should not be called if the buffer is empty, but it should be called if there is a hole.

fn discard(&self) -> Result<(), i32>

Remove the current fragment on record streams.

It is invalid to do this without first calling peek.

Note: The original C function name used the term drop; We instead use discard here to avoid conflict with the Rust Drop trait!

fn writable_size(&self) -> Option<usize>

Return the number of bytes requested by the server that have not yet been written.

It is possible to write more than this amount, up to the stream's buffer_attr.maxlength bytes. This is usually not desirable, though, as it would increase stream latency to be higher than requested (buffer_attr.tlength).

fn readable_size(&self) -> Option<usize>

Return the number of bytes that may be read using peek.

fn drain(&self, cb: Option<(SuccessCb, *mut c_void)>) -> Option<Operation>

Drain a playback stream.

Use this for notification when the playback buffer is empty after playing all the audio in the buffer. Please note that only one drain operation per stream may be issued at a time.

fn update_timing_info(
    &self,
    cb: Option<(SuccessCb, *mut c_void)>
) -> Option<Operation>

Request a timing info structure update for a stream.

Use get_timing_info to get access to the raw timing data, or get_time or get_latency to get cleaned up values.

fn set_state_callback(&self, cb: Option<(NotifyCb, *mut c_void)>)

Set the callback function that is called whenever the state of the stream changes.

fn set_write_callback(&self, cb: Option<(RequestCb, *mut c_void)>)

Set the callback function that is called when new data may be written to the stream.

fn set_read_callback(&self, cb: Option<(RequestCb, *mut c_void)>)

Set the callback function that is called when new data is available from the stream.

fn set_overflow_callback(&self, cb: Option<(NotifyCb, *mut c_void)>)

Set the callback function that is called when a buffer overflow happens. (Only for playback streams).

fn get_underflow_index(&self) -> Option<i64>

Return at what position the latest underflow occurred.

None is returned if this information is not known (e.g. if no underflow has occurred).

This can be used inside the underflow callback to get information about the current underflow. (Only for playback streams).

fn set_underflow_callback(&self, cb: Option<(NotifyCb, *mut c_void)>)

Set the callback function that is called when a buffer underflow happens. (Only for playback streams)

fn set_started_callback(&self, cb: Option<(NotifyCb, *mut c_void)>)

Set the callback function that is called when the server starts playback after an underrun or on initial startup. This only informs that audio is flowing again, it is no indication that audio started to reach the speakers already. (Only for playback streams).

fn set_latency_update_callback(&self, cb: Option<(NotifyCb, *mut c_void)>)

Set the callback function that is called whenever a latency information update happens. Useful on flags::AUTO_TIMING_UPDATE streams only.

fn set_moved_callback(&self, cb: Option<(NotifyCb, *mut c_void)>)

Set the callback function that is called whenever the stream is moved to a different sink/source. Use get_device_name or get_device_index to query the new sink/source.

fn set_suspended_callback(&self, cb: Option<(NotifyCb, *mut c_void)>)

Set the callback function that is called whenever the sink/source this stream is connected to is suspended or resumed. Use is_suspended to query the new suspend status. Please note that the suspend status might also change when the stream is moved between devices. Thus if you call this function you very likely want to call set_moved_callback too.

fn set_event_callback(&self, cb: Option<(EventCb, *mut c_void)>)

Set the callback function that is called whenever a meta/policy control event is received.

fn set_buffer_attr_callback(&self, cb: Option<(NotifyCb, *mut c_void)>)

Set the callback function that is called whenever the buffer attributes on the server side change. Please note that the buffer attributes can change when moving a stream to a different sink/source too, hence if you use this callback you should use set_moved_callback as well.

fn cork(&self, cb: Option<(SuccessCb, *mut c_void)>) -> Option<Operation>

Pause playback of this stream temporarily.

Available on both playback and recording streams. The pause operation is executed as quickly as possible. If a cork is very quickly followed by an uncork or the other way round, this might not actually have any effect on the stream that is output. You can use is_corked to find out whether the stream is currently paused or not. Normally a stream will be created in uncorked state. If you pass flags::START_CORKED as a flag when connecting the stream, it will be created in corked state.

fn uncork(&self, cb: Option<(SuccessCb, *mut c_void)>) -> Option<Operation>

Resume playback of this stream.

Available on both playback and recording streams. The operation is executed as quickly as possible.

fn flush(&self, cb: Option<(SuccessCb, *mut c_void)>) -> Option<Operation>

Flush the playback or record buffer of this stream.

This discards any audio data in the buffer. Most of the time you're better off using the parameter seek of write instead of this function.

fn prebuf(&self, cb: Option<(SuccessCb, *mut c_void)>) -> Option<Operation>

Reenable prebuffering if specified in the ::def::BufferAttr structure. Available for playback streams only.

fn trigger(&self, cb: Option<(SuccessCb, *mut c_void)>) -> Option<Operation>

Request immediate start of playback on this stream.

This disables prebuffering temporarily if specified in the ::def::BufferAttr structure. Available for playback streams only.

fn set_name(
    &self,
    name: &str,
    cb: Option<(SuccessCb, *mut c_void)>
) -> Option<Operation>

Rename the stream.

fn get_time(&self) -> Result<Option<Usecs>, i32>

Return the current playback/recording time.

This is based on the data in the timing info structure returned by get_timing_info. The returned time is in the sound card clock domain, which usually runs at a slightly different rate than the system clock.

This function will usually only return new data if a timing info update has been received. Only if timing interpolation has been requested (flags::INTERPOLATE_TIMING) the data from the last timing update is used for an estimation of the current playback/recording time based on the local time that passed since the timing info structure has been acquired.

The time value returned by this function is guaranteed to increase monotonically (the returned value is always greater or equal to the value returned by the last call). This behaviour can be disabled by using flags::NOT_MONOTONIC. This may be desirable to better deal with bad estimations of transport latencies, but may have strange effects if the application is not able to deal with time going 'backwards'.

The time interpolator activated by flags::INTERPOLATE_TIMING favours 'smooth' time graphs over accurate ones to improve the smoothness of UI operations that are tied to the audio clock. If accuracy is more important to you, you might need to estimate your timing based on the data from get_timing_info yourself or not work with interpolated timing at all and instead always query the server side for the most up to date timing with update_timing_info.

If no timing information has been received yet this call will return Ok(None). For more details see get_timing_info.

fn get_latency(&self) -> Result<Latency, i32>

Determine the total stream latency.

This function is based on get_time. The returned time is in the sound card clock domain, which usually runs at a slightly different rate than the system clock.

In case the stream is a monitoring stream the result can be negative, i.e. the captured samples are not yet played, in which case Ok(Latency::Negative(usecs)) will be returned instead of Ok(Latency::Positive(usecs))

If no timing information has been received yet, this call will return Ok(Latency::None).

For more details see get_timing_info and get_time.

fn get_timing_info(&self) -> Option<&TimingInfo>

Returns the latest raw timing data structure.

The returned pointer refers to an internal read-only instance of the timing structure. The user should make a copy of this structure if wanting to modify it. An in-place update to this data structure may be requested using update_timing_info.

If no timing information has been received before (i.e. by requesting update_timing_info or by using flags::AUTO_TIMING_UPDATE), this function will return None (as it will also if an error occurs).

Please note that the write_index member field (and only this field) is updated on each write call, not just when a timing update has been received.

fn get_sample_spec(&self) -> Option<&Spec>

Return a pointer to the stream's sample specification.

fn get_channel_map(&self) -> Option<&Map>

Return a pointer to the stream's channel map.

fn get_format_info(&self) -> Option<Info>

Return a pointer to the stream's format.

fn get_buffer_attr(&self) -> Option<&BufferAttr>

Return the per-stream server-side buffer metrics of the stream.

Only valid after the stream has been connected successfully. This will return the actual configured buffering metrics, which may differ from what was requested during connect_record or connect_playback. This call will always return the actual per-stream server-side buffer metrics, regardless whether flags::ADJUST_LATENCY is set or not.

fn set_buffer_attr(
    &self,
    attr: &BufferAttr,
    cb: (SuccessCb, *mut c_void)
) -> Option<Operation>

Change the buffer metrics of the stream during playback.

The server might have chosen different buffer metrics then requested. The selected metrics may be queried with get_buffer_attr as soon as the callback is called. Only valid after the stream has been connected successfully. Please be aware of the slightly different semantics of the call depending whether flags::ADJUST_LATENCY is set or not.

fn update_sample_rate(
    &self,
    rate: u32,
    cb: (SuccessCb, *mut c_void)
) -> Option<Operation>

Change the stream sampling rate during playback.

You need to pass flags::VARIABLE_RATE in the flags parameter of connect_playback if you plan to use this function. Only valid after the stream has been connected successfully.

fn update_proplist(
    &self,
    mode: UpdateMode,
    plist: &mut Proplist,
    cb: (SuccessCb, *mut c_void)
) -> Option<Operation>

Update the property list of the sink input/source output of this stream, adding new entries.

Please note that it is highly recommended to set as many properties initially via new_with_proplist as possible instead a posteriori with this function, since that information may be used to route this stream to the right device.

fn proplist_remove(
    &self,
    keys: &[&str],
    cb: (SuccessCb, *mut c_void)
) -> Option<Operation>

Update the property list of the sink input/source output of this stream, remove entries.

fn set_monitor_stream(&self, sink_input_idx: u32) -> Result<(), i32>

For record streams connected to a monitor source: monitor only a very specific sink input of the sink. This function needs to be called before connect_record is called.

fn get_monitor_stream(&self) -> Option<u32>

Return the sink input index previously set with set_monitor_stream.

Trait Implementations

impl Drop for Stream

fn drop(&mut self)

Executes the destructor for this type.