include/voice_control_command.h

   1 /**
   2  * Copyright (c) 2011-2016 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 __VOICE_CONTROL_COMMAND_H__
  19 #define __VOICE_CONTROL_COMMAND_H__
  20
  21
  22 #include <tizen.h>
  23
  24
  25 /**
  26  * @defgroup CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE Voice control command
  27  * @ingroup CAPI_UIX_VOICE_CONTROL_MODULE
  28  * @brief The @ref CAPI_UIX_VOICE_CONTROL_COMMAND_MODULE API provides functions for creating/destroying command list and add/remove/retrieve commands of list.
  29  * @{
  30  */
  31
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #endif
  37
  38
  39 /**
  40  * @brief Definition for fixed command format.
  41  * @since_tizen 3.0
  42  */
  43 #define VC_COMMAND_FORMAT_FIXED 0
  44
  45
  46 /**
  47  * @brief Definition for fixed and variable fixed command format.
  48  * @since_tizen 3.0
  49  */
  50 #define VC_COMMAND_FORMAT_FIXED_AND_VFIXED      1
  51
  52
  53 /**
  54  * @brief Definition for variable fixed and fixed command format.
  55  * @since_tizen 3.0
  56  */
  57 #define VC_COMMAND_FORMAT_VFIXED_AND_FIXED      2
  58
  59
  60 /**
  61  * @brief Definition for fixed and non-fixed command format.
  62  * @since_tizen 3.0
  63  */
  64 #define VC_COMMAND_FORMAT_FIXED_AND_NONFIXED    3
  65
  66
  67 /**
  68  * @brief Definition for non-fixed and fixed command format.
  69  * @since_tizen 3.0
  70  */
  71 #define VC_COMMAND_FORMAT_NONFIXED_AND_FIXED    4
  72
  73
  74 /**
  75  * @brief The voice command handle.
  76  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  77  */
  78 typedef struct vc_cmd_s* vc_cmd_h;
  79
  80
  81 /**
  82  * @brief The voice command list handle.
  83  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  84  */
  85 typedef struct vc_cmd_list_s* vc_cmd_list_h;
  86
  87
  88 /**
  89  * @brief Called to retrieve The commands in list.
  90  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  91  * @remarks @a vc_command should not be released. It is managed by the framework and will be released when invoking this callback is finished.
  92  * @param[in] vc_command The command handle
  93  * @param[in] user_data The user data passed from the foreach function
  94  * @return @c true to continue with the next iteration of the loop,
  95  *         @c false to break out of the loop
  96  * @pre vc_cmd_list_foreach_commands() will invoke this callback.
  97  * @see vc_cmd_list_foreach_commands()
  98  */
  99 typedef bool (*vc_cmd_list_cb)(vc_cmd_h vc_command, void* user_data);
 100
 101
 102 /**
 103  * @brief Creates a handle for command list.
 104  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 105  * @remarks If the function succeeds, @a vc_cmd_list must be released with vc_cmd_list_destroy().
 106  * @param[out] vc_cmd_list The command list handle
 107  * @return @c 0 on success,
 108  *         otherwise a negative error value
 109  * @retval #VC_ERROR_NONE Successful
 110  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 111  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 112  * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 113  * @see vc_cmd_list_destroy()
 114  */
 115 int vc_cmd_list_create(vc_cmd_list_h* vc_cmd_list);
 116
 117
 118 /**
 119  * @brief Destroys the handle for command list.
 120  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 121  * @param[in] vc_cmd_list The command list handle
 122  * @param[in] free_command The command free option @c true = release each commands in list,
 123  *                                                 @c false = remove command from list
 124  * @return @c 0 on success,
 125  *         otherwise a negative error value
 126  * @retval #VC_ERROR_NONE Successful
 127  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 128  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 129  * @see vc_cmd_list_create()
 130  */
 131 int vc_cmd_list_destroy(vc_cmd_list_h vc_cmd_list, bool free_command);
 132
 133
 134 /**
 135  * @brief Gets command count of list.
 136  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 137  * @param[in] vc_cmd_list The command list handle
 138  * @param[out] count The count
 139  * @return @c 0 on success,
 140  *         otherwise a negative error value
 141  * @retval #VC_ERROR_NONE Successful
 142  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 143  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 144  */
 145 int vc_cmd_list_get_count(vc_cmd_list_h vc_cmd_list, int* count);
 146
 147
 148 /**
 149  * @brief Adds command to command list.
 150  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 151  * @param[in] vc_cmd_list The command list handle
 152  * @param[in] vc_command The command handle
 153  * @return @c 0 on success,
 154  *         otherwise a negative error value
 155  * @retval #VC_ERROR_NONE Successful
 156  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 157  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 158  * @see vc_cmd_list_remove()
 159  */
 160 int vc_cmd_list_add(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
 161
 162
 163 /**
 164  * @brief Removes command from command list.
 165  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 166  * @param[in] vc_cmd_list The command list handle
 167  * @param[in] vc_command The command handle
 168  * @return @c 0 on success,
 169  *         otherwise a negative error value
 170  * @retval #VC_ERROR_NONE Successful
 171  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 172  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 173  * @see vc_cmd_list_add()
 174  */
 175 int vc_cmd_list_remove(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
 176
 177
 178 /**
 179  * @brief Retrieves all commands of command list using callback function.
 180  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 181  * @param[in] vc_cmd_list The command list handle
 182  * @param[in] callback Callback function to invoke
 183  * @param[in] user_data The user data to be passed to the callback function
 184  * @return @c 0 on success,
 185  *         otherwise a negative error value
 186  * @retval #VC_ERROR_NONE Successful
 187  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 188  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 189  * @post This function invokes vc_cmd_list_cb() repeatedly for getting commands.
 190  * @see vc_cmd_list_cb()
 191  */
 192 int vc_cmd_list_foreach_commands(vc_cmd_list_h vc_cmd_list, vc_cmd_list_cb callback, void* user_data);
 193
 194
 195 /**
 196  * @brief Moves index to first command.
 197  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 198  * @param[in] vc_cmd_list The command list handle
 199  * @return @c 0 on success,
 200  *         otherwise a negative error value
 201  * @retval #VC_ERROR_NONE Successful
 202  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 203  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 204  * @retval #VC_ERROR_EMPTY List empty
 205  * @see vc_cmd_list_last()
 206  */
 207 int vc_cmd_list_first(vc_cmd_list_h vc_cmd_list);
 208
 209
 210 /**
 211  * @brief Moves index to last command.
 212  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 213  * @param[in] vc_cmd_list The command list handle
 214  * @return @c 0 on success,
 215  *         otherwise a negative error value
 216  * @retval #VC_ERROR_NONE Successful
 217  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 218  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 219  * @retval #VC_ERROR_EMPTY List empty
 220  * @see vc_cmd_list_first()
 221  */
 222 int vc_cmd_list_last(vc_cmd_list_h vc_cmd_list);
 223
 224
 225 /**
 226  * @brief Moves index to next command.
 227  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 228  * @param[in] vc_cmd_list The command list handle
 229  * @return @c 0 on success,
 230  *         otherwise a negative error value
 231  * @retval #VC_ERROR_NONE Successful
 232  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 233  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 234  * @retval #VC_ERROR_EMPTY List empty
 235  * @retval #VC_ERROR_ITERATION_END List reached end
 236  * @see vc_cmd_list_prev()
 237  */
 238 int vc_cmd_list_next(vc_cmd_list_h vc_cmd_list);
 239
 240
 241 /**
 242  * @brief Moves index to previous command.
 243  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 244  * @param[in] vc_cmd_list The command list handle
 245  * @return @c 0 on success,
 246  *         otherwise a negative error value
 247  * @retval #VC_ERROR_NONE Successful
 248  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 249  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 250  * @retval #VC_ERROR_EMPTY List empty
 251  * @retval #VC_ERROR_ITERATION_END List reached end
 252  * @see vc_cmd_list_next()
 253  */
 254 int vc_cmd_list_prev(vc_cmd_list_h vc_cmd_list);
 255
 256
 257 /**
 258  * @brief Gets current command from command list by index.
 259  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 260  * @remarks @a vc_command should be released after removing it from @a vc_cmd_list with vc_cmd_list_remove().
 261  * @param[in] vc_cmd_list The command list handle
 262  * @param[out] vc_command The command handle
 263  * @return @c 0 on success,
 264  *         otherwise a negative error value
 265  * @retval #VC_ERROR_NONE Successful
 266  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 267  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 268  * @retval #VC_ERROR_EMPTY List empty
 269  * @see vc_cmd_list_first()
 270  * @see vc_cmd_list_last()
 271  * @see vc_cmd_list_prev()
 272  * @see vc_cmd_list_next()
 273  */
 274 int vc_cmd_list_get_current(vc_cmd_list_h vc_cmd_list, vc_cmd_h* vc_command);
 275
 276
 277 /**
 278  * @brief Creates a handle for command.
 279  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 280  * @remarks If the function succeeds, @a vc_command must be released with vc_cmd_destroy() or vc_cmd_list_destroy().
 281  *          You should set command and type if command is valid.
 282  *          The command format is set to #VC_COMMAND_FORMAT_FIXED by default and can be changed with vc_cmd_set_format().
 283  * @param[out] vc_command The command handle
 284  * @return @c 0 on success,
 285  *         otherwise a negative error value
 286  * @retval #VC_ERROR_NONE Successful
 287  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 288  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 289  * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 290  * @see vc_cmd_destroy()
 291  */
 292 int vc_cmd_create(vc_cmd_h* vc_command);
 293
 294
 295 /**
 296  * @brief Destroys the handle.
 297  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 298  * @param[in] vc_command The command handle
 299  * @return @c 0 on success,
 300  *         otherwise a negative error value
 301  * @retval #VC_ERROR_NONE Successful
 302  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 303  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 304  * @see vc_cmd_create()
 305  */
 306 int vc_cmd_destroy(vc_cmd_h vc_command);
 307
 308
 309 /**
 310  * @brief Sets command or action.
 311  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 312  * @param[in] vc_command The command handle
 313  * @param[in] command The command or action text
 314  * @return @c 0 on success,
 315  *         otherwise a negative error value
 316  * @retval #VC_ERROR_NONE Successful
 317  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 318  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 319  * @see vc_cmd_get_command()
 320  */
 321 int vc_cmd_set_command(vc_cmd_h vc_command, const char* command);
 322
 323
 324 /**
 325  * @brief Gets command.
 326  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 327  * @remarks If the function succeeds, @a command must be released with free() by you if they are not NULL.
 328  * @param[in] vc_command The command handle
 329  * @param[out] command The command text
 330  * @return @c 0 on success,
 331  *         otherwise a negative error value
 332  * @retval #VC_ERROR_NONE Successful
 333  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 334  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 335  * @see vc_cmd_set_command()
 336  */
 337 int vc_cmd_get_command(vc_cmd_h vc_command, char** command);
 338
 339
 340 /**
 341  * @brief Gets the unfixed command.
 342  * @since_tizen 3.0
 343  * @remarks If the function succeeds, the @a command must be released with free() if it is not NULL.
 344  *         If the command of the given @a vc_command is NULL (@a vc_command is NOT NULL), @a command will be also NULL.
 345  *         This function should be used for commands which have non-fixed format.
 346  * @param[in] vc_command The command handle
 347  * @param[out] command The unfixed command text
 348  * @return @c 0 on success,
 349  *         otherwise a negative error value
 350  * @retval #VC_ERROR_NONE Successful
 351  * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
 352  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 353  */
 354 int vc_cmd_get_unfixed_command(vc_cmd_h vc_command, char** command);
 355
 356
 357 /**
 358  * @brief Sets command type.
 359  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 360  * @remarks If you do not set the command type, the default value is @c -1.
 361  *         You should set type if command is valid
 362  * @param[in] vc_command The command handle
 363  * @param[in] type The command type
 364  * @return @c 0 on success,
 365  *         otherwise a negative error value
 366  * @retval #VC_ERROR_NONE Successful
 367  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 368  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 369  * @see vc_cmd_get_type()
 370  */
 371 int vc_cmd_set_type(vc_cmd_h vc_command, int type);
 372
 373
 374 /**
 375  * @brief Gets command type.
 376  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 377  * @param[in] vc_command The command handle
 378  * @param[out] type The command type
 379  * @return @c 0 on success,
 380  *         otherwise a negative error value
 381  * @retval #VC_ERROR_NONE Successful
 382  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 383  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 384  * @see vc_cmd_set_type()
 385  */
 386 int vc_cmd_get_type(vc_cmd_h vc_command, int* type);
 387
 388
 389 /**
 390  * @brief Sets the command format.
 391  * @since_tizen 3.0
 392  * @remarks The default format is #VC_COMMAND_FORMAT_FIXED.
 393  * @param[in] vc_command The command handle
 394  * @param[in] format The command format
 395  * @return @c 0 on success,
 396  *         otherwise a negative error value
 397  * @retval #VC_ERROR_NONE Successful
 398  * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
 399  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 400  * @see vc_cmd_get_format()
 401  */
 402 int vc_cmd_set_format(vc_cmd_h vc_command, int format);
 403
 404
 405 /**
 406  * @brief Gets the command format.
 407  * @since_tizen 3.0
 408  * @remarks The default format is #VC_COMMAND_FORMAT_FIXED.
 409  * @param[in] vc_command The command handle
 410  * @param[out] format The command format
 411  * @return @c 0 on success,
 412  *         otherwise a negative error value
 413  * @retval #VC_ERROR_NONE Successful
 414  * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
 415  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 416  * @see vc_cmd_set_format()
 417  */
 418 int vc_cmd_get_format(vc_cmd_h vc_command, int* format);
 419
 420
 421 #ifdef __cplusplus
 422 }
 423 #endif
 424
 425
 426 /**
 427  * @}
 428  */
 429
 430
 431 #endif /* __VOICE_CONTROL_COMMAND_H__ */