Chirp C SDK  3.3.1
Use Chirp to send data over sound from your C application.
chirp_sdk.h File Reference

Chirp C SDK implementation header. More...

#include <stdbool.h>
#include <stdint.h>
#include "chirp_sdk_errors.h"
#include "chirp_sdk_events.h"
#include "chirp_sdk_version.h"

Go to the source code of this file.

Macros

#define PUBLIC_SYM   __attribute__ ((visibility ("default")))
 

Typedefs

typedef struct _chirp_sdk_t chirp_sdk_t
 

Functions

PUBLIC_SYM chirp_sdk_tnew_chirp_sdk (const char *key, const char *secret)
 
PUBLIC_SYM chirp_sdk_error_code_t del_chirp_sdk (chirp_sdk_t **sdk)
 
PUBLIC_SYM void chirp_sdk_free (void *ptr)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_config (chirp_sdk_t *sdk, const char *config)
 
PUBLIC_SYM char * chirp_sdk_get_info (chirp_sdk_t *sdk)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_callbacks (chirp_sdk_t *sdk, chirp_sdk_callback_set_t callback_set)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_start (chirp_sdk_t *sdk)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_stop (chirp_sdk_t *sdk)
 
PUBLIC_SYM size_t chirp_sdk_get_max_payload_length (chirp_sdk_t *sdk)
 
PUBLIC_SYM float chirp_sdk_get_duration_for_payload_length (chirp_sdk_t *sdk, size_t payload_length)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_is_valid (chirp_sdk_t *sdk, const uint8_t *bytes, size_t length)
 
PUBLIC_SYM uint8_t * chirp_sdk_random_payload (chirp_sdk_t *sdk, size_t *length)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_send (chirp_sdk_t *sdk, uint8_t *bytes, size_t length)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process (chirp_sdk_t *sdk, float *in, float *out, size_t length)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process_input (chirp_sdk_t *sdk, float *buffer, size_t length)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process_output (chirp_sdk_t *sdk, float *buffer, size_t length)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process_shorts (chirp_sdk_t *sdk, short *in, short *out, size_t length)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process_shorts_input (chirp_sdk_t *sdk, const short *buffer, size_t length)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process_shorts_output (chirp_sdk_t *sdk, short *buffer, size_t length)
 
PUBLIC_SYM chirp_sdk_state_t chirp_sdk_get_state_for_channel (chirp_sdk_t *sdk, uint8_t channel)
 
PUBLIC_SYM int8_t chirp_sdk_get_transmission_channel (chirp_sdk_t *sdk)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_transmission_channel (chirp_sdk_t *sdk, uint8_t channel)
 
PUBLIC_SYM uint8_t chirp_sdk_get_channel_count (chirp_sdk_t *sdk)
 
PUBLIC_SYM chirp_sdk_state_t chirp_sdk_get_state (chirp_sdk_t *sdk)
 
PUBLIC_SYM float chirp_sdk_get_volume (chirp_sdk_t *sdk)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_volume (chirp_sdk_t *sdk, float volume)
 
PUBLIC_SYM uint32_t chirp_sdk_get_input_sample_rate (chirp_sdk_t *sdk)
 
PUBLIC_SYM uint32_t chirp_sdk_get_output_sample_rate (chirp_sdk_t *sdk)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_input_sample_rate (chirp_sdk_t *sdk, uint32_t sample_rate)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_output_sample_rate (chirp_sdk_t *sdk, uint32_t sample_rate)
 
PUBLIC_SYM bool chirp_sdk_get_listen_to_self (chirp_sdk_t *sdk)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_listen_to_self (chirp_sdk_t *sdk, bool listen_to_self)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_callback_ptr (chirp_sdk_t *sdk, void *ptr)
 
PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_frequency_correction (chirp_sdk_t *sdk, float correction)
 
PUBLIC_SYM int32_t chirp_sdk_get_heap_usage (chirp_sdk_t *sdk)
 

Detailed Description

Chirp C SDK implementation header.


ASIO CONFIDENTIAL

All contents are strictly proprietary, and not for copying, resale, or use outside of the agreed license.

Copyright © 2011-2019, Asio Ltd. All rights reserved.


Macro Definition Documentation

◆ PUBLIC_SYM

#define PUBLIC_SYM   __attribute__ ((visibility ("default")))

Mark the function as public. Any attempt to call a function without this marker will fail.

Typedef Documentation

◆ chirp_sdk_t

typedef struct _chirp_sdk_t chirp_sdk_t

Typedef exposing the SDK structure to the API.

Function Documentation

◆ chirp_sdk_free()

