cmtspeech.h File Reference

CMT Speech Data protocol library. More...

`#include <stdarg.h>`
`#include <stdbool.h>`
`#include <stdint.h>`
`#include <time.h>`
`#include <cmtspeech_msgs.h>`
`#include <cmtspeech_config.h>`

## Data Structures

struct | cmtspeech_buffer_s
| Frame data buffer descriptor. More...
struct | cmtspeech_event_s
| Protocol state change event. More...

## Macros

#define | CMTSPEECH_BUFFER_TYPE_PCM_S16_LE 0
| A continuous stream of little-endian 16bit PCM samples.
#define | CMTSPEECH_EVENT_CONTROL (1 << 0)
| control message available
#define | CMTSPEECH_EVENT_DL_DATA (1 << 1)
| DL frame available.
#define | CMTSPEECH_EVENT_XRUN (1 << 2)
| DL overrun occured.

## Typedefs

typedef struct cmtspeech_buffer_s | cmtspeech_buffer_t
| Typedef for cmtspeech_buffer_s.
typedef struct cmtspeech_event_s | cmtspeech_event_t
| Typedef for cmtspeech_event_s.

## Enumerations

enum | cmtspeech_state
| General list of TODO items: More...
enum | cmtspeech_state_tr
| Enumeration of state transitions.

## Functions

void | cmtspeech_init (void)
| Initializes the libcmtspeechdata for use. More...
cmtspeech_t * | cmtspeech_open (void)
| Opens the CMT Speech Data connection to the modem. More...
int | cmtspeech_close (cmtspeech_t *context)
| Closes CMT Speech Data connection. More...
int | cmtspeech_descriptor (cmtspeech_t *context)
| Returns a file descriptor that can be used to wait (with poll()/select()) for events. More...
int | cmtspeech_check_pending (cmtspeech_t *context, int *flags)
| Checks what events are available. More...
int | cmtspeech_read_event (cmtspeech_t *context, cmtspeech_event_t *event)
| Reads a control event and stores it to 'event'. More...
int | cmtspeech_event_to_state_transition (const cmtspeech_t *context, const cmtspeech_event_t *event)
| Returns the matching state transition for for 'event'. More...
int | cmtspeech_set_wb_preference (cmtspeech_t *context, bool enabled)
| Sets preference for wideband mode. More...
int | cmtspeech_protocol_state (cmtspeech_t *context)
| Returns the current protocol state. More...
bool | cmtspeech_is_ssi_connection_enabled (cmtspeech_t *context)
| Is SSI connection enabled? More...
bool | cmtspeech_is_active (cmtspeech_t *context)
| Is speech data stream active? More...
int | cmtspeech_state_change_call_status (cmtspeech_t *context, bool state)
| Signals a change in call signaling server status. More...
int | cmtspeech_state_change_call_connect (cmtspeech_t *context, bool state)
| Signals a change in call connected status. More...
int | cmtspeech_state_change_error (cmtspeech_t *context)
| Signals an error. More...
int | cmtspeech_ul_buffer_acquire (cmtspeech_t *context, cmtspeech_buffer_t **buf)
| Acquires the next uplink buffer slot. More...
int | cmtspeech_ul_buffer_release (cmtspeech_t *context, cmtspeech_buffer_t *buf)
| Releases a previously acquired uplink buffer slot back to the library. More...
int | cmtspeech_dl_buffer_acquire (cmtspeech_t *context, cmtspeech_buffer_t **buf)
| Acquires the next downlink buffer slot. More...
int | cmtspeech_dl_buffer_release (cmtspeech_t *context, cmtspeech_buffer_t *buf)
| Releases a previously acquired downlink buffer slot back to the library. More...
int | cmtspeech_buffer_codec_sample_rate (cmtspeech_buffer_t *context)
| Returns the codec sample rate for the buffer. More...
int | cmtspeech_buffer_sample_rate (cmtspeech_buffer_t *context)
| Returns the sample rate for the buffer. More...
cmtspeech_buffer_t * | cmtspeech_dl_buffer_find_with_data (cmtspeech_t *context, uint8_t *data)
| Returns the buffer descriptor pointing to raw downlink frame at 'data'. More...
const char * | cmtspeech_version_str (void)
| Returns the library implementation version as a NULL-terminated string.
int | cmtspeech_protocol_version (void)
| Returns the implemented CMT Speech Data protocol version. More...
const char * | cmtspeech_backend_name (cmtspeech_t *context)
| Returns a string identifying the library backend implementation. More...
int | cmtspeech_backend_message (cmtspeech_t *self, int type, int args,...)
| Passes a custom message to the library backend implementation. More...
int | cmtspeech_send_timing_request (cmtspeech_t *context)
| Sends the NEW_TIMING_CONFIG_REQ message to CMT. More...
int | cmtspeech_send_ssi_config_request (cmtspeech_t *context, bool active)
| Sends the SSI_CONFIG_REQ message to CMT. More...
int | cmtspeech_test_data_ramp_req (cmtspeech_t *context, uint8_t rampstart, uint8_t ramplen)
| Initiates a test sequence where the peer is requested to send back a test data frame. More...
void | cmtspeech_trace_toggle (int priority, bool enabled)
| Enables or disables trace message of a given priority level. More...
int | cmtspeech_set_trace_handler (cmtspeech_trace_handler_t func)
| Sets the function to call when the library emits a trace message. More...

