CUEEngine

A base singleton class to access CUEEngine API.

#import <CUEEngine.h>

Instance Methods

(void)	- didEnterForeground
	Call it to refresh CUEEngine if you are entered foreground.
(void)	- setReceiverCallback:
	Setup CUEEngine receiver callback which is fired on a detected CUE trigger.
(void)	- setupWithAPIKey:
	Setup CUEEngine using an api key (only)
(void)	- setupWithAPIKey:andWithConfig:
	Setup CUEEngine using an api key and a config string.
(void)	- startListening
	Start CUEEngine listening to detect CUE triggers.
(void)	- stopListening
	Stop CUEEngine listening, triggers won't be detected.
(BOOL)	- isListening
	Check is CUEEngine actualy listening?
(BOOL)	- didSetup
	Check is CUEEngine actualy initialized?
(void)	- feed:withNSamps:andWithSRate:
	Direcly feeds buffer of floats to CUEEngine.
(CUE_ENGINE_ERROR)	- queueLive:
	Queue a live trigger.
(CUE_ENGINE_ERROR)	- queueLL:
	Queue a LL (Low Latency) trigger.
(CUE_ENGINE_ERROR)	- queueTrigger:
	Queue a trigger.
(CUE_ENGINE_ERROR)	- queueTriggerAsNumber:
	Queue a trigger as a number.
(CUE_ENGINE_ERROR)	- queueMultiTrigger:
	Queue a multi trigger (usually 2 triggers) at once.
(CUE_ENGINE_ERROR)	- queueMultiTriggerAsNumber:
	Queue a multi trigger as a number.
(CUE_ENGINE_ERROR)	- queueData:
	Queue a data trigger.
(CUE_ENGINE_ERROR)	- queueMessage:
	Queue a message trigger.
(nonnull NSString *)	- getEngineDeviceId
	method to get CUEEngine UUID for the currnet device
(void)	- setDefaultGeneration:
	Set a CUEEngine default generation.
(void)	- refreshPayloads:
	Refresh payloads provided by a CUEPortal infrastructure with a callback fired after an actual refresh.
(nonnull NSDictionary *)	- getPayload:
	Get payload asossiated with a given trigger.

Class Methods

didEnterForeground

- (void) didEnterForeground

Call to refresh CUEEngine if you are in the foreground.

didSetup

- (BOOL) didSetup

Check if CUEEngine is actually initialized

Returns

YES if CUEEngine is already initialized, or NO otherwise.

feed:withNSamps:andWithSRate:

- (void) feed:	(null_unspecified float *)	bufOfFloats
withNSamps:	(int)	nSamps
andWithSRate:	(double)	sRate

Directly feeds a buffer of floats to CUEEngine.

Parameters

bufOfFloats	Buffer of floats to feed
nSamps	Number of float samples to feed
sRate	Frequency rate of a provided signal

Warning

This is unsafe, there are no runtime checks (asserts, exceptions). Please do not send the buffer more than nSamps samples. Do not use this function while the engine is listening. Use this only after a call to setup.

getEngineDeviceId

- (nonnull NSString*) getEngineDeviceId

method to get CUEEngine UUID for the current device

Returns

CUEEngine device UUID as NSSTring

getPayload:

- (nonnull NSDictionary*) getPayload:

(nonnull NSString *)

trigger

Get a payload associated with a given trigger.

The set of payloads is provided by the CUE Portal infrastructure. Each payload can be associated with trigger or multi-trigger indices.

Parameters

trigger

indices (e.g. 1.2.3, 1.2.3.4.5.6, ...) of a given trigger.

Returns

Payload as NSDictinary. Can be empty if there is no payload for a given index.

See also

CUETrigger.rawIndices

CUEEngineModeTrigger

CUEEngineModeMultitrigger

isListening

- (BOOL) isListening

Check if CUEEngine actually listening

Returns

YES if CUEEngine is listening or NO otherwise.

queueData:

- (CUE_ENGINE_ERROR) queueData:

(nonnull NSString *)

data

Queue a data trigger.

Parameters

data	is a ASCII string for generation 2, or a n-symbols sequence (e.g 1.2.3.4...) for generation 1

Returns

One of CUE_ENGINE_ERROR values. In the case of success queueLL returns 0 (or CUE_ENGINE_SUCCESS). Otherwise it returns a negative value. See the list of possible return values below.

CUE_ENGINE_SUCCESS

CUE_ENGINE_ERR_G1_NUMBER_OF_SYMBOLS_EXCEEDED