PUBLIC_SYM void chirp_sdk_free ( void *  ptr)

Free memory previously allocated and returned by the SDK.

Note that this does not free the SDK itself. For this, use del_chirp_sdk above.

This function should be called to free the memory returned by the following functions:

chirp_sdk_get_info chirp_sdk_random_payload

As well as freeing the memory, this function tracks the ongoing heap allocation which can be queried with chirp_sdk_get_heap_usage.

Parameters
ptrThe pointer to the memory to be freed.

◆ chirp_sdk_get_channel_count()

PUBLIC_SYM uint8_t chirp_sdk_get_channel_count ( chirp_sdk_t sdk)

Get the number of channels supported by the protocol used. By default, most protocols only support a single channel. To discuss support for multi-channel transmission, please get in touch at devel.nosp@m.oper.nosp@m.s@chi.nosp@m.rp.i.nosp@m.o.

Parameters
sdkA pointer to the SDK structure.
Returns
The number of available channels.

◆ chirp_sdk_get_duration_for_payload_length()

PUBLIC_SYM float chirp_sdk_get_duration_for_payload_length ( chirp_sdk_t sdk,
size_t  payload_length 
)

Get the duration, in seconds, for a given payload length.

Parameters
sdkA pointer to the SDK structure.
payload_lengthThe length, in bytes, of the payload we want to know the duration. You can get the maximum allowed length with chirp_sdk_get_max_payload_length.
Returns
The duration, in second, of the given length, -1 if the payload is too short or -2 if the payload is too long.

◆ chirp_sdk_get_heap_usage()

PUBLIC_SYM int32_t chirp_sdk_get_heap_usage ( chirp_sdk_t sdk)

Return the current heap usage of the SDK, in bytes.

Parameters
sdkA pointer to the SDK structure.
Returns
The heap usage in bytes of the SDK.

◆ chirp_sdk_get_info()

PUBLIC_SYM char* chirp_sdk_get_info ( chirp_sdk_t sdk)

Return a short description string of the config being used. An example of the type of string can be : "Chirp SDK with "standard-2018" config v1 [max 32 bytes in 4.52s]"

Parameters
sdkA pointer to the SDK structure.
Returns
The short config description string. The user has to free this string with chirp_sdk_free once it is not needed anymore.

◆ chirp_sdk_get_input_sample_rate()

PUBLIC_SYM uint32_t chirp_sdk_get_input_sample_rate ( chirp_sdk_t sdk)

Get the sample rate at which the SDK is processing the input.

Parameters
sdkA pointer to the SDK structure.
Returns
The actual sample rate used by the SDK to process the input.

◆ chirp_sdk_get_listen_to_self()

PUBLIC_SYM bool chirp_sdk_get_listen_to_self ( chirp_sdk_t sdk)

Get the SDK's listen to self state. This automatically mutes the decoder when sending a chirp, to prevent the application from hearing its own chirps. Defaults to false.

Set to true if you want your application to be able to hear its own chirps. This is typically only useful for testing and debugging - for example, when passing the output of process_output directly into process_input

Parameters
sdkA pointer to the SDK structure.
Returns
True : The SDK will attempt to decode the payloads it sends. False : The SDK will ignore the payloads it sends.

◆ chirp_sdk_get_max_payload_length()

PUBLIC_SYM size_t chirp_sdk_get_max_payload_length ( chirp_sdk_t sdk)

Get the maximum payload length allowed by the current config set for the SDK.

Parameters
sdkA pointer to the SDK structure.
Returns
The maximum payload length that can be sent. A length of 0 is invalid. If the config hasn't been set yet when this function is called 0 is returned.

◆ chirp_sdk_get_output_sample_rate()

PUBLIC_SYM uint32_t chirp_sdk_get_output_sample_rate ( chirp_sdk_t sdk)

Get the sample rate at which the SDK is processing the output.

Parameters
sdkA pointer to the SDK structure.
Returns
The actual sample rate used by the SDK to process the output.

◆ chirp_sdk_get_state()

PUBLIC_SYM chirp_sdk_state_t chirp_sdk_get_state ( chirp_sdk_t sdk)

Get the state of the SDK. Possibles values are defined in chirp_sdk_states.h.

Parameters
sdkA pointer to the SDK structure.
Returns
The state of the SDK.

◆ chirp_sdk_get_state_for_channel()

PUBLIC_SYM chirp_sdk_state_t chirp_sdk_get_state_for_channel ( chirp_sdk_t sdk,
uint8_t  channel 
)

Get the SDK state for the given channel.