## Detailed Description

CMT Speech Data protocol library.

## Enumeration Type Documentation

## cmtspeech_state

enum cmtspeech_state

General list of TODO items:

- relay SPC_FLAGS with downlink frames
- rename file to cmtspeechdata.h? Protocol states

## Function Documentation

## cmtspeech_backend_message()

int cmtspeech_backend_message | ( | cmtspeech_t * | self,
|  | int | type,
|  | int | args,
|  |  | ...
| ) |  |

Passes a custom message to the library backend implementation.

Parameters

## cmtspeech_backend_name()

const char* cmtspeech_backend_name | ( | cmtspeech_t * | context | ) |

Returns a string identifying the library backend implementation.

Backend name can be used to verify which set of custom messages can be sent (

See also
  cmtspeech_backend_name()).

## cmtspeech_buffer_codec_sample_rate()

int cmtspeech_buffer_codec_sample_rate | ( | cmtspeech_buffer_t * | context | ) |

Returns the codec sample rate for the buffer.

The value reflects the original codec sample rate as it was received from, or will be sent to, the radio interface. The value may be different from value of cmtspeech_buffer_sample_rate(), e.g. in the case where modem does decoding and resamples the resulting PCM buffers.

Returns
  CMTSPEECH_SAMPLE_RATE_NONE: if information not available, CMTSPEECH_SAMPLE_RATE_8KHZ: 8kHz (narrow band), CMTSPEECH_SAMPLE_RATE_16KHZ: 16kHz (wide band)

See also
  cmtspeech_dl_sample_rate().

## cmtspeech_buffer_sample_rate()

int cmtspeech_buffer_sample_rate | ( | cmtspeech_buffer_t * | context | ) |

Returns the sample rate for the buffer.

Returns
  CMTSPEECH_SAMPLE_RATE_NONE: if information not available, CMTSPEECH_SAMPLE_RATE_8KHZ: 8kHz (narrow band), CMTSPEECH_SAMPLE_RATE_16KHZ: 16kHz (wide band)

See also
  cmtspeech_dl_codec_sample_rate().

## cmtspeech_check_pending()

int cmtspeech_check_pending | ( | cmtspeech_t * | context,
|  | int * | flags
| ) |  |

Checks what events are available.

Should be called when cmtspeech_descriptor() becomes readable.

Parameters

  context | self-pointer
  flags | bitmask of pending events (e.g. CMTSPEECH_EVENT_CONTROL, CMTSPEECH_DL_DATA_AVAIL, ...)

Returns
  1 if events available, 0 if not, or a negative error code

## cmtspeech_close()

int cmtspeech_close | ( | cmtspeech_t * | context | ) |

Closes CMT Speech Data connection.

Returns
  Zero on success, a negative error code otherwise.

## cmtspeech_descriptor()

int cmtspeech_descriptor | ( | cmtspeech_t * | context | ) |

Returns a file descriptor that can be used to wait (with poll()/select()) for events.

When there is readable data, client should call cmtspeech_check_events() function.

Returns
  a file descriptor

## cmtspeech_dl_buffer_acquire()

