Extension API Reference¶

extension_api.h
extension_types.h
extension_support.h
extension_support.hpp

extension_api.h ¶

Base Extension functions.

This file defines base functions that must be implemented by a Quasar extension. These are called to load and destroy the extension.

Defines

EXPORT¶

Functions

quasar_ext_info_t *quasar_ext_load(void)¶

Loads this extension.

This function should only populate a quasar_ext_info_t struct with this extension’s info and return it. Allocations for resources required by this extension should be performed in quasar_ext_info_t::init instead.

Returns: pointer to a populated quasar_ext_info_t struct if successful, nullptr otherwise

void quasar_ext_destroy(quasar_ext_info_t *info)¶

Destroys this extension.

This function should extension any resources allocated for the quasar_ext_info_t struct (as well as the struct instance itself if necessary)

See also

quasar_ext_info_t

Parameters: info – [in] Extension info data

extension_types.h ¶

Types used by the Extension API.

This file defines types used by the Extension API. Included by extension_api.h.

Defines

QUASAR_API_VERSION¶: Quasar extension API version.

Typedefs

typedef void *quasar_settings_t¶

Handle for creating and storing extension settings.

This handle is opaque to the front facing API.

See also

extension_support.h

typedef void *quasar_selection_options_t¶

Handle for creating and storing selection options in a selection type setting.

This handle is opaque to the front facing API.

See also

extension_support.h

typedef void *quasar_ext_handle¶: Type for the extension handle pointer.

typedef void *quasar_data_handle¶

Handle type for storing return data.

See also

extension_support.h, quasar_ext_info_t.get_data

typedef bool (*ext_info_call_t)(quasar_ext_handle)¶

Function pointer type for the quasar_ext_info_t::init and quasar_ext_info_t::shutdown functions.

typedef quasar_settings_t *(*ext_create_settings_call_t)(quasar_ext_handle)¶

Function pointer type for the quasar_ext_info_t::create_settings function.

See also

quasar_ext_info_t.create_settings

typedef void (*ext_settings_call_t)(quasar_settings_t*)¶

Function pointer type for settings related functions, like quasar_ext_info_t::update.

See also

quasar_ext_info_t.update

typedef bool (*ext_get_data_call_t)(size_t, quasar_data_handle, char*)¶

Function pointer type for the quasar_ext_info_t::get_data function.

See also

quasar_ext_info_t.get_data

Enums

enum quasar_log_level_t¶

Defines valid log levels for logging.

Values:

enumerator QUASAR_LOG_DEBUG¶: Debug level.

enumerator QUASAR_LOG_INFO¶: Info level.

enumerator QUASAR_LOG_WARNING¶: Warning level.

enumerator QUASAR_LOG_ERROR¶: Error level.

enumerator QUASAR_LOG_CRITICAL¶: Critical level.

enum quasar_polling_type_t¶

Defines valid polling type values.

Positive values determine extension timed data refresh rate

See also

quasar_data_source_t.rate

Values:

enumerator QUASAR_POLLING_SIGNALED¶: Extension is responsible for signaling data send when data is ready.

enumerator QUASAR_POLLING_CLIENT¶: Data is polled on-demand by the client.

struct quasar_data_source_t¶

#include <extension_types.h>

Struct for defining Data Sources.

Defines the Data Sources available to widgets provided by this extension.

See also

quasar_ext_info_t.dataSources

Public Members

char name[32]¶: Identifier for this data source.

int64_t rate¶

Default rate of refresh for this Data Source (in microseconds). See quasar_polling_type_t for additional polling options.

uint64_t validtime¶

For client polled data (QUASAR_POLLING_CLIENT), this defines the duration in milliseconds that newly retrieved data is cached remains valid. Additional poll requests during this valid duration will return the cached data. A value of 0 means the data is never cached. Not used for other polling types.

See also

quasar_polling_type_t

size_t uid¶: uid assigned to this Data Source by Quasar. An integer uid is assigned to each Data Source by Quasar to reduce discrepancies and avoid string comparisons. This uid is passed to quasar_ext_info_t::get_data.

struct quasar_ext_info_fields_t¶

#include <extension_types.h>

Struct for defining information and description fields for the extension.

Defines the information and description fields for this extension.

See also

quasar_ext_info_t.fields

Public Members

char name[32]¶: A unique short identifier for this extension. Used by widgets to identify and subscribe to this extension.

char fullname[64]¶: Full name of this extension.

char version[64]¶: Version string.

char author[64]¶: Author.

char description[256]¶: Extension description.

char url[256]¶: Extension website url, if any.

struct quasar_ext_info_t¶

#include <extension_types.h>

Struct for defining a Quasar extension.

