libcmtspeechdata library API
2.1.1
|
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 |
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... | |
CMT Speech Data protocol library.
enum cmtspeech_state |
General list of TODO items:
int cmtspeech_backend_message | ( | cmtspeech_t * | self, |
int | type, | ||
int | args, | ||
... | |||
) |
Passes a custom message to the library backend implementation.
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 (
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.
int cmtspeech_buffer_sample_rate | ( | cmtspeech_buffer_t * | context | ) |
Returns the sample rate for the buffer.
int cmtspeech_check_pending | ( | cmtspeech_t * | context, |
int * | flags | ||
) |
Checks what events are available.
Should be called when cmtspeech_descriptor() becomes readable.
context | self-pointer |
flags | bitmask of pending events (e.g. CMTSPEECH_EVENT_CONTROL, CMTSPEECH_DL_DATA_AVAIL, ...) |
int cmtspeech_close | ( | cmtspeech_t * | context | ) |
Closes CMT Speech Data connection.
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.
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'.
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'.
int cmtspeech_dl_buffer_release | ( | cmtspeech_t * | context, |
cmtspeech_buffer_t * | buf | ||
) |
Releases a previously acquired downlink buffer slot back to the library.
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.
void cmtspeech_init | ( | void | ) |
Initializes the libcmtspeechdata for use.
Should be called once when application is started.
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.
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.
cmtspeech_t* cmtspeech_open | ( | void | ) |
Opens the CMT Speech Data connection to the modem.
int cmtspeech_protocol_state | ( | cmtspeech_t * | context | ) |
Returns the current protocol state.
int cmtspeech_protocol_version | ( | void | ) |
Returns the implemented CMT Speech Data protocol version.
Note that implementation may also provide backwards compatibility for older versions.
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.
int cmtspeech_send_ssi_config_request | ( | cmtspeech_t * | context, |
bool | active | ||
) |
Sends the SSI_CONFIG_REQ message to CMT.
state | enabled or disabled |
int cmtspeech_send_timing_request | ( | cmtspeech_t * | context | ) |
Sends the NEW_TIMING_CONFIG_REQ message to CMT.
int cmtspeech_set_trace_handler | ( | cmtspeech_trace_handler_t | func | ) |
Sets the function to call when the library emits a trace message.
func | handler function, or NULL to reset back to default handler |
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.
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.
state | true call has been connected |
state | false call has been disconnected |
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.
state | true call signaling instance has been started |
state | false call signaling instance has terminated |
int cmtspeech_state_change_error | ( | cmtspeech_t * | context | ) |
Signals an error.
Protocol state should be reseted.
state | true call has been connected |
state | false call has been disconnected |
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.
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.
priority | one of CMTSPEECH_TRACE_* |
enabled | if true, traces are allowed through |
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.
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'.