int cmtspeech_dl_buffer_acquire | ( | cmtspeech_t * | context,
|  | cmtspeech_buffer_t ** | buf
| ) |  |

Acquires the next downlink buffer slot.

The buffer contains the next available received frame of data.

All the buffer properties are set according to the received downlink frame.

Note: Application must not write to the buffer memory, i.e. 'buf->data' and 'buf->payload'.

Returns
  0 on success, otherwise a negative error code: -EINVAL: Invalid paramers or state, buffer not acquired. -ENODATA: No downlink slot available, buffer not acquired.

## cmtspeech_dl_buffer_find_with_data()

cmtspeech_buffer_t * cmtspeech_dl_buffer_find_with_data | ( | cmtspeech_t * | context,
|  | uint8_t * | data
| ) |  |

Returns the buffer descriptor pointing to raw downlink frame at 'data'.

See also
  cmtspeech_dl_buffer_release().

## cmtspeech_dl_buffer_release()

int cmtspeech_dl_buffer_release | ( | cmtspeech_t * | context,
|  | cmtspeech_buffer_t * | buf
| ) |  |

Releases a previously acquired downlink buffer slot back to the library.

Returns
  0 on success, otherwise a negative error code -ENOENT: The buffer given as argument does not match any existing acquired buffer. -EINVAL: Invalid parameters or state. -EPIPE: An underrun has occured because the buffer was released too late.

## cmtspeech_event_to_state_transition()

int cmtspeech_event_to_state_transition | ( | const cmtspeech_t * | context,
|  | const cmtspeech_event_t * | event
| ) |  |

Returns the matching state transition for for 'event'.

In case either 'context' or 'event' is invalid, CMTSPEECH_TR_INVALID is returned.

This function is a helper function and its use is not mandatory.

Returns
  enum cmtspeech_state_tr

## cmtspeech_init()

void cmtspeech_init | ( | void |  | ) |

Initializes the libcmtspeechdata for use.

Should be called once when application is started.

## cmtspeech_is_active()

bool cmtspeech_is_active | ( | cmtspeech_t * | context | ) |

Is speech data stream active?

The speech frame data stream is active when call parameters have been delivered and either downlink, or both downlink and uplink, frames are being sent.

Returns
  boolean answer

## cmtspeech_is_ssi_connection_enabled()

bool cmtspeech_is_ssi_connection_enabled | ( | cmtspeech_t * | context | ) |

Is SSI connection enabled?

The connection is enabled when a succesful SSI_CONFIG_REQ/_RESP transaction has completed.

Returns
  boolean answer

## cmtspeech_open()

cmtspeech_t* cmtspeech_open | ( | void |  | ) |

Opens the CMT Speech Data connection to the modem.

Returns
  Instance pointer is returned. On error, NULL is returned.

## cmtspeech_protocol_state()

int cmtspeech_protocol_state | ( | cmtspeech_t * | context | ) |

Returns the current protocol state.

Returns
  one of CMTSPEECH_STATE_*

## cmtspeech_protocol_version()

int cmtspeech_protocol_version | ( | void |  | ) |

Returns the implemented CMT Speech Data protocol version.

Note that implementation may also provide backwards compatibility for older versions.

## cmtspeech_read_event()

int cmtspeech_read_event | ( | cmtspeech_t * | context,
|  | cmtspeech_event_t * | event
| ) |  |

Reads a control event and stores it to 'event'.

This function should be called when cmtspeech_check_pending() returns flag CMTSPEECH_EVENT_CONTROL.

Returns
  0 on success

## cmtspeech_send_ssi_config_request()

int cmtspeech_send_ssi_config_request | ( | cmtspeech_t * | context,
|  | bool | active
| ) |  |

Sends the SSI_CONFIG_REQ message to CMT.

Parameters

  state | enabled or disabled

Returns
  0 on success

## cmtspeech_send_timing_request()

int cmtspeech_send_timing_request | ( | cmtspeech_t * | context | ) |

Sends the NEW_TIMING_CONFIG_REQ message to CMT.

Returns
  0 on success

## cmtspeech_set_trace_handler()

int cmtspeech_set_trace_handler | ( | cmtspeech_trace_handler_t | func | ) |

Sets the function to call when the library emits a trace message.

Parameters

  func | handler function, or NULL to reset back to default handler

