Tizen Native API  5.0
Multi assistant

The Multi assistant provides functions for supporting users to use several assistants.

Copyright (c) 2011-2018 Samsung Electronics Co., Ltd All Rights Reserved

Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Required Header

#include <multi_assistant.h>

Overview

A main function of Voice Control API register command and gets notification for recognition result. Applications can add their own commands and be provided result when their command is recognized by user voice input. To use of Voice Control, use the following steps:
1. Initialize
2. Register callback functions for notifications
3. Connect to voice control service asynchronously. The state should be changed to Ready
4. Make command list as the following step and Step 4 is called repeatedly for each command which an application wants
4-1. Create command list handle
4-2. Create command handle
4-3. Set command and type for command handle
4-4. Add command handle to command list
5. Set command list for recognition
6. Set an invocation name for an application
7. Get recognition results
8. Request the dialogue
9. If an application wants to finish voice control,
9-1. Destroy command and command list handle
9-2. Deinitialize
An application can obtain command handle from command list, and also get information from handle. The Voice Control API also notifies you (by callback mechanism) when the states of client and service are changed, command is recognized, current language is changed or error occurred. An application should register callback functions: vc_state_changed_cb(), vc_service_state_changed_cb(), vc_result_cb(), vc_current_language_changed_cb(), vc_error_cb().

State Diagram

The following diagram shows the life cycle and the states of the Voice Control.

capi_uix_voice_control_state_diagram.png
<State diagram>

The following diagram shows the states of Voice Control service.

capi_uix_voice_control_service_state_diagram.png
<Service state diagram>

State Transitions

FUNCTION PRE-STATE POST-STATE SYNC TYPE
vc_initialize() None Initialized SYNC
vc_deinitialize() Initialized None SYNC
vc_prepare() Initialized Ready ASYNC
vc_unprepare() Ready Initialized SYNC

State Dependent Function Calls

The following table shows state-dependent function calls. It is forbidden to call functions listed below in wrong states. Violation of this rule may result in an unpredictable behavior.

FUNCTION VALID STATES DESCRIPTION
vc_initialize() None All functions must be called after vc_initialize()
vc_deinitialize() Initialized, Ready This function should be called when an application want to finalize voice control using
vc_prepare() Initialized This function works asynchronously. If service start is failed, application gets the error callback.
vc_unprepare() Ready
vc_foreach_supported_languages() Initialized, Ready
vc_get_current_language() Initialized, Ready
vc_get_state() Initialized, Ready
vc_get_service_state() Initialized, Ready
vc_get_result() Ready
vc_get_system_command_list() Ready
vc_set_command_list() Ready
vc_unset_command_list() Ready
vc_set_invocation_name() Ready
vc_set_server_dialog() Ready
vc_request_dialog() Ready
vc_set_result_cb()
vc_unset_result_cb()
vc_set_state_changed_cb()
vc_unset_state_changed_cb()
vc_set_service_state_changed_cb()
vc_unset_service_state_changed_cb()
vc_set_current_language_changed_cb()
vc_unset_current_language_changed_cb()
vc_set_error_cb()
vc_unset_error_cb()
Initialized All callback function should be registered in Initialized state

Related Features

This API is related with the following features:

Copyright (c) 2011-2018 Samsung Electronics Co., Ltd All Rights Reserved

Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Typedefs

typedef void(* ma_state_changed_cb )(ma_state_e previous, ma_state_e current, void *user_data)
 Called when the client state is changed.
typedef void(* ma_error_cb )(ma_error_e reason, void *user_data)
 Called when the error is occurred.
typedef void(* ma_language_changed_cb )(const char *previous, const char *current, void *user_data)
 Called when the default language is changed.
typedef void(* ma_audio_streaming_cb )(ma_audio_streaming_event_e event, char *buffer, int len, void *user_data)
 Called when the multi-assistant service sends audio streaming.

Typedef Documentation

typedef void(* ma_audio_streaming_cb)(ma_audio_streaming_event_e event, char *buffer, int len, void *user_data)

Called when the multi-assistant service sends audio streaming.

Since :
5.0
Remarks:
The buffer should not be released and can be used only in the callback. To use outside, make a copy.
Parameters:
[in]eventThe audio streaming event
[in]bufferThe audio streaming data
[in]lenThe length of the audio streaming data
[in]user_dataThe user data passed from the callback registration function
See also:
ma_set_audio_streaming_cb()
ma_unset_audio_streaming_cb()
typedef void(* ma_error_cb)(ma_error_e reason, void *user_data)