Parameters
sdkA pointer to the SDK structure.
channelThe channel we want to know the state of.
Returns
The channel state of the SDK.

◆ chirp_sdk_get_transmission_channel()

PUBLIC_SYM int8_t chirp_sdk_get_transmission_channel ( chirp_sdk_t sdk)

Chirp listens for broadcasts on all channels simultaneously, but only transmits on a single channel at a time. This function gets the channel on which the data is sent.

Parameters
sdkA pointer to the SDK structure.
Returns
The channel on which the data is sent (including 0) or -1 if the SDK hasn't been initialised.

◆ chirp_sdk_get_volume()

PUBLIC_SYM float chirp_sdk_get_volume ( chirp_sdk_t sdk)

Get the volume of the SDK, between 0 and 1. This volume only influences the SDK's software output volume, and may be affected by the system's hardware audio volume.

Parameters
sdkA pointer to the SDK structure.
Returns
The volume of the output of the SDK or -1 if an error happened.

◆ chirp_sdk_is_valid()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_is_valid ( chirp_sdk_t sdk,
const uint8_t *  bytes,
size_t  length 
)

Validate a payload. If uncertain, the user can call this function to confirm this payload can be sent without issues.

Parameters
sdkA pointer to the SDK structure.
bytesA pointer to the payload to be validated.
lengthThe length, in bytes, of the payload.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_process()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process ( chirp_sdk_t sdk,
float *  in,
float *  out,
size_t  length 
)

Float audio processing function handling both the encoding (output) and the decoding (input).

Parameters
sdkA pointer to the SDK structure.
inA pointer to the float mono input buffer.
outA pointer to the float mono output buffer.
lengthThe length, in mono samples, of both the input and output buffers.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_process_input()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process_input ( chirp_sdk_t sdk,
float *  buffer,
size_t  length 
)

Float audio processing function for the decoding (input).

Parameters
sdkA pointer to the SDK structure.
bufferThe input buffer containing mono samples which will be decoded.
lengthThe length, in mono samples, of the input buffer.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_process_output()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process_output ( chirp_sdk_t sdk,
float *  buffer,
size_t  length 
)

Float audio processing function for the encoding (output). Fill a buffer with as many bytes as needed once the sending of a payload has been triggered.

Parameters
sdkA pointer to the SDK structure.
bufferThe output buffer which will be filled with new mono samples.
lengthThe length, in mono samples, of the output buffer.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_process_shorts()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process_shorts ( chirp_sdk_t sdk,
short *  in,
short *  out,
size_t  length 
)

Short audio processing function handling both the encoding (output) and the decoding (input).

Parameters
sdkA pointer to the SDK structure.
inA pointer to the short mono input buffer.
outA pointer to the short mono output buffer.
lengthThe length, in mono samples, of both the input and output buffers.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_process_shorts_input()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process_shorts_input ( chirp_sdk_t sdk,
const short *  buffer,
size_t  length 
)

Short audio processing function for the decoding (input).

Parameters
sdkA pointer to the SDK structure.
bufferThe input buffer containing mono samples which will be decoded.
lengthThe length, in mono samples, of the input buffer.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_process_shorts_output()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_process_shorts_output ( chirp_sdk_t sdk,
short *  buffer,
size_t  length 
)

Short audio processing function for the encoding (output). Fill a buffer, as many times as needed, once the sending of a payload has been triggered.

Parameters
sdkA pointer to the SDK structure.
bufferThe output buffer which will be filled with new mono samples.
lengthThe length, in mono samples, of the output buffer.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_random_payload()

PUBLIC_SYM uint8_t* chirp_sdk_random_payload ( chirp_sdk_t sdk,
size_t *  length 
)

Generate a random payload by allocating a payload and randomising its content.

Parameters
sdkA pointer to the SDK structure.
lengthA pointer containing the length, in bytes, of the payload to be generated. If the length is 0, the SDK will randomise both the length of the payload and its content. The length pointer will then be updated with the random length. You can get the maximum allowed length with chirp_sdk_get_max_payload_length.
Returns
A pointer to the newly created random data payload.The user has to free this pointer once they doesn't need it anymore using chirp_sdk_free.

◆ chirp_sdk_send()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_send ( chirp_sdk_t sdk,
uint8_t *  bytes,
size_t  length 
)

Send a payload. A valid length is between 1 and the value returned by chirp_sdk_get_max_payload_length.

Parameters
sdkA pointer to the SDK structure.
bytesA pointer to the payload that will be sent.
lengthThe length, in bytes, of the payload which will be sent.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_set_callback_ptr()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_callback_ptr ( chirp_sdk_t sdk,
void *  ptr 
)