## cmtspeech_set_wb_preference()

int cmtspeech_set_wb_preference | ( | cmtspeech_t * | context,
|  | bool | enabled
| ) |  |

Sets preference for wideband mode.

If set to enabled, application is assumed to prefer sending and receiving wideband (i.e. 16kHz sampling rate) speech frames. If disabled, library assumes only 8kHz sampling rate is supported and/or preferred.

This setting will be passed to the modem upon session setup. The final selection of sampling rate will however be done by the modem. It is thus possible that modem will send a CMTSPEECH_SPEECH_CONFIG_REQ event with sampling rate of 16kHz even though application has disabled wideband support with this method.

The sampling rate used to interface with the modem does not necessarily match the codec sampling rate used on the radio interface. In other words the modem may resample the voice frames to match the sampling rate used on modem<->libcmtspeechdata link.

By default, wideband mode is disabled after initial cmtspeech_open().

This function can only be called when there is no active session.

Precondition
  cmtspeech_is_ssi_connection_enabled(context) != true

Returns
  0 on success

## cmtspeech_state_change_call_connect()

int cmtspeech_state_change_call_connect | ( | cmtspeech_t * | context,
|  | bool | state
| ) |  |

Signals a change in call connected status.

Note: this reflects the status of call signaling and is not same as cmtspeech protocol state.

Parameters

  state | true call has been connected
  state | false call has been disconnected

## cmtspeech_state_change_call_status()

int cmtspeech_state_change_call_status | ( | cmtspeech_t * | context,
|  | bool | state
| ) |  |

Signals a change in call signaling server status.

Note: this reflects the status of call signaling and is not same as cmtspeech protocol state.

Parameters

  state | true call signaling instance has been started
  state | false call signaling instance has terminated

## cmtspeech_state_change_error()

int cmtspeech_state_change_error | ( | cmtspeech_t * | context | ) |

Signals an error.

Protocol state should be reseted.

Parameters

  state | true call has been connected
  state | false call has been disconnected

## cmtspeech_test_data_ramp_req()

int cmtspeech_test_data_ramp_req | ( | cmtspeech_t * | context,
|  | uint8_t | rampstart,
|  | uint8_t | ramplen
| ) |  |

Initiates a test sequence where the peer is requested to send back a test data frame.

The response frame payload should contain a data ramp, starting from value 'rampstart', and incremented by one in every octet. The payload length should be 'ramplen' 32bit words.

Note: this is a test interface that may not be supported by all library backends.

Returns
  0 on sucess, -1 on error

## cmtspeech_trace_toggle()

void cmtspeech_trace_toggle | ( | int | priority,
|  | bool | enabled
| ) |  |

Enables or disables trace message of a given priority level.

Note, some traces may be disabled at build time, and thus some traces may be unavailable even if enabled with this function.

Parameters

  priority | one of CMTSPEECH_TRACE_*
  enabled | if true, traces are allowed through

## cmtspeech_ul_buffer_acquire()

int cmtspeech_ul_buffer_acquire | ( | cmtspeech_t * | context,
|  | cmtspeech_buffer_t ** | buf
| ) |  |

Acquires the next uplink buffer slot.

The buffer should be filled with uplink data to be sent.

Buffer can be acquired when data stream is active (i.e. cmtspeech_is_active() is true). Note that it is possible to acquire buffers already in CMTSPEECH_STATE_ACTIVE_DL state.

Following buffer properties are set by the library: 'type', 'count', 'pcount', 'size', 'data' and 'payload'. Client should copy payload contents to buffer pointed by 'payload', and if needed, update the flags in 'frame_flags'. See documentation of cmtspeech_buffer_t for more information about the struct fields.

Precondition
  cmtspeech_is_active() == true

Returns
  0 on success, other a negative error code: -EINVAL: Invalid paramers or state, buffer not acquired. -ENOBUFS: No free uplink buffers, buffer not acquired.

## cmtspeech_ul_buffer_release()

int cmtspeech_ul_buffer_release | ( | cmtspeech_t * | context,
|  | cmtspeech_buffer_t * | buf
| ) |  |

Releases a previously acquired uplink buffer slot back to the library.

The buffer will be sent immediately to the network, so the caller must release the buffer in sync with network timing. The timing parameters are delivered as events ('msg_type' CMTSPEECH_TIMING_CONFIG_NTF).