Called when the error is occurred.

The following error codes can be received:
MA_ERROR_NONE: Success
MA_ERROR_OUT_OF_MEMORY: Out of Memory
MA_ERROR_IO_ERROR: I/O error
MA_ERROR_INVALID_PARAMETER: Invalid parameter
MA_ERROR_TIMED_OUT: No answer from service
MA_ERROR_RECORDER_BUSY: Busy recorder
MA_ERROR_PERMISSION_DENIED: Permission denied
MA_ERROR_NOT_SUPPORTED: Multi-assistant NOT supported
MA_ERROR_INVALID_STATE: Invalid state
MA_ERROR_INVALID_LANGUAGE: Invalid language
MA_ERROR_ENGINE_NOT_FOUND: No available engine
MA_ERROR_OPERATION_FAILED: Operation failed
MA_ERROR_SERVICE_RESET: Service daemon reset
MA_ERROR_NOT_SUPPORTED_FEATURE: Not supported feature of current engine

Since :
5.0
Parameters:
[in]reasonThe error reason
[in]user_dataThe user data passed from the callback registration function
typedef void(* ma_language_changed_cb)(const char *previous, const char *current, void *user_data)

Called when the default language is changed.

Since :
5.0
Remarks:
The previous can be used only in the callback. To use outside, make a copy. The current can be used only in the callback. To use outside, make a copy.
Parameters:
[in]previousThe previous language
[in]currentThe current language
[in]user_dataThe user data passed from the callback registration function
See also:
ma_set_language_changed_cb()
ma_unset_language_changed_cb()
typedef void(* ma_state_changed_cb)(ma_state_e previous, ma_state_e current, void *user_data)

Called when the client state is changed.

Since :
5.0
Parameters:
[in]previousThe previous state
[in]currentThe current state
[in]user_dataThe user data passed from the callback registration function

Enumeration Type Documentation

Enumerations for ASR result events.

Since :
5.0
Enumerator:
MA_ASR_RESULT_EVENT_PARTIAL_RESULT 

ASR result event for partial result

MA_ASR_RESULT_EVENT_FINAL_RESULT 

ASR result event for final result

MA_ASR_RESULT_EVENT_ERROR 

ASR result event for error

Enumerations for audio channels.

Since :
5.0
Enumerator:
MA_AUDIO_CHANNEL_MONO 

1 channel, mono

MA_AUDIO_CHANNEL_STEREO 

2 channels, stereo

Enumerations for multi-assistant audio streaming events.

Since :
5.0
Enumerator:
MA_AUDIO_STREAMING_EVENT_FAIL 

Failed

MA_AUDIO_STREAMING_EVENT_START 

Start event

MA_AUDIO_STREAMING_EVENT_CONTINUE 

Continue event

MA_AUDIO_STREAMING_EVENT_FINISH 

Finish event

Enumerations for audio types.

Since :
5.0
Enumerator:
MA_AUDIO_TYPE_PCM_S16_LE 

Signed 16bit audio type, Little endian

MA_AUDIO_TYPE_PCM_U8 

Unsigned 8bit audio type

enum ma_error_e

Enumerations for multi-assistant error codes.

Since :
5.0
Enumerator:
MA_ERROR_NONE 

Successful

MA_ERROR_OUT_OF_MEMORY 

Out of Memory

MA_ERROR_IO_ERROR 

I/O error

MA_ERROR_INVALID_PARAMETER 

Invalid parameter

MA_ERROR_TIMED_OUT 

No answer from service

MA_ERROR_RECORDER_BUSY 

Busy recorder

MA_ERROR_PERMISSION_DENIED 

Permission denied

MA_ERROR_NOT_SUPPORTED 

Multi-assistant NOT supported

MA_ERROR_INVALID_STATE 

Invalid state

MA_ERROR_INVALID_LANGUAGE 

Invalid language

MA_ERROR_ENGINE_NOT_FOUND 

No available engine

MA_ERROR_OPERATION_FAILED 

Operation failed

MA_ERROR_SERVICE_RESET 

Service daemon reset

MA_ERROR_NOT_SUPPORTED_FEATURE 

Not supported feature of current engine

enum ma_state_e

Enumerations for multi-assistant client state.

Since :
5.0
Enumerator:
MA_STATE_NONE 

'None' state

MA_STATE_INITIALIZED 

'Initialized' state

MA_STATE_READY 

'Ready' state