libcmtspeechdata library API  2.1.1
Data Structures | Macros | Typedefs | Enumerations | Functions
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_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.