Client should update the following buffer properties: contents of buffer pointed to by 'payload', and 'frame_flags'.

Returns
  0 on success, otherwise a negative error code: -EBUSY: Connection currently busy, frame not sent. Application should acquire a new buffer and retry sending later. -EINVAL: Invalid paramers or state, frame not sent. -EIO: I/O error, frame not sent. -EPIPE: Protocol state has changed since the buffer was acquired, frame not sent.

cmtspeech_dl_buffer_acquire
int cmtspeech_dl_buffer_acquire(cmtspeech_t *context, cmtspeech_buffer_t **buf)
Acquires the next downlink buffer slot.
cmtspeech_dl_buffer_release
int cmtspeech_dl_buffer_release(cmtspeech_t *context, cmtspeech_buffer_t *buf)
Releases a previously acquired downlink buffer slot back to the library.
cmtspeech_state_change_call_status
int cmtspeech_state_change_call_status(cmtspeech_t *context, bool state)
Signals a change in call signaling server status.
cmtspeech_open
cmtspeech_t * cmtspeech_open(void)
Opens the CMT Speech Data connection to the modem.
cmtspeech_event_s::tstamp
struct timespec tstamp
CLOCK_MONOTONIC timestamp when the message was received by HW driver.
Definition: cmtspeech.h:174
cmtspeech_ul_buffer_acquire
int cmtspeech_ul_buffer_acquire(cmtspeech_t *context, cmtspeech_buffer_t **buf)
Acquires the next uplink buffer slot.
cmtspeech_buffer_s::type
int type
buffer type (CMTSPEECH_BUFFER_TYPE_*)
Definition: cmtspeech.h:113
cmtspeech_descriptor
int cmtspeech_descriptor(cmtspeech_t *context)
Returns a file descriptor that can be used to wait (with poll()/select()) for events.
cmtspeech_event_s::version
uint8_t version
deprecated in 1.6.1
Definition: cmtspeech.h:154
cmtspeech_event_s::layout_changed
bool layout_changed
if true, acquired dl/ul buffers are invalid and need to be released
Definition: cmtspeech.h:166
cmtspeech_buffer_sample_rate
int cmtspeech_buffer_sample_rate(cmtspeech_buffer_t *context)
Returns the sample rate for the buffer.
cmtspeech_state_change_call_connect
int cmtspeech_state_change_call_connect(cmtspeech_t *context, bool state)
Signals a change in call connected status.
cmtspeech_buffer_s::payload
uint8_t * payload
pointer to frame payload
Definition: cmtspeech.h:122
cmtspeech_event_s::msg_type
int msg_type
type of the message that caused the state change
Definition: cmtspeech.h:140
cmtspeech_test_data_ramp_req
int cmtspeech_test_data_ramp_req(cmtspeech_t *context, uint8_t rampstart, uint8_t ramplen)
Initiates a test sequence where the peer is requested to send back a test data frame.
cmtspeech_event_to_state_transition
int cmtspeech_event_to_state_transition(const cmtspeech_t *context, const cmtspeech_event_t *event)
Returns the matching state transition for for 'event'.
cmtspeech_close
int cmtspeech_close(cmtspeech_t *context)
Closes CMT Speech Data connection.
cmtspeech_buffer_s::data
uint8_t * data
pointer to a buffer of 'size' octets
Definition: cmtspeech.h:121
cmtspeech_buffer_s
Frame data buffer descriptor.
Definition: cmtspeech.h:112
cmtspeech_version_str
const char * cmtspeech_version_str(void)
Returns the library implementation version as a NULL-terminated string.
cmtspeech_event_s::cellular_info
uint8_t cellular_info
deprecated in 1.5.3
Definition: cmtspeech.h:163
cmtspeech_event_s
Protocol state change event.
Definition: cmtspeech.h:135
cmtspeech_buffer_s::spc_flags
unsigned int spc_flags
speech codec flags for the frame; for UL: always set to zero, for DL: bitmask of CMTSPEECH_SPC_FLAGS_...
Definition: cmtspeech.h:118
cmtspeech_send_timing_request
int cmtspeech_send_timing_request(cmtspeech_t *context)
Sends the NEW_TIMING_CONFIG_REQ message to CMT.
cmtspeech_dl_buffer_find_with_data
cmtspeech_buffer_t * cmtspeech_dl_buffer_find_with_data(cmtspeech_t *context, uint8_t *data)
Returns the buffer descriptor pointing to raw downlink frame at 'data'.
cmtspeech_set_wb_preference
int cmtspeech_set_wb_preference(cmtspeech_t *context, bool enabled)
Sets preference for wideband mode.
cmtspeech_state_tr
cmtspeech_state_tr
Enumeration of state transitions.
Definition: cmtspeech.h:66
cmtspeech_event_s::msg
union cmtspeech_event_s::@0 msg
A copy of the protocol message that caused the state change (matching 'msg_type' field).
cmtspeech_buffer_s::frame_flags
int frame_flags
frame flags; enum CMTSPEECH_DATATYPE_*
Definition: cmtspeech.h:117
cmtspeech_protocol_version
int cmtspeech_protocol_version(void)
Returns the implemented CMT Speech Data protocol version.
cmtspeech_event_s::state
int state
new state (CMTSPEECH_STATE_*)
Definition: cmtspeech.h:137
cmtspeech_protocol_state
int cmtspeech_protocol_state(cmtspeech_t *context)
Returns the current protocol state.
cmtspeech_check_pending
int cmtspeech_check_pending(cmtspeech_t *context, int *flags)
Checks what events are available.
cmtspeech_init
void cmtspeech_init(void)
Initializes the libcmtspeechdata for use.
cmtspeech_event_s::codec_info
uint8_t codec_info
deprecated in 1.5.3
Definition: cmtspeech.h:162
cmtspeech_buffer_s::pcount
int pcount
octets of valid payload data
Definition: cmtspeech.h:115
cmtspeech_buffer_s::size
int size
octets of allocated space
Definition: cmtspeech.h:116
cmtspeech_backend_message
int cmtspeech_backend_message(cmtspeech_t *self, int type, int args,...)
Passes a custom message to the library backend implementation.
cmtspeech_event_s::cmt_sent_req
int cmt_sent_req
whether CMT was the initiator
Definition: cmtspeech.h:181
cmtspeech_ul_buffer_release
int cmtspeech_ul_buffer_release(cmtspeech_t *context, cmtspeech_buffer_t *buf)
Releases a previously acquired uplink buffer slot back to the library.
cmtspeech_is_active
bool cmtspeech_is_active(cmtspeech_t *context)
Is speech data stream active?
cmtspeech_buffer_s::index
int index
library internal
Definition: cmtspeech.h:123
cmtspeech_backend_name
const char * cmtspeech_backend_name(cmtspeech_t *context)
Returns a string identifying the library backend implementation.
cmtspeech_buffer_s::count
int count
octets of valid data (including header)
Definition: cmtspeech.h:114
cmtspeech_event_s::reserved
int reserved
reserved
Definition: cmtspeech.h:143
cmtspeech_read_event
int cmtspeech_read_event(cmtspeech_t *context, cmtspeech_event_t *event)
Reads a control event and stores it to 'event'.
cmtspeech_trace_toggle
void cmtspeech_trace_toggle(int priority, bool enabled)
Enables or disables trace message of a given priority level.
cmtspeech_set_trace_handler
int cmtspeech_set_trace_handler(cmtspeech_trace_handler_t func)
Sets the function to call when the library emits a trace message.
cmtspeech_event_s::prev_state
int prev_state
previous state
Definition: cmtspeech.h:138
cmtspeech_buffer_codec_sample_rate
int cmtspeech_buffer_codec_sample_rate(cmtspeech_buffer_t *context)
Returns the codec sample rate for the buffer.
cmtspeech_state_change_error
int cmtspeech_state_change_error(cmtspeech_t *context)
Signals an error.
cmtspeech_is_ssi_connection_enabled
bool cmtspeech_is_ssi_connection_enabled(cmtspeech_t *context)
Is SSI connection enabled?
cmtspeech_state
cmtspeech_state
General list of TODO items:
Definition: cmtspeech.h:54
cmtspeech_send_ssi_config_request
int cmtspeech_send_ssi_config_request(cmtspeech_t *context, bool active)
Sends the SSI_CONFIG_REQ message to CMT.