An extension should populate this struct with data upon initialization and return it to Quasar when quasar_ext_load() is called

See also

quasar_ext_load()

Public Members

int api_version¶: API version. Should always be initialized to QUASAR_API_VERSION.

quasar_ext_info_fields_t *fields¶: Extension info/description fields. Must be initialized.

size_t numDataSources¶: Number of Data Sources provided by this extension.

quasar_data_source_t *dataSources¶

Array of Data Sources provided by this extension.

See also

quasar_data_source_t

ext_info_call_t init¶

bool init(quasar_ext_handle handle)

Attention

Extensions are REQUIRED to implement this function.

This function should save data source uids assigned by Quasar as well as initialize any resources needed by the extension. The extension’s handle will be passed into this function. This function should save the handle.

Return: true if success, false otherwise

ext_info_call_t shutdown¶

bool shutdown(quasar_ext_handle handle)

Attention

Extensions are REQUIRED to implement this function.

This function should cleanup any resources initialized by this extension.

Return: Should always return true

ext_get_data_call_t get_data¶

bool get_data(size_t uid, quasar_data_handle handle, char* args)

Attention

Extensions are REQUIRED to implement this function.

Retrieves the data of a specific Data Source entry.

args contains a null terminate string that consists of any arguments passed to the Data Source entry, if arguments are accepted. args is null if no arguments are passed.

Use support functions in extension_support.h to populate data into handle.

Important

This function needs to be both re-entrant and thread-safe.

Return: true if success, false otherwise

ext_create_settings_call_t create_settings¶

quasar_settings_t* create_settings(quasar_ext_handle handle), OPTIONAL

Creates extension settings (and corresponding UI elements) if any.

Return: quasar_settings_t pointer if successful, nullptr otherwise

ext_settings_call_t update¶

void update(quasar_settings_t* settings), OPTIONAL

This function should update local settings values.

extension_support.h ¶

Extension API support functionality.

This file defines functions that augment extension functionality

Functions

char *quasar_strcpy(char *dest, size_t destSize, const char *src, size_t srcSize)¶

A custom string copy implementation to work around inherently unsafe C library functions.

If src contains a null terminator before srcSize is reached, this function will correctly terminate. If the [0, srcSize) portion of src does not contain a null terminator, it will copy up to src[srcSize-1] and terminate. If destSize is smaller than src at null terminator or srcSize, it will copy up to destSize-2 and terminate. Assuming that the copy occurred, dest will be null terminated.

Parameters

dest – [in] Destination buffer
destSize – [in] Size of destination buffer
src – [in] Source string
srcSize – [in] Maximum size of source string

Returns

dest

void quasar_log(quasar_log_level_t level, const char *msg)¶

Logs a message to Quasar console.

See also

quasar_log_level_t

Parameters

level – [in] Log level
msg – [in] Log message

quasar_settings_t *quasar_create_settings(quasar_ext_handle handle)¶

Returns an instance of quasar_settings_t.

Use in quasar_ext_info_t::create_settings to create extension settings. Ensure that only a single instance is used per extension.

Parameters: handle – [in] Extension handle
Returns: quasar_settings_t instance if successful, nullptr otherwise

quasar_selection_options_t *quasar_create_selection_setting(void)¶

Creates a new quasar_selection_options_t setting.

Use with quasar_add_selection_setting() after populating options.

Returns: quasar_selection_options_t instance if successful, nullptr otherwise

void quasar_free_selection_setting(quasar_selection_options_t *handle)¶

Deletes a quasar_selection_options_t setting. Should only be used in error case exits.

Parameters: handle – [in] Handle to instance to be freed

quasar_data_handle quasar_set_data_string(quasar_data_handle hData, const char *data)¶

Sets the return data to be a null terminated string.

Parameters

hData – [in] Data handle
data – [in] Data to set

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_int(quasar_data_handle hData, int data)¶

Sets the return data to be an integer.

Parameters

hData – [in] Data handle
data – [in] Data to set

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_double(quasar_data_handle hData, double data)¶

Sets the return data to be a floating point double.

Parameters

hData – [in] Data handle
data – [in] Data to set

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_bool(quasar_data_handle hData, bool data)¶

Sets the return data to be a bool.

Parameters

hData – [in] Data handle
data – [in] Data to set

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_json(quasar_data_handle hData, const char *data)¶

Sets the return data to be a valid JSON object string.

Parameters

hData – [in] Data handle
data – [in] Data to set

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_string_array(quasar_data_handle hData, char **arr, size_t len)¶

Sets the return data to be an array of null terminated strings.

Parameters

hData – [in] Data handle
arr – [in] Array of data to set
len – [in] Length of array

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_int_array(quasar_data_handle hData, int *arr, size_t len)¶

