include/multi_assistant_common.h

   1 /*
   2  * Copyright (c) 2018-2019 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_UIFW_MULTI_ASSISTANT_COMMON_H__
  19 #define __TIZEN_UIFW_MULTI_ASSISTANT_COMMON_H__
  20
  21 #include <tizen.h>
  22
  23 /**
  24  * @addtogroup CAPI_UIX_MULTI_ASSISTANT_MODULE
  25  * @{
  26  */
  27
  28
  29 #ifdef __cplusplus
  30 extern "C"
  31 {
  32 #endif
  33
  34 /**
  35  * @brief Enumerations for multi-assistant error codes.
  36  * @since_tizen 5.0
  37  */
  38 typedef enum {
  39         MA_ERROR_NONE = TIZEN_ERROR_NONE,               /**< Successful */
  40         MA_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of Memory */
  41         MA_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
  42         MA_ERROR_INVALID_PARAMETER      = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  43         MA_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT, /**< No answer from service */
  44         MA_ERROR_RECORDER_BUSY = TIZEN_ERROR_RESOURCE_BUSY, /**< Busy recorder */
  45         MA_ERROR_PERMISSION_DENIED      = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
  46         MA_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Multi-assistant NOT supported */
  47         MA_ERROR_INVALID_STATE = TIZEN_ERROR_MULTI_ASSISTANT | 0x011, /**< Invalid state */
  48         MA_ERROR_INVALID_LANGUAGE = TIZEN_ERROR_MULTI_ASSISTANT | 0x012, /**< Invalid language */
  49         MA_ERROR_ENGINE_NOT_FOUND = TIZEN_ERROR_MULTI_ASSISTANT | 0x013, /**< No available engine */
  50         MA_ERROR_OPERATION_FAILED = TIZEN_ERROR_MULTI_ASSISTANT | 0x014, /**< Operation failed */
  51         MA_ERROR_SERVICE_RESET = TIZEN_ERROR_MULTI_ASSISTANT | 0x015, /**< Service daemon reset */
  52         MA_ERROR_NOT_SUPPORTED_FEATURE = TIZEN_ERROR_MULTI_ASSISTANT | 0x016 /**< Not supported feature of current engine */
  53 } ma_error_e;
  54
  55 /**
  56  * @brief Enumerations for multi-assistant client state.
  57  * @since_tizen 5.0
  58  */
  59 typedef enum {
  60         MA_STATE_NONE = 0,                      /**< 'None' state */
  61         MA_STATE_INITIALIZED = 1,       /**< 'Initialized' state */
  62         MA_STATE_READY = 2,                     /**< 'Ready' state */
  63 } ma_state_e;
  64
  65 /**
  66  * @brief Enumerations for multi-assistant audio streaming events.
  67  * @since_tizen 5.0
  68  */
  69 typedef enum {
  70         MA_AUDIO_STREAMING_EVENT_FAIL = -1,             /**< Failed */
  71         MA_AUDIO_STREAMING_EVENT_START = 1,             /**< Start event */
  72         MA_AUDIO_STREAMING_EVENT_CONTINUE = 2,  /**< Continue event */
  73         MA_AUDIO_STREAMING_EVENT_FINISH = 3             /**< Finish event */
  74 } ma_audio_streaming_event_e;
  75
  76 /**
  77  * @brief Enumerations for audio types.
  78  * @since_tizen 5.0
  79  */
  80 typedef enum {
  81         MA_AUDIO_TYPE_PCM_S16_LE = 0,   /**< Signed 16bit audio type, Little endian */
  82         MA_AUDIO_TYPE_PCM_U8                    /**< Unsigned 8bit audio type */
  83 } ma_audio_type_e;
  84
  85 /**
  86  * @brief Enumerations for audio channels.
  87  * @since_tizen 5.0
  88  */
  89 typedef enum {
  90         MA_AUDIO_CHANNEL_MONO = 0,              /**< 1 channel, mono */
  91         MA_AUDIO_CHANNEL_STEREO = 1             /**< 2 channels, stereo */
  92 } ma_audio_channel_e;
  93
  94 /**
  95  * @brief Enumerations for ASR result events.
  96  * @since_tizen 5.0
  97  */
  98 typedef enum {
  99         MA_ASR_RESULT_EVENT_PARTIAL_RESULT = 0,         /**< ASR result event for partial result */
 100         MA_ASR_RESULT_EVENT_FINAL_RESULT,                       /**< ASR result event for final result */
 101         MA_ASR_RESULT_EVENT_ERROR                                       /**< ASR result event for error */
 102 } ma_asr_result_event_e;
 103
 104 /**
 105  * @brief Enumerations for recognition result events.
 106  * @since_tizen 5.5
 107  */
 108 typedef enum {
 109         MA_RECOGNITION_RESULT_EVENT_SUCCESS = 0,                /**< Recognition succeeded */
 110         MA_RECOGNITION_RESULT_EVENT_EMPTY_TEXT,                 /**< No text result recognized */
 111         MA_RECOGNITION_RESULT_EVENT_ERROR,                              /**< Unknown error occurred */
 112         MA_RECOGNITION_RESULT_EVENT_FALSE_TRIGGER               /**< Turned out to be a false trigger */
 113 } ma_recognition_result_event_e;
 114
 115 /**
 116  * @brief Enumerations for speech data types.
 117  * @since_tizen 5.5
 118  */
 119 typedef enum {
 120         MA_AUDIO_STREAMING_DATA_TYPE_CURRENT_UTTERANCE = 0,             /**< Current utterance */
 121         MA_AUDIO_STREAMING_DATA_TYPE_PREVIOUS_UTTERANCE,                        /**< Previous utterance */
 122         MA_AUDIO_STREAMING_DATA_TYPE_FOLLOW_UP_SPEECH                           /**< Follow-up speech */
 123 } ma_audio_streaming_data_type_e;
 124
 125 /**
 126  * @brief Enumerations for individual assistant's voice feedback state.
 127  * @since_tizen 5.5
 128  */
 129 typedef enum {
 130         MA_VOICE_FEEDBACK_STATE_NONE = 0,       /**< No voice feedback being provided */
 131         MA_VOICE_FEEDBACK_STATE_STARTED,        /**< Voice feedback being provided */
 132 } ma_voice_feedback_state_e;
 133
 134 /**
 135  * @brief Enumerations for multi-assistant active state.
 136  * @since_tizen 5.5
 137  */
 138 typedef enum {
 139         MA_ACTIVE_STATE_INACTIVE = 0,   /**< 'Inactive' state */
 140         MA_ACTIVE_STATE_ACTIVE, /**< 'Active' state */
 141         MA_ACTIVE_STATE_PREPROCESSING,  /**< 'Preprocessing' state */
 142 } ma_active_state_e;
 143
 144 /**
 145  * @brief Enumerations for allowing preprocessing by other voice assistants.
 146  * @since_tizen 5.5
 147  */
 148 typedef enum {
 149         MA_PREPROCESSING_ALLOW_NONE = 0,        /**< No preprocessing allowed */
 150         MA_PREPROCESSING_ALLOW_UTTERANCE,       /**< Preprocessing allowed for utterance audio only */
 151         MA_PREPROCESSING_ALLOW_FOLLOW_UP,       /**< Preprocessing allowed for follow-up audio only */
 152         MA_PREPROCESSING_ALLOW_ALL,                     /**< Preprocessing allowed for all audio */
 153 } ma_preprocessing_allow_mode_e;
 154
 155 /**
 156  * @brief Enumerations for section information of audio streaming data.
 157  * @since_tizen 5.5
 158  */
 159 typedef enum {
 160         MA_AUDIO_STREAMING_DATA_SECTION_UTTERANCE = 0,  /**< Utterance section started */
 161         MA_AUDIO_STREAMING_DATA_SECTION_WAKE_WORD,              /**< Wake word section started */
 162 } ma_audio_streaming_data_section_e;
 163
 164 /**
 165  * @brief Enumerations for multi-assistant service state.
 166  * @since_tizen 6.0
 167  */
 168 typedef enum {
 169         MA_SERVICE_STATE_INACTIVE = 0,                  /**< 'Inactive' state */
 170         MA_SERVICE_STATE_LISTENING = 1,                 /**< 'Listening' state */
 171         MA_SERVICE_STATE_UTTERANCE = 2,                 /**< 'Utterance' state */
 172         MA_SERVICE_STATE_PROCESSING = 3,                /**< 'Processing' state */
 173         MA_SERVICE_STATE_VOICE_FEEDBACK = 4,    /**< 'VoiceFeedback' state */
 174 } ma_service_state_e;
 175
 176 /**
 177  * @brief Enumerations for voice key status change.
 178  * @details When the voice key is pressed, the "pressed" state is reported.
 179  *          If the voice key gets released within the timeout value for tap events,
 180  *          the voice key status value will be reported as "released after tap".
 181  *          Otherwise, "released after push" will be reported.
 182  * @since_tizen 6.0
 183   */
 184 typedef enum {
 185         MA_VOICE_KEY_STATUS_PRESSED = 0,                                /**< 'Pressed' state */
 186         MA_VOICE_KEY_STATUS_RELEASED_AFTER_PUSH = 1,    /**< 'Released' state after push */
 187         MA_VOICE_KEY_STATUS_RELEASED_AFTER_TAP = 2,             /**< 'Released' state after tap*/
 188 } ma_voice_key_status_e;
 189
 190 /**
 191  * @brief Called when the client state is changed.
 192  * @since_tizen 5.0
 193  *
 194  * @param[in] previous The previous state
 195  * @param[in] current The current state
 196  * @param[in] user_data The user data passed from the callback registration function
 197  */
 198 typedef void (*ma_state_changed_cb)(ma_state_e previous, ma_state_e current, void* user_data);
 199
 200 /**
 201  * @brief Called when the error is occurred.
 202  * @details The following error codes can be received: \n
 203  *          #MA_ERROR_NONE:                         Success \n
 204  *          #MA_ERROR_OUT_OF_MEMORY:                Out of Memory \n
 205  *          #MA_ERROR_IO_ERROR:                     I/O error \n
 206  *          #MA_ERROR_INVALID_PARAMETER:            Invalid parameter \n
 207  *          #MA_ERROR_TIMED_OUT:                    No answer from service \n
 208  *          #MA_ERROR_RECORDER_BUSY:                Busy recorder \n
 209  *          #MA_ERROR_PERMISSION_DENIED:            Permission denied \n
 210  *          #MA_ERROR_NOT_SUPPORTED:                Multi-assistant NOT supported \n
 211  *          #MA_ERROR_INVALID_STATE:                Invalid state \n
 212  *          #MA_ERROR_INVALID_LANGUAGE:             Invalid language \n
 213  *          #MA_ERROR_ENGINE_NOT_FOUND:             No available engine \n
 214  *          #MA_ERROR_OPERATION_FAILED:             Operation failed \n
 215  *          #MA_ERROR_SERVICE_RESET:                Service daemon reset \n
 216  *          #MA_ERROR_NOT_SUPPORTED_FEATURE:        Not supported feature of current engine \n
 217  * @since_tizen 5.0
 218  *
 219  * @param[in] reason The error reason
 220  * @param[in] user_data The user data passed from the callback registration function
 221  */
 222 typedef void (*ma_error_cb)(ma_error_e reason, void* user_data);
 223
 224 /**
 225  * @brief Called when the default language is changed.
 226  * @since_tizen 5.0
 227  * @remarks The @a previous can be used only in the callback. To use outside, make a copy.
 228  *          The @a current can be used only in the callback. To use outside, make a copy.
 229  *
 230  * @param[in] previous The previous language
 231  * @param[in] current The current language
 232  * @param[in] user_data The user data passed from the callback registration function
 233  *
 234  * @see ma_set_language_changed_cb()
 235  * @see ma_unset_language_changed_cb()
 236  */
 237 typedef void (*ma_language_changed_cb)(const char* previous, const char* current, void* user_data);
 238
 239 /**
 240  * @brief Called when the multi-assistant service sends audio streaming.
 241  * @since_tizen 5.0
 242  * @remarks The @a buffer should not be released and can be used only in the callback. To use outside, make a copy.
 243  *
 244  * @param[in] event The audio streaming event
 245  * @param[in] buffer The audio streaming data
 246  * @param[in] len The length of the audio streaming data
 247  * @param[in] user_data The user data passed from the callback registration function
 248  *
 249  * @see ma_set_audio_streaming_cb()
 250  * @see ma_unset_audio_streaming_cb()
 251  */
 252 typedef void (*ma_audio_streaming_cb)(ma_audio_streaming_event_e event, char* buffer, int len, void* user_data);
 253
 254 /**
 255  * @brief Called when the active state is changed.
 256  * @since_tizen 5.5
 257  *
 258  * @param[in] previous The previous active state
 259  * @param[in] current The current active state
 260  * @param[in] user_data The user data passed from the callback registration function
 261  */
 262 typedef void (*ma_active_state_changed_cb)(ma_active_state_e previous, ma_active_state_e current, void* user_data);
 263
 264 /**
 265  * @brief Called when a wakeup engine specific command is retrieved.
 266  * @since_tizen 5.5
 267  * @remarks The @a command should not be released and can be used only in the callback. To use outside, make a copy.
 268  *
 269  * @param[in] command The wakeup engine specific command
 270  * @param[in] user_data The user data passed from the callback registration function
 271  */
 272 typedef void (*ma_wakeup_engine_command_cb)(const char *command, void* user_data);
 273
 274 /**
 275  * @brief A handle to get assistant information.
 276  * @since_tizen 5.5
 277  */
 278
 279 typedef void *ma_assistant_info_h;
 280
 281 /**
 282  * @brief Called whenever to get the assistant information of each installed assistant.
 283  * @since_tizen 5.5
 284  *
 285  * @remarks The @a handle should not be released.
 286  * @remarks The @a handle is managed by the platform and will be released when application exits.
 287  * @param[in] handle The handle of the assistant
 288  * @param[in] user_data The user data passed from the callback registration function
 289  */
 290 typedef int (*ma_assistant_info_list_cb)(ma_assistant_info_h handle, void* user_data);
 291
 292 /**
 293  * @brief Called when the preprocessing information is changed.
 294  * @since_tizen 5.5
 295  *
 296  * @remarks The @a app_id should not be released and can be used only in the callback. To use outside, make a copy.
 297  * @remarks If the @a app_id is NULL, it means there is no preprocessing voice assistant available.
 298  * @param[in] app_id The application id of current preprocessing voice assistant
 299  * @param[in] user_data The user data passed from the callback registration function
 300  */
 301 typedef void (*ma_preprocessing_information_changed_cb)(const char* app_id, void* user_data);
 302
 303 /**
 304  * @brief Called when the section of audio streaming data is changed.
 305  * @since_tizen 5.5
 306  *
 307  * @param[in] section The current section information of audio streaming data
 308  * @param[in] user_data The user data passed from the callback registration function
 309  */
 310 typedef void (*ma_audio_streaming_data_section_changed_cb)(ma_audio_streaming_data_section_e section, void* user_data);
 311
 312 /**
 313  * @brief Called when the service state is changed.
 314  * @since_tizen 6.0
 315  *
 316  * @param[in] previous The previous service state
 317  * @param[in] current The new service state
 318  * @param[in] user_data The user data passed from the callback registration function
 319  */
 320 typedef void (*ma_service_state_changed_cb)(ma_service_state_e previous, ma_service_state_e current, void* user_data);
 321
 322 /**
 323  * @brief Called when the multi-assistant service sends voice key status change event.
 324  * @since_tizen 6.0
 325  *
 326  * @param[in] status The change of voice key status
 327  * @param[in] user_data The user data passed from the callback registration function
 328  *
 329  * @see ma_set_voice_key_status_changed_cb()
 330  * @see ma_unset_voice_key_status_changed_cb()
 331  */
 332 typedef void (*ma_voice_key_status_changed_cb)(ma_voice_key_status_e status, void* user_data);
 333
 334 #ifdef __cplusplus
 335 }
 336 #endif
 337
 338 /**
 339  * @}
 340  */
 341
 342 #endif /* __TIZEN_UIFW_MULTI_ASSISTANT_COMMON_H__ */
 343