CUE_ENGINE_ERR_SYMBOL_NOT_A_NUMBER

CUE_ENGINE_ERR_INDEX_VALUE_EXCEEDED

CUE_ENGINE_ERR_NO_ACTIVE_TRANSMITTER

See also

CUE_ENGINE_ERROR

queueLive:

- (CUE_ENGINE_ERROR) queueLive:

(nonnull NSString *)

message

Queue a live trigger.

Parameters

message

value of a live trigger witch is number between 0 and 461

Remarks

works for engine generation 1 only

Returns

One of CUE_ENGINE_ERROR values. In the case of success queueLL returns 0 (or CUE_ENGINE_SUCCESS). Otherwise it returns a negative value. See the list of possible return values below.

CUE_ENGINE_SUCCESS

CUE_ENGINE_ERR_NUMBER_OF_SYMBOLS_MISMATCH

CUE_ENGINE_ERR_SYMBOL_NOT_A_NUMBER

CUE_ENGINE_ERR_INDEX_VALUE_EXCEEDED

CUE_ENGINE_ERR_G2_QUEUE_LIVE_UNSUPPORTED

CUE_ENGINE_ERR_NO_ACTIVE_TRANSMITTER

See also

CUE_ENGINE_ERROR

queueLL:

- (CUE_ENGINE_ERROR) queueLL:

(nonnull NSString *)

message

Queue a LL (Low Latency) trigger.

Parameters

message

A value of a live trigger witch is number between 0 and 461

Remarks

Works for engine generation 2 only

Returns

One of CUE_ENGINE_ERROR values. In the case of success queueLL returns 0 (or CUE_ENGINE_SUCCESS). Otherwise it returns a negative value. See the list of possible return values below.

CUE_ENGINE_SUCCESS - no errors

CUE_ENGINE_ERR_SYMBOL_NOT_A_NUMBER - one symbol in the LL sequence is not a number.

CUE_ENGINE_ERR_INDEX_VALUE_EXCEEDED - value of one symbol in the LL sequence is more then its possible maximum.

CUE_ENGINE_ERR_G2_LL_IS_ON_IN_BASIC_CAN_NOT_QUEUE - LL is already on.

CUE_ENGINE_ERR_G1_QUEUE_LL_UNSUPPORTED - it's impossible to queue LL sequence in a G1 mode.

CUE_ENGINE_ERR_G2_QUEUE_LL_MODE_LL_ONLY_OR_MODE_BASIC_SHOULD_BE_SET - it's possible to queue LL trigger only in a config 'basic' or 'll_only' mode.

CUE_ENGINE_ERR_NO_ACTIVE_TRANSMITTER - CUEEngine didn't initialize the transmitter. Please try to queue a LL trigger later.

See also

CUE_ENGINE_ERROR

queueMessage:

- (CUE_ENGINE_ERROR) queueMessage:

(nonnull NSString *)

message

Queue a message trigger.

Parameters

message

is a ASCII string for generation 1 or generation 2

Returns

One of CUE_ENGINE_ERROR values. In the case of success queueLL returns 0 (or CUE_ENGINE_SUCCESS). Otherwise it returns a negative value. See the list of possible return values below.

CUE_ENGINE_SUCCESS

CUE_ENGINE_ERR_NO_ACTIVE_TRANSMITTER

See also

CUE_ENGINE_ERROR

queueMultiTrigger:

- (CUE_ENGINE_ERROR) queueMultiTrigger:

(nonnull NSString *)

multiTrigger

Queue a multi trigger (usually 2 triggers) at once.

Parameters

multiTrigger

is a 3*l symbols trigger (e.g. 1.2.3.4.5.6), where l is a number of multi trigger carrier frequencies and each symbol is a number between 0 and 461

Returns

One of CUE_ENGINE_ERROR values. In the case of success queueLL returns 0 (or CUE_ENGINE_SUCCESS). Otherwise it returns a negative value. See the list of possible return values below.

CUE_ENGINE_SUCCESS

CUE_ENGINE_ERR_NUMBER_OF_SYMBOLS_MISMATCH

CUE_ENGINE_ERR_SYMBOL_NOT_A_NUMBER

CUE_ENGINE_ERR_INDEX_VALUE_EXCEEDED

CUE_ENGINE_ERR_G1_QUEUE_MULTI_TRIGGER_UNSUPPORTED

CUE_ENGINE_ERR_NO_ACTIVE_TRANSMITTER

queueMultiTriggerAsNumber:

- (CUE_ENGINE_ERROR) queueMultiTriggerAsNumber:

