include/sticker_provider.h

   1 /*
   2  * Copyright (c) 2018 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 #ifndef __TIZEN_UIX_STICKER_PROVIDER_H__
  18 #define __TIZEN_UIX_STICKER_PROVIDER_H__
  19
  20 #include <sticker_error.h>
  21 #include <sticker_data.h>
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * @file sticker_provider.h
  29  * @brief This file contains sticker provider's APIs.
  30  */
  31
  32 /**
  33  * @addtogroup CAPI_UIX_STICKER_PROVIDER_MODULE
  34  * @{
  35  */
  36
  37 /**
  38  * @brief The sticker provider handle.
  39  * @since_tizen 5.5
  40  */
  41 typedef struct sticker_provider_s *sticker_provider_h;
  42
  43 /**
  44  * @brief Called to retrieve all sticker data in the sticker database.
  45  * @details The sticker_provider_data_foreach_all() must be called to invoke this callback function, synchronously.
  46  * @since_tizen 5.5
  47  * @remarks @a data_handle should not be freed and can be used only in the callback.
  48  *          If you want to use it outside of the callback, you need to use a clone which can be obtained sticker_data_clone().
  49  * @param[in] data_handle The sticker data handle
  50  * @param[in] user_data The user data passed from the foreach function
  51  * @pre sticker_provider_data_foreach_all() will invoke this callback.
  52  * @see sticker_provider_data_foreach_all()
  53  */
  54 typedef void (*sticker_provider_data_foreach_cb)(sticker_data_h data_handle, void *user_data);
  55
  56 /**
  57  * @brief Called when inserting sticker data is finished.
  58  * @details The following error codes can be received: \n
  59  *          #STICKER_ERROR_NONE                 Successful \n
  60  *          #STICKER_ERROR_OPERATION_FAILED     Operation failed \n
  61  * @since_tizen 5.5
  62  * @param[in] error The sticker error code
  63  * @param[in] user_data The user data passed from the foreach function
  64  * @pre sticker_provider_insert_data_by_json_file() will invoke this callback.
  65  * @see sticker_provider_insert_data_by_json_file()
  66  */
  67 typedef void (*sticker_provider_insert_finished_cb)(sticker_error_e error, void *user_data);
  68
  69 /**
  70  * @brief Creates a sticker provider handle.
  71  * @since_tizen 5.5
  72  * @remarks If the function succeeds, @a provider_handle must be released with sticker_provider_destroy().
  73  * @param[out] provider_handle The sticker provider handle
  74  * @return 0 on success, otherwise a negative error value
  75  * @retval #STICKER_ERROR_NONE Successful
  76  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
  77  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
  78  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
  79  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
  80  * @see sticker_provider_destroy()
  81  */
  82 int sticker_provider_create(sticker_provider_h *provider_handle);
  83
  84 /**
  85  * @brief Destroys a sticker provider handle.
  86  * @since_tizen 5.5
  87  * @param[in] provider_handle The sticker provider handle
  88  * @return 0 on success, otherwise a negative error value
  89  * @retval #STICKER_ERROR_NONE Successful
  90  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
  91  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
  92  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
  93  * @see sticker_provider_create()
  94  */
  95 int sticker_provider_destroy(sticker_provider_h provider_handle);
  96
  97 /**
  98  * @brief Inserts a sticker data to the sticker database.
  99  * @since_tizen 5.5
 100  * @remarks All data except thumbnail, description, and display_type must be set in the @a data_handle to insert the sticker data.
 101  *          If the URI type is #STICKER_DATA_URI_LOCAL_PATH, the sticker file is copied to a sticker directory.
 102  *          It is recommended to delete your sticker file after inserting a sticker data.
 103  * @param[in] provider_handle The sticker provider handle
 104  * @param[in] data_handle The sticker data handle to be saved
 105  * @return 0 on success, otherwise a negative error value
 106  * @retval #STICKER_ERROR_NONE Successful
 107  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 108  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 109  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 110  * @retval #STICKER_ERROR_FILE_EXISTS File exists
 111  * @retval #STICKER_ERROR_NO_SUCH_FILE No such file
 112  * @see sticker_provider_update_data()
 113  * @see sticker_provider_delete_data()
 114  */
 115 int sticker_provider_insert_data(sticker_provider_h provider_handle, sticker_data_h data_handle);
 116
 117 /**
 118  * @brief Inserts a sticker data using JSON file.
 119  * @details @a json_path must be a relative path like '/data/message_sticker.json'.
 120  * @since_tizen 5.5
 121  * @remarks All data except thumbnail, description, and display_type must be set in the JSON file to insert the sticker data.
 122  *          @a json_path must have a non-null value and must be an existing file. If not, the error as invalid parameter will be returned.
 123  *          If the URI type is #STICKER_DATA_URI_LOCAL_PATH, the sticker file is copied to a sticker directory.
 124  *          It is recommended to delete your sticker files after inserting a sticker data.
 125  * @param[in] provider_handle The sticker provider handle
 126  * @param[in] json_path The path of JSON file containing sticker information to be saved
 127  * @param[in] callback The callback function to invoke
 128  * @param[in] user_data The user data to be passed to the callback function
 129  * @return 0 on success, otherwise a negative error value
 130  * @retval #STICKER_ERROR_NONE Successful
 131  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 132  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 133  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 134  * @post This function invokes sticker_provider_insert_finished_cb().
 135  * @see sticker_provider_insert_finished_cb()
 136  *
 137  * @code
 138  //JSON file format
 139  {
 140     "sticker":
 141     [
 142         {
 143             "type" : 1,
 144             "uri" : "/res/face/heart_eyes.png",
 145             "keyword" : ["heart eyes", "love", "cute"],
 146             "group" : "face",
 147             "thumbnail" : "/res/face/thumbnail/heart_eyes.png",
 148             "description" : "Smiling face with heart eyes emoji.",
 149             "display_type" : 1
 150         },
 151         {
 152             "type" : 2,
 153             "uri" : "https://samsung.com/example/01/high_five.png",
 154             "keyword" : ["smile", "high five"],
 155             "group" : "face",
 156             "thumbnail" : "",
 157             "description" : "Smiling face with high five emoji.",
 158             "display_type" : null
 159         },
 160             .....
 161         {
 162             .....
 163         }
 164     ]
 165  }
 166  * @endcode
 167  */
 168 int sticker_provider_insert_data_by_json_file(sticker_provider_h provider_handle, const char *json_path, sticker_provider_insert_finished_cb callback, void *user_data);
 169
 170 /**
 171  * @brief Updates a sticker data in the sticker database.
 172  * @since_tizen 5.5
 173  * @param[in] provider_handle The sticker provider handle
 174  * @param[in] data_handle The sticker data handle to be updated
 175  * @return 0 on success, otherwise a negative error value
 176  * @retval #STICKER_ERROR_NONE Successful
 177  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 178  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 179  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 180  * @retval #STICKER_ERROR_FILE_EXISTS File exists
 181  * @retval #STICKER_ERROR_NO_SUCH_FILE No such file
 182  * @see sticker_provider_insert_data()
 183  * @see sticker_provider_delete_data()
 184  */
 185 int sticker_provider_update_data(sticker_provider_h provider_handle, sticker_data_h data_handle);
 186
 187 /**
 188  * @brief Deletes a sticker data in the sticker database.
 189  * @since_tizen 5.5
 190  * @remarks The @a data_handle must be the handle of the sticker stored in the sticker database.
 191  * @param[in] provider_handle The sticker provider handle
 192  * @param[in] data_handle The sticker data handle to be deleted
 193  * @return 0 on success, otherwise a negative error value
 194  * @retval #STICKER_ERROR_NONE Successful
 195  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 196  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 197  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 198  * @see sticker_provider_insert_data()
 199  * @see sticker_provider_update_data()
 200  */
 201 int sticker_provider_delete_data(sticker_provider_h provider_handle, sticker_data_h data_handle);
 202
 203 /**
 204  * @brief Deletes a sticker with the given @a uri from the sticker database.
 205  * @details If the database does not have a sticker that matches the given @a uri, the #STICKER_ERROR_NO_SUCH_FILE error is returned.
 206  * @since_tizen 5.5
 207  * @param[in] provider_handle The sticker provider handle
 208  * @param[in] uri The URI of the sticker data to be deleted
 209  * @return 0 on success, otherwise a negative error value
 210  * @retval #STICKER_ERROR_NONE Successful
 211  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 212  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 213  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 214  * @retval #STICKER_ERROR_NO_SUCH_FILE No such file
 215  * @see sticker_provider_insert_data()
 216  * @see sticker_provider_delete_data()
 217  */
 218 int sticker_provider_delete_data_by_uri(sticker_provider_h provider_handle, const char *uri);
 219
 220 /**
 221  * @brief Gets the count of stickers stored by the provider application.
 222  * @since_tizen 5.5
 223  * @param[in] provider_handle The sticker provider handle
 224  * @param[out] count The number of stickers
 225  * @return 0 on success, otherwise a negative error value
 226  * @retval #STICKER_ERROR_NONE Successful
 227  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 228  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 230  */
 231 int sticker_provider_get_sticker_count(sticker_provider_h provider_handle, int *count);
 232
 233 /**
 234  * @brief Retrieves all sticker data in the sticker database.
 235  * @details If you set the @a offset as @c 10 and @a count as @c 10, then only searched data from @c 10 to @c 19 will be invoked.
 236  * @since_tizen 5.5
 237  * @remarks It is not an error if @a result is smaller than @a count.
 238  * @param[in] provider_handle The sticker provider handle
 239  * @param[in] offset The start position (Starting from zero)
 240  * @param[in] count The number of stickers to be searched with respect to the offset
 241  * @param[out] result The number of stickers retrieved (zero indicates that no data was found)
 242  * @param[in] callback The callback function to invoke
 243  * @param[in] user_data The user data to be passed to the callback function
 244  * @return 0 on success, otherwise a negative error value
 245  * @retval #STICKER_ERROR_NONE Successful
 246  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 247  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter
 248  * @retval #STICKER_ERROR_OUT_OF_MEMORY Out of memory
 249  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 250  * @post This function invokes sticker_provider_data_foreach_cb() repeatedly for getting data.
 251  * @see sticker_provider_data_foreach_cb()
 252  */
 253 int sticker_provider_data_foreach_all(sticker_provider_h provider_handle, int offset, int count, int *result, sticker_provider_data_foreach_cb callback, void *user_data);
 254
 255 /**
 256  * @brief Sets the image of the sticker group.
 257  * @details @a uri must be a relative path like '/res/smile.png' when @a type is #STICKER_DATA_URI_LOCAL_PATH.
 258  * @since_tizen 6.5
 259  * @param[in] provider_handle The sticker provider handle
 260  * @param[in] group The group name for setting group image
 261  * @param[in] type The URI type of the image file
 262  * @param[in] uri The URI of the image file
 263  * @return 0 on success, otherwise a negative error value
 264  * @retval #STICKER_ERROR_NONE Successful
 265  * @retval #STICKER_ERROR_NOT_SUPPORTED Not supported
 266  * @retval #STICKER_ERROR_INVALID_PARAMETER Invalid parameter, e.g. @a group is @c NULL or the group name does not exist in the database
 267  * @retval #STICKER_ERROR_OPERATION_FAILED Operation failed
 268  * @retval #STICKER_ERROR_NO_SUCH_FILE No such file, e.g. @a uri is @c NULL or the specified file does not exist
 269  * @see sticker_provider_insert_data()
 270  */
 271 int sticker_provider_set_group_image(sticker_provider_h provider_handle, const char *group, sticker_data_uri_type_e type, const char *uri);
 272
 273 /**
 274  * @}
 275  */
 276
 277 #ifdef __cplusplus
 278 }
 279 #endif
 280
 281 #endif /* __TIZEN_UIX_STICKER_PROVIDER_H__ */