libcmtspeechdata library API  2.1.1
Data Structures | Macros | Typedefs | Enumerations | Functions
cmtspeech.h File Reference
#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_tcmtspeech_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

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
contextself-pointer
flagsbitmask 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
stateenabled 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
funchandler 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
statetrue call has been connected
statefalse 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
statetrue call signaling instance has been started
statefalse 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
statetrue call has been connected
statefalse 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
priorityone of CMTSPEECH_TRACE_*
enabledif 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.