Set the pointer which is accessible in the callbacks. This function doesn't necessarily need to be to be called. In that case, the pointer passed the callbacks will be NULL.

Parameters
sdkA pointer to the SDK structure.
ptrA pointer to any data you want to pass to the callbacks.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_set_callbacks()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_callbacks ( chirp_sdk_t sdk,
chirp_sdk_callback_set_t  callback_set 
)

Set the callbacks to the SDK. Callbacks are functions which will be executed once a key event happens. The list of the supported callbacks is explained in the documentation of the chirp_sdk_callback_set_t structure in chirp_sdk_callbacks.h.

Parameters
sdkA pointer to the SDK structure.
callback_setA set of callbacks which will be set to the SDK.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_set_config()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_config ( chirp_sdk_t sdk,
const char *  config 
)

Set the SDK config string coming from your Chirp account. Your Chirp config string configures your application's transmission settings (audio frequency, data rate, payload sizes). To get your Chirp config, sign in to the Chirp Admin Centre at https://developers.chirp.io.

Parameters
sdkA pointer to the SDK structure which needs the config to be set.
configThe config string which will be set.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_set_frequency_correction()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_frequency_correction ( chirp_sdk_t sdk,
float  correction 
)

On some systems, the effective audio sample rate is not quite the same as the expected sample rate - for example, if it is being driven by a clock whose frequency is not an integer multiple of the required audio sample rate. This setting rectifies the discrepancy between the two, by multiplying the detected frequency by a fixed frequency correction coefficient.

Parameters
sdkA pointer to the SDK structure.
correctionA correction value between 0.5 and 1.5.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_set_input_sample_rate()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_input_sample_rate ( chirp_sdk_t sdk,
uint32_t  sample_rate 
)

Set the input sample rate of the SDK. It must always be the same as the system's audio I/O sample rate or the decoding will fail.

Parameters
sdkA pointer to the SDK structure.
sample_rateThe sample rate wanted for the input.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_set_listen_to_self()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_listen_to_self ( chirp_sdk_t sdk,
bool  listen_to_self 
)

Set the listen to self status of the SDK.

Parameters
sdkA pointer to the SDK structure.
listen_to_selfTrue: The SDK will attempt to decode the payloads it sends. False: The SDK will ignore the payloads it sends.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_set_output_sample_rate()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_output_sample_rate ( chirp_sdk_t sdk,
uint32_t  sample_rate 
)

Set the output sample rate of the SDK. It must always be the same as the system's audio I/O sample rate or the encoding will be distorted.

Parameters
sdkA pointer to the SDK structure.
sample_rateThe sample rate wanted for the output.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_set_transmission_channel()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_transmission_channel ( chirp_sdk_t sdk,
uint8_t  channel 
)

Set the channel on which the data will be sent. Allowed values are between 0 and chirp_sdk_get_channel_count() - 1.

Parameters
sdkA pointer to the SDK structure.
channelThe channel number on which the data should be sent.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_set_volume()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_set_volume ( chirp_sdk_t sdk,
float  volume 
)

Set the volume of the output of the SDK.

Parameters
sdkA pointer to the SDK structure.
volumeThe volume of the output wanted, between 0 and 1. 1 being maximum volume and 0 being silent.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_start()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_start ( chirp_sdk_t sdk)

Start the SDK and the audio processing. From this call, it is possible to send and receive data.

Parameters
sdkA pointer to the SDK structure.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ chirp_sdk_stop()

PUBLIC_SYM chirp_sdk_error_code_t chirp_sdk_stop ( chirp_sdk_t sdk)

Stop the SDK and the audio processing. Once this function is called, some internal structures will be reset and any data being sent won't be recoverable.

Parameters
sdkA pointer to the SDK structure.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ del_chirp_sdk()

PUBLIC_SYM chirp_sdk_error_code_t del_chirp_sdk ( chirp_sdk_t **  sdk)

Release the SDK. This function should be the last one to be called among all the API functions.

During the program life time, this function should be called only one time.

Parameters
sdkA pointer to the SDK structure that will be deleted.
Returns
An error code resulting from the call. CHIRP_SDK_OK will be returned if everything went well.

◆ new_chirp_sdk()

PUBLIC_SYM chirp_sdk_t* new_chirp_sdk ( const char *  key,
const char *  secret 
)

Allocate the memory and create the SDK structure. This function should be the first one to be called among all the API functions.

During the program life time, this function should be called only one time.

Parameters
keyThe application key coming from your Chirp Account.
secretThe application secret coming from your Chirp Account.
Returns
A pointer to the newly allocated SDK structure.