Sets the return data to be an array of integers.

Parameters

hData – [in] Data handle
arr – [in] Array of data to set
len – [in] Length of array

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_float_array(quasar_data_handle hData, float *arr, size_t len)¶

Sets the return data to be an array of floats.

Parameters

hData – [in] Data handle
arr – [in] Array of data to set
len – [in] Length of array

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_double_array(quasar_data_handle hData, double *arr, size_t len)¶

Sets the return data to be an array of doubles.

Parameters

hData – [in] Data handle
arr – [in] Array of data to set
len – [in] Length of array

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_null(quasar_data_handle hData)¶

Sets the return data to be null.

Parameters: hData – [in] Data handle
Returns: Data handle if successful, nullptr otherwise

quasar_data_handle quasar_append_error(quasar_data_handle hData, const char *err)¶

Adds an error to the return data to be sent back to the client.

Parameters

hData – [in] Data handle
err – [in] Error to add

Returns

Data handle if successful, nullptr otherwise

quasar_settings_t *quasar_add_int_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name, const char *description, int min, int max, int step, int dflt)¶

Creates an integer setting in extension settings.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting
description – [in] Description for the setting
min – [in] Minimum value
max – [in] Maximum value
step – [in] Incremental step
dflt – [in] Default value

Returns

The settings handle if successful, nullptr otherwise

quasar_settings_t *quasar_add_bool_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name, const char *description, bool dflt)¶

Creates a bool setting in extension settings.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting
description – [in] Description for the setting
dflt – [in] Default value

Returns

The settings handle if successful, nullptr otherwise

quasar_settings_t *quasar_add_double_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name, const char *description, double min, double max, double step, double dflt)¶

Creates a double setting in extension settings.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting
description – [in] Description for the setting
min – [in] Minimum value
max – [in] Maximum value
step – [in] Incremental step
dflt – [in] Default value

Returns

The settings handle if successful, nullptr otherwise

quasar_settings_t *quasar_add_string_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name, const char *description, const char *dflt, bool password)¶

Creates a string type setting in extension settings.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting
description – [in] Description for the setting
dflt – [in] Default value (if any)
password – [in] Whether this field is a password/obscured field in the UI

Returns

The settings handle if successful, nullptr otherwise

quasar_settings_t *quasar_add_selection_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name, const char *description, quasar_selection_options_t *select)¶

Creates a selection type setting in extension settings.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting
description – [in] Description for the setting
select – [in] Handle to the selection setting instance (takes ownership)

Returns

The settings handle if successful, nullptr otherwise

quasar_selection_options_t *quasar_add_selection_option(quasar_selection_options_t *select, const char *name, const char *value)¶

Creates a selection type setting in extension settings.

Parameters

select – [in] The selection setting handle
name – [in] Name of the option (shown in UI)
value – [in] Actual value of the option

Returns

The setting handle if successful, nullptr otherwise

intmax_t quasar_get_int_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name)¶

Retrieves an integer setting from Quasar.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting

Returns

Value of the setting if successful, default value otherwise

uintmax_t quasar_get_uint_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name)¶

Retrieves an unsigned integer setting from Quasar.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting

Returns

Value of the setting if successful, default value otherwise

bool quasar_get_bool_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name)¶

Retrieves a bool setting from Quasar.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting

Returns

Value of the setting if successful, default value otherwise

double quasar_get_double_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name)¶

Retrieves a double setting from Quasar.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting

Returns

Value of the setting if successful, default value otherwise

bool quasar_get_string_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name, char *buf, size_t size)¶

Retrieves a string setting from Quasar.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting
buf – [in] Buffer to copy results to
size – [in] Size of buffer

Returns

true if successful, false otherwise

bool quasar_get_selection_setting(quasar_ext_handle handle, quasar_settings_t *settings, const char *name, char *buf, size_t size)¶

Retrieves a selection setting from Quasar.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting
buf – [in] Buffer to copy results to
size – [in] Size of buffer

Returns

true if successful, false otherwise

void quasar_signal_data_ready(quasar_ext_handle handle, const char *source)¶

Signals to Quasar that data is ready to be sent to clients.

This function is for Data Sources with quasar_data_source_t::rate set to QUASAR_POLLING_CLIENT or QUASAR_POLLING_SIGNALED. This function signals to Quasar that the data for the specified source is ready to be sent.

See also

quasar_data_source_t.rate

Parameters

handle – [in] Extension handle
source – [in] Data Source identifier

void quasar_signal_wait_processed(quasar_ext_handle handle, const char *source)¶

Waits for a set of data to be sent to clients before processing the next set.

This function is for Data Sources with quasar_data_source_t::rate set to QUASAR_POLLING_SIGNALED. This function can be used to allow a thread to wait until a set of data has been consumed before moving on to processing the next set.

See also

quasar_data_source_t.rate

Parameters

handle – [in] Extension handle
source – [in] Data Source identifier

void quasar_set_storage_string(quasar_ext_handle handle, const char *name, const char *data)¶

Stores a string type data.

Parameters

handle – [in] Extension handle
name – [in] Data name
data – [in] Data to set

void quasar_set_storage_int(quasar_ext_handle handle, const char *name, int data)¶

Stores a int type data.

Parameters

handle – [in] Extension handle
name – [in] Data name
data – [in] Data to set

void quasar_set_storage_double(quasar_ext_handle handle, const char *name, double data)¶

Stores a double type data.

Parameters

handle – [in] Extension handle
name – [in] Data name
data – [in] Data to set

void quasar_set_storage_bool(quasar_ext_handle handle, const char *name, bool data)¶

Stores a bool type data.

Parameters

handle – [in] Extension handle
name – [in] Data name
data – [in] Data to set

bool quasar_get_storage_string(quasar_ext_handle handle, const char *name, char *buf, size_t size)¶

Gets a string type data from storage.

Parameters

handle – [in] Extension handle
name – [in] Data name
buf – [in] Buffer to copy results to
size – [in] Size of buffer

Returns

true if successful, false otherwise

bool quasar_get_storage_int(quasar_ext_handle handle, const char *name, int *buf)¶

Gets a int type data from storage.

Parameters

handle – [in] Extension handle
name – [in] Data name
buf – [in] Buffer to copy results to

Returns

true if successful, false otherwise

bool quasar_get_storage_double(quasar_ext_handle handle, const char *name, double *buf)¶

Gets a double type data from storage.

Parameters

handle – [in] Extension handle
name – [in] Data name
buf – [in] Buffer to copy results to

Returns

true if successful, false otherwise

bool quasar_get_storage_bool(quasar_ext_handle handle, const char *name, bool *buf)¶

Gets a bool type data from storage.

Parameters

handle – [in] Extension handle
name – [in] Data name
buf – [in] Buffer to copy results to

Returns

true if successful, false otherwise

extension_support.hpp ¶

C++ specific Extension API support functions.

Attention

Functions in this file passes STL types across library boundaries. ENSURE THAT CRT LINKAGE IS SET TO DYNAMIC ON WINDOWS WHEN USING THESE!!!

Functions

quasar_data_handle quasar_set_data_string_hpp(quasar_data_handle hData, std::string_view data)¶

Sets the return data to be a null terminated string.

Parameters

hData – [in] Data handle
data – [in] Data to set

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_json_hpp(quasar_data_handle hData, std::string_view data)¶

Sets the return data to be a valid JSON object string.

Parameters

hData – [in] Data handle
data – [in] Data to set

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_string_vector(quasar_data_handle hData, const std::vector<std::string> &vec)¶

Sets the return data to be an array of null terminated strings.

Parameters

hData – [in] Data handle
vec – [in] Vector of data to set

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_int_vector(quasar_data_handle hData, const std::vector<int> &vec)¶

Sets the return data to be an array of integers.

Parameters

hData – [in] Data handle
vec – [in] Vector of data to set

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_float_vector(quasar_data_handle hData, const std::vector<float> &vec)¶

Sets the return data to be an array of floats.

Parameters

hData – [in] Data handle
vec – [in] Vector of data to set

Returns

Data handle if successful, nullptr otherwise

quasar_data_handle quasar_set_data_double_vector(quasar_data_handle hData, const std::vector<double> &vec)¶

Sets the return data to be an array of doubles.

Parameters

hData – [in] Data handle
vec – [in] Vector of data to set

Returns

Data handle if successful, nullptr otherwise

std::string_view quasar_get_string_setting_hpp(quasar_ext_handle handle, quasar_settings_t *settings, std::string_view name)¶

Retrieves a string setting from Quasar.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting

Returns

string setting if successful, empty string_view otherwise

std::string_view quasar_get_selection_setting_hpp(quasar_ext_handle handle, quasar_settings_t *settings, std::string_view name)¶

Retrieves a selection setting from Quasar.

Parameters

handle – [in] Extension handle
settings – [in] The extension settings handle
name – [in] Name of the setting

Returns

string setting if successful, empty string_view otherwise

Extension API Reference¶

extension_api.h¶

extension_types.h¶

extension_support.h¶

extension_support.hpp¶

extension_api.h ¶

extension_types.h ¶

extension_support.h ¶

extension_support.hpp ¶