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  * @param[in] vc_command The command handle
  92  * @param[in] user_data The user data passed from the foreach function
  93  * @return @c true to continue with the next iteration of the loop,
  94  *         @c false to break out of the loop
  95  * @pre vc_cmd_list_foreach_commands() will invoke this callback.
  96  * @see vc_cmd_list_foreach_commands()
  97  */
  98 typedef bool (*vc_cmd_list_cb)(vc_cmd_h vc_command, void* user_data);
  99
 100
 101 /**
 102  * @brief Creates a handle for command list.
 103  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 104  * @remarks If the function succeeds, @a The list handle must be released with vc_cmd_list_destroy().
 105  * @param[out] vc_cmd_list The command list handle
 106  * @return @c 0 on success,
 107  *         otherwise a negative error value
 108  * @retval #VC_ERROR_NONE Successful
 109  * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 110  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 111  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 112  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 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_INVALID_PARAMETER Invalid parameter
 128  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 129  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 130  * @see vc_cmd_list_create()
 131  */
 132 int vc_cmd_list_destroy(vc_cmd_list_h vc_cmd_list, bool free_command);
 133
 134
 135 /**
 136  * @brief Gets command count of list.
 137  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 138  * @param[in] vc_cmd_list The command list handle
 139  * @param[out] count The count
 140  * @return @c 0 on success,
 141  *         otherwise a negative error value
 142  * @retval #VC_ERROR_NONE Successful
 143  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 144  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 145  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 146  */
 147 int vc_cmd_list_get_count(vc_cmd_list_h vc_cmd_list, int* count);
 148
 149
 150 /**
 151  * @brief Adds command to command list.
 152  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 153  * @param[in] vc_cmd_list The command list handle
 154  * @param[in] vc_command The command handle
 155  * @return @c 0 on success,
 156  *         otherwise a negative error value
 157  * @retval #VC_ERROR_NONE Successful
 158  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 159  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 160  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 161  * @see vc_cmd_list_remove()
 162  */
 163 int vc_cmd_list_add(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
 164
 165
 166 /**
 167  * @brief Removes command from command list.
 168  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 169  * @param[in] vc_cmd_list The command list handle
 170  * @param[in] vc_command The command handle
 171  * @return @c 0 on success,
 172  *         otherwise a negative error value
 173  * @retval #VC_ERROR_NONE Successful
 174  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 175  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 176  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 177  * @see vc_cmd_list_add()
 178  */
 179 int vc_cmd_list_remove(vc_cmd_list_h vc_cmd_list, vc_cmd_h vc_command);
 180
 181
 182 /**
 183  * @brief Retrieves all commands of command list using callback function.
 184  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 185  * @param[in] vc_cmd_list The command list handle
 186  * @param[in] callback Callback function to invoke
 187  * @param[in] user_data The user data to be passed to the callback function
 188  * @return @c 0 on success,
 189  *         otherwise a negative error value
 190  * @retval #VC_ERROR_NONE Successful
 191  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 192  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 193  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 194  * @post This function invokes vc_cmd_list_cb() repeatedly for getting commands.
 195  * @see vc_cmd_list_cb()
 196  */
 197 int vc_cmd_list_foreach_commands(vc_cmd_list_h vc_cmd_list, vc_cmd_list_cb callback, void* user_data);
 198
 199
 200 /**
 201  * @brief Moves index to first command.
 202  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 203  * @param[in] vc_cmd_list The command list handle
 204  * @return @c 0 on success,
 205  *         otherwise a negative error value
 206  * @retval #VC_ERROR_NONE Successful
 207  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 208  * @retval #VC_ERROR_EMPTY List empty
 209  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 210  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 211  * @see vc_cmd_list_last()
 212  */
 213 int vc_cmd_list_first(vc_cmd_list_h vc_cmd_list);
 214
 215
 216 /**
 217  * @brief Moves index to last command.
 218  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 219  * @param[in] vc_cmd_list The command list handle
 220  * @return @c 0 on success,
 221  *         otherwise a negative error value
 222  * @retval #VC_ERROR_NONE Successful
 223  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 224  * @retval #VC_ERROR_EMPTY List empty
 225  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 226  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 227  * @see vc_cmd_list_first()
 228  */
 229 int vc_cmd_list_last(vc_cmd_list_h vc_cmd_list);
 230
 231
 232 /**
 233  * @brief Moves index to next command.
 234  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 235  * @param[in] vc_cmd_list The command list handle
 236  * @return @c 0 on success,
 237  *         otherwise a negative error value
 238  * @retval #VC_ERROR_NONE Successful
 239  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 240  * @retval #VC_ERROR_EMPTY List empty
 241  * @retval #VC_ERROR_ITERATION_END List reached end
 242  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 243  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 244  * @see vc_cmd_list_prev()
 245  */
 246 int vc_cmd_list_next(vc_cmd_list_h vc_cmd_list);
 247
 248
 249 /**
 250  * @brief Moves index to previous command.
 251  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 252  * @param[in] vc_cmd_list The command list handle
 253  * @return @c 0 on success,
 254  *         otherwise a negative error value
 255  * @retval #VC_ERROR_NONE Successful
 256  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 257  * @retval #VC_ERROR_EMPTY List empty
 258  * @retval #VC_ERROR_ITERATION_END List reached end
 259  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 260  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 261  * @see vc_cmd_list_next()
 262  */
 263 int vc_cmd_list_prev(vc_cmd_list_h vc_cmd_list);
 264
 265
 266 /**
 267  * @brief Get current command from command list by index.
 268  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 269  * @param[in] vc_cmd_list The command list handle
 270  * @param[out] vc_command The command handle
 271  * @return @c 0 on success,
 272  *         otherwise a negative error value
 273  * @retval #VC_ERROR_NONE Successful
 274  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 275  * @retval #VC_ERROR_EMPTY List empty
 276  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 277  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 278  * @see vc_cmd_list_first()
 279  * @see vc_cmd_list_last()
 280  * @see vc_cmd_list_prev()
 281  * @see vc_cmd_list_next()
 282  */
 283 int vc_cmd_list_get_current(vc_cmd_list_h vc_cmd_list, vc_cmd_h* vc_command);
 284
 285
 286 /**
 287  * @brief Creates a handle for command.
 288  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 289  * @remarks If the function succeeds, @a The command handle must be released
 290  *          with vc_cmd_destroy() or vc_cmd_list_destroy().
 291  *          You should set command and type if command is valid.
 292  *          The command format is set to #VC_COMMAND_FORMAT_FIXED by default and can be changed with vc_cmd_set_format().
 293  * @param[out] vc_command The command handle
 294  * @return @c 0 on success,
 295  *         otherwise a negative error value
 296  * @retval #VC_ERROR_NONE Successful
 297  * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 298  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 299  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 300  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 301  * @see vc_cmd_destroy()
 302  */
 303 int vc_cmd_create(vc_cmd_h* vc_command);
 304
 305
 306 /**
 307  * @brief Destroys the handle.
 308  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 309  * @param[in] vc_command The command handle
 310  * @return @c 0 on success,
 311  *         otherwise a negative error value
 312  * @retval #VC_ERROR_NONE Successful
 313  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 314  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 315  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 316  * @see vc_cmd_create()
 317  */
 318 int vc_cmd_destroy(vc_cmd_h vc_command);
 319
 320
 321 /**
 322  * @brief Sets command or action.
 323  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 324  * @param[in] vc_command The command handle
 325  * @param[in] command The command or action text
 326  * @return @c 0 on success,
 327  *         otherwise a negative error value
 328  * @retval #VC_ERROR_NONE Successful
 329  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 330  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 331  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 332  * @see vc_cmd_get_command()
 333  */
 334 int vc_cmd_set_command(vc_cmd_h vc_command, const char* command);
 335
 336
 337 /**
 338  * @brief Gets command.
 339  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 340  * @remark If the function succeeds, @a command must be released with free() by you if they are not NULL.
 341  * @param[in] vc_command The command handle
 342  * @param[out] command The command text
 343  * @return @c 0 on success,
 344  *         otherwise a negative error value
 345  * @retval #VC_ERROR_NONE Successful
 346  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 347  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 348  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 349  * @see vc_cmd_set_command()
 350  */
 351 int vc_cmd_get_command(vc_cmd_h vc_command, char** command);
 352
 353
 354 /**
 355  * @brief Gets the unfixed command.
 356  * @since_tizen 3.0
 357  * @remark If the function succeeds, the @a command must be released with free() if it is not NULL.
 358  *         If the command of the given @a vc_command is NULL (@a vc_command is NOT NULL), @a command will be also NULL.
 359  *         This function should be used for commands which have non-fixed format.
 360  * @param[in] vc_command The command handle
 361  * @param[out] command The unfixed command text
 362  * @return @c 0 on success,
 363  *         otherwise a negative error value
 364  * @retval #VC_ERROR_NONE Successful
 365  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 366  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 367  * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
 368  */
 369 int vc_cmd_get_unfixed_command(vc_cmd_h vc_command, char** command);
 370
 371
 372 /**
 373  * @brief Sets command type.
 374  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 375  * @remark If you do not set the command type, the default value is @c -1.
 376  *         You should set type if command is valid
 377  * @param[in] vc_command The command handle
 378  * @param[in] 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_INVALID_PARAMETER Invalid parameter
 383  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 384  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 385  * @see vc_cmd_get_type()
 386  */
 387 int vc_cmd_set_type(vc_cmd_h vc_command, int type);
 388
 389
 390 /**
 391  * @brief Gets command type.
 392  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 393  * @param[in] vc_command The command handle
 394  * @param[out] type The command type
 395  * @return @c 0 on success,
 396  *         otherwise a negative error value
 397  * @retval #VC_ERROR_NONE Successful
 398  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 399  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 400  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 401  * @see vc_cmd_set_type()
 402  */
 403 int vc_cmd_get_type(vc_cmd_h vc_command, int* type);
 404
 405
 406 /**
 407  * @brief Sets the command format.
 408  * @since_tizen 3.0
 409  * @remark The default format is #VC_COMMAND_FORMAT_FIXED.
 410  * @param[in] vc_command The command handle
 411  * @param[in] format The command format
 412  * @return @c 0 on success,
 413  *         otherwise a negative error value
 414  * @retval #VC_ERROR_NONE Successful
 415  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 416  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 417  * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
 418  * @see vc_cmd_get_format()
 419  */
 420 int vc_cmd_set_format(vc_cmd_h vc_command, int format);
 421
 422
 423 /**
 424  * @brief Gets the command format.
 425  * @since_tizen 3.0
 426  * @remark The default format is #VC_COMMAND_FORMAT_FIXED.
 427  * @param[in] vc_command The command handle
 428  * @param[out] format The command format
 429  * @return @c 0 on success,
 430  *         otherwise a negative error value
 431  * @retval #VC_ERROR_NONE Successful
 432  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 433  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 434  * @retval #VC_ERROR_NOT_SUPPORTED Not supported feature
 435  * @see vc_cmd_set_format()
 436  */
 437 int vc_cmd_get_format(vc_cmd_h vc_command, int* format);
 438
 439
 440 #ifdef __cplusplus
 441 }
 442 #endif
 443
 444
 445 /**
 446  * @}@}
 447  */
 448
 449
 450 #endif /* __VOICE_CONTROL_COMMAND_H__ */