(const long long)

n

Queue a multi trigger as a number.

Remarks

please note that n can not exceed a 64 bit signed integer value

Parameters

n	A number between 0 and 462**(3*l) - 1 where l is a number of multi trigger carrier frequencies in the config

Returns

One of CUE_ENGINE_ERROR values. In the case of success queueLL returns 0 (or CUE_ENGINE_SUCCESS). Otherwise it returns a negative value. See the list of possible return values below.

CUE_ENGINE_SUCCESS

CUE_ENGINE_ERR_MULTI_TRIGGER_AS_NUMBER_MAX_NUMBER_EXCEEDED

CUE_ENGINE_ERR_G1_QUEUE_MULTI_TRIGGER_UNSUPPORTED

CUE_ENGINE_ERR_NO_ACTIVE_TRANSMITTER

See also

CUE_ENGINE_ERROR

queueTrigger:

- (CUE_ENGINE_ERROR) queueTrigger:

(nonnull NSString *)

message

Queue a trigger.

Parameters

message

is a 3-symbols trigger (e.g. 1.2.3), where each symbol is a number between 0 and 461

Returns

One of CUE_ENGINE_ERROR values. In the case of success queueLL returns 0 (or CUE_ENGINE_SUCCESS). Otherwise it returns a negative value. See the list of possible return values below.

CUE_ENGINE_SUCCESS

CUE_ENGINE_ERR_NUMBER_OF_SYMBOLS_MISMATCH

CUE_ENGINE_ERR_SYMBOL_NOT_A_NUMBER

CUE_ENGINE_ERR_INDEX_VALUE_EXCEEDED

CUE_ENGINE_ERR_G2_QUEUE_TRIGGER_NON_BASIC_MODE_IS_USED

CUE_ENGINE_ERR_NO_ACTIVE_TRANSMITTER

See also

CUE_ENGINE_ERROR

queueTriggerAsNumber:

- (CUE_ENGINE_ERROR) queueTriggerAsNumber:

(unsigned long)

n

Queue a trigger as a number.

Parameters

n	is a number between 0 and 98611127

Returns

One of CUE_ENGINE_ERROR values. In the case of success queueLL returns 0 (or CUE_ENGINE_SUCCESS). Otherwise it returns a negative value. See the list of possible return values below.

CUE_ENGINE_SUCCESS

CUE_ENGINE_ERR_TRIGGER_AS_NUMBER_MAX_NUMBER_EXCEEDED

CUE_ENGINE_ERR_G2_QUEUE_TRIGGER_NON_BASIC_MODE_IS_USED

CUE_ENGINE_ERR_NO_ACTIVE_TRANSMITTER

See also

CUE_ENGINE_ERROR

refreshPayloads:

- (void) refreshPayloads:

(nonnull RefreshPayloadsCallback)

blk

Refresh payloads provided by a CUEPortal infrastructure with a callback fired after an actual refresh.

Parameters

blk	callback fired after a payloads refresh

setDefaultGeneration:

- (void) setDefaultGeneration:

(int)

g

Set CUEEngineto the default generation.

Parameters

g	is a CUEEngine generation number. Which can be 1 or 2.

setReceiverCallback:

- (void) setReceiverCallback:

(nonnull ReceiverCallback)

blk

Setup CUEEngine with a receiver callback to be fired upon detecting a CUE trigger.

Parameters

blk	callback which has a CUETrigger value as an input parameter

Remarks

you can set the tone callback at any moment in the life-cycle of the object

setupWithAPIKey:

- (void) setupWithAPIKey:

(nonnull NSString *)

apiKey

Setup CUEEngine using an api key (only)

Parameters

apiKey

The apiKey provided to you as a NSString

Remarks

If you don't have microphone permission before setup, the mobile OS will automatically request it.

setupWithAPIKey:andWithConfig:

- (void) setupWithAPIKey:	(nonnull NSString *)	apiKey
andWithConfig:	(nonnull NSString *)	config

Setup CUEEngine using an api key and a config string.

Parameters

apiKey	The apiKey provided to you as a NSString
config	The engine config string

Remarks

If you don't have microphone permission before you setup, the mobile OS will automatically request it.

sharedInstance

+ (nonnull CUEEngine*) sharedInstance

Access method for the CUEEngine API singleton object

startListening

- (void) startListening

Set CUEEngine to start listening for CUE triggers.

Remarks

This will trigger an assertion failure if the setup didn't complete

stopListening

- (void) stopListening

Set CUEEngine to stop listening for CUE triggers.