A state’s default options are set from the keyboard at creation time and the environment. The Platform layer is then is expected to apply any persisted options it is maintaining. Options are passed into and out of API functions as simple C arrays of km_core_option_item terminated with a KM_CORE_OPTIONS_END sentinel value. A state's options are exposed and manipulatable via the km_core_options API. All option values are of type C string.

During processing when the Platform layer finds a PERSIST action type it should store the updated option in the appropriate place, based on its scope. For RESET the processor will apply the pristine value from the original scope, the Platform layer should update that only if it manages a previously persisted value.

km_core_option_scope enum {#km_core_option_scope}

Description

Specification

enum km_core_option_scope {
  KM_CORE_OPT_UNKNOWN      = 0,
  KM_CORE_OPT_KEYBOARD     = 1,
  KM_CORE_OPT_ENVIRONMENT  = 2,
  KM_CORE_OPT_MAX_SCOPES
};

Values

KM_CORE_OPT_UNKNOWN : An unknown option type. Reserved.

KM_CORE_OPT_KEYBOARD : An option that is defined for the currently active keyboard; not all processors support this type of option. These options are specific to the active keyboard.

KM_CORE_OPT_ENVIRONMENT : Properties of the current environment, often but not necessarily always read-only.

km_core_option_item struct {#km_core_option_item}

Description

Defines a single option to be passed into the Keyman Core from the Platform layer.

Specification

struct km_core_option_item {
  km_core_cp const *   key;
  km_core_cp const *   value;
  uint8_t             scope;
};

#define KM_CORE_OPTIONS_END { 0, 0, 0 }

Members

key : Null-terminated string key for the option

value : Null-terminated string value for the option

scope : Scope which an option belongs to, from km_core_option_scope.

km_core_options_list_size() {#km_core_options_list_size}

Description

Return the length of a terminated km_core_option_item array (options list).

Specification

KMN_API
size_t
km_core_options_list_size(km_core_option_item const *opts);

Parameters

opts : A pointer to a KM_CORE_OPTIONS_END terminated array of km_core_option_item values.

Returns

The number of items in the list, not including terminating item, or 0 if opts is null.

km_core_state_option_lookup

Description

Lookup an option based on its key, in an options list.

Specification

KMN_API
km_core_status
km_core_state_option_lookup(km_core_state const *state,
                      uint8_t scope,
                      km_core_cp const *key,
                      km_core_cp const **value);

Parameters

state : An opaque pointer to a state object.

scope : Which key-value store to interrogate.

key : A UTF-16 string that matches the key in the target km_core_option_item.

value : A pointer to the result variable: A pointer to a UTF-16 string value owned by the state or keyboard object at the time of the call. This pointer is only valid until the next call to any function on this API and should be used immediately.

Returns

KM_CORE_STATUS_OK : On success.

KM_CORE_STATUS_INVALID_ARGUMENT : If non-optional parameters are null, or if the scope is invalid.

KM_CORE_STATUS_KEY_ERROR : The key cannot be found.

km_core_state_options_update() {#km_core_state_options_update}

Description

Adds or updates one or more options from a list of km_core_option_items.

Specification

KMN_API
km_core_status
km_core_state_options_update(km_core_state *state,
                      km_core_option_item const *new_opts);

Parameters

state : An opaque pointer to a state object.

new_opts : An array of km_core_option_item objects to update or add. Must be terminated with KM_CORE_OPTIONS_END.

Returns

KM_CORE_STATUS_OK : On success.

KM_CORE_STATUS_INVALID_ARGUMENT : If non-optional parameters are null.

KM_CORE_STATUS_NO_MEM : In the event an internal memory allocation fails.

KM_CORE_STATUS_KEY_ERROR : The key cannot be found.

km_core_state_options_to_json() {#km_core_state_options_to_json}

Description

Export the contents of a km_core_options array to a JSON formatted document and place it in the supplied buffer, reporting how much space was used. If null is passed as the buffer the number of bytes required is returned in space. If there is insufficent space to hold the document the contents of the buffer is undefined. The returned buffer uses UTF-8 encoding.

Specification

KMN_API
km_core_status
km_core_state_options_to_json(km_core_state const *state,
                       char *buf,
                       size_t *space);

Parameters

state : An opaque pointer to a state object.

buf : A pointer to the buffer to place the C string containing the JSON document into, can be null.

space : A pointer to a size_t variable. This variable must contain the number of bytes available in the buffer pointed to by buf, unless buf is null. On return it will hold how many bytes were used.

Returns

KM_CORE_STATUS_OK : On success.

KM_CORE_STATUS_INVALID_ARGUMENT : If non-optional parameters are null.

KM_CORE_STATUS_NO_MEM : In the event an internal memory allocation fails.