client/sal_service_adaptor.h

   1 /*
   2  * Service Adaptor
   3  *
   4  * Copyright (c) 2014 - 2015 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20 #ifndef __SERVICE_ADAPTOR_H__
  21 #define __SERVICE_ADAPTOR_H__
  22
  23 #ifndef API
  24 #define API __attribute__ ((visibility("default")))
  25 #endif
  26
  27 #ifdef __cplusplus
  28 extern "C"
  29 {
  30 #endif
  31
  32 #include <glib.h>
  33
  34 /**
  35  * @addtogroup  SERVICE_ADAPTOR_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Type of service in plugin
  41  */
  42 typedef enum _service_plugin_type_e
  43 {
  44         SERVICE_PLUGIN_AUTH     = (0x01 << 0),          /**< Auth service type flag */
  45         SERVICE_PLUGIN_STORAGE  = (0x01 << 1),          /**< Storage service type flag */
  46 } service_plugin_type_e;
  47
  48 /**
  49  * @brief Definition for the service_plugin property: The application id be issued from service provider for 3rd party developer.
  50  * @since_tizen 2.4
  51  * @see service_plugin_add_property()
  52  * @see service_plugin_remove_property()
  53  * @see service_plugin_get_property()
  54  */
  55 #define SERVICE_PLUGIN_PROPERTY_APP_KEY         "http://tizen.org/service-adaptor/plugin/property/app_key"
  56
  57 /**
  58  * @brief Definition for the service_plugin property: The application password be issued from service provider for 3rd party developer.
  59  * @since_tizen 2.4
  60  * @see service_plugin_add_property()
  61  * @see service_plugin_remove_property()
  62  * @see service_plugin_get_property()
  63  */
  64 #define SERVICE_PLUGIN_PROPERTY_APP_SECRET      "http://tizen.org/service-adaptor/plugin/property/app_secret"
  65
  66 /**
  67  * @brief Definition for the service_plugin property: The user id for using specific service.
  68  * @since_tizen 2.4
  69  * @see service_plugin_add_property()
  70  * @see service_plugin_remove_property()
  71  * @see service_plugin_get_property()
  72  */
  73 #define SERVICE_PLUGIN_PROPERTY_USER_ID         "http://tizen.org/service-adaptor/plugin/property/user_id"
  74
  75 /**
  76  * @brief The handle for connection and managing handle of Service Plugin
  77  * @details The handle can be created by service_plugin_create()<br>
  78  *  When a handle is no longer needed, use service_plugin_destroy()
  79  * @see #service_plugin_create()
  80  * @see #service_plugin_destroy()
  81  */
  82 typedef struct _service_plugin_s *service_plugin_h;
  83
  84 /**
  85  * @brief Callback for service_adaptor_foreach_plugin API
  86  *
  87  * @param[in]    uri      The service plugin's unique uri, this value be set by plugin
  88  * @param[in]    service_mask    Masked value for <b>installed</b> service plugins, this value can be masked multiple enum (#service_plugin_service_type_e)
  89  * @param[in]    user_data       Passed data from #service_adaptor_foreach_plugin()
  90  * @remarks      @a service_mask check using 'bit and' operation with #service_plugin_service_type_e
  91  * @remarks      - for example,
  92  * @remarks      &nbsp;&nbsp;&nbsp;&nbsp;        if(@a service_mask & SERVICE_PLUGIN_SERVICE_STORAGE)
  93  * @remarks      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;        { @a USING_STORAGE_CODE }
  94  * @remarks Do not release memory of @a plugin_uri
  95  * @see          service_plugin_service_type_e
  96  * @return @c true to continue with the next iteration of the loop,
  97  *         otherwise @c false to break out of the loop
  98  * @pre  service_adaptor_foreach_plugin() will invoke this callback.
  99  */
 100 typedef bool (*service_adaptor_plugin_cb)(const char *uri,
 101                 int service_mask,
 102                 void *user_data);
 103
 104 /**
 105  * @brief Callback for service_plugin_login API
 106  *
 107  * @param[in]    result
 108  * @param[in]    user_data       Passed data from #service_plugin_login()
 109  * @remarks
 110  * @return void
 111  * @pre  service_plugin_login() will invoke this callback.
 112  */
 113 typedef void (*service_plugin_login_cb)(int result,
 114                 void *user_data);
 115
 116 /*==================================================================================================
 117                                          FUNCTION PROTOTYPES
 118 ==================================================================================================*/
 119
 120 /**
 121  * @brief Create Service Adaptor
 122  * @since_tizen 2.4
 123  *
 124  * @param[out]  service_adaptor The Service Adaptor handle
 125  * @remarks     @a service_adaptor must be released memory using service_adaptor_destroy(), when a program no longer needs any function of Service Adaptor
 126  * @see         service_adaptor_destroy()
 127  * @return 0 on success, otherwise a negative error value
 128  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 129  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 130  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 131  */
 132 int service_adaptor_connect();
 133
 134 /**
 135  * @brief       Destroy Service Adaptor
 136  * @details     It must called after a program no longer needs any function of Service Adaptor
 137  * @since_tizen 2.4
 138  *
 139  * @param[in]   service_adaptor The handle of Service Adaptor
 140  * @see         service_adaptor_create()
 141  * @return 0 on success, otherwise a negative error value
 142  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 143  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 144  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 145  * @pre  @a service_adaptor must be issued by service_adaptor_create()
 146  */
 147 int service_adaptor_disconnect();
 148
 149 /**
 150  * @brief Foreach the list of plugin
 151  * @details Iterate to all installed plugin
 152  * @since_tizen 2.4
 153  *
 154  * @param[in]    callback        The callback for foreach plugin
 155  * @param[in]    user_data       Passed data to callback
 156  * @return 0 on success, otherwise a negative error value
 157  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 158  * @retval #SERVICE_ADAPTOR_ERROR_NO_DATA There is no available plugins
 159  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 160  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 161  * @pre  @a service_adaptor must be issued by service_adaptor_create()
 162  */
 163 int service_adaptor_foreach_plugin(service_adaptor_plugin_cb callback,
 164                 void *user_data);
 165
 166 /**
 167  * @brief Gets service specfic last result
 168  * @details This function retrieves the last error code that be issued from plugin.<br>
 169  *  When if API function returns #SERVICE_ADAPTOR_ERROR_PLUGIN_FAILED, gets using this function.
 170  * @since_tizen 2.4
 171  *
 172  * @param[out]   err     The error number that is defined service plugin SPEC
 173  * @remarks      Thread safe functions
 174  * @remarks      The result number's detail specification is defined service plugin or provider.
 175  * @remarks      The detail error message can be got using service_adaptor_get_last_error_message()
 176  * @see          service_adaptor_get_last_error_message()
 177  * @return 0 on success, otherwise a negative error value
 178  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 179  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 180  * @retval #SERVICE_ADAPTOR_ERROR_NO_DATA There is no result
 181  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 182  */
 183 int service_adaptor_get_last_result(int *err);
 184
 185 /**
 186  * @brief Gets service specfic last result error message
 187  * @details This function retrieves the last error code that be issued from plugin.<br>
 188  *  When if API function returns #SERVICE_ADAPTOR_ERROR_PLUGIN_FAILED, gets using this function.
 189  * @since_tizen 2.4
 190  *
 191  * @param[out]   message The error message that is defined service plugin SPEC
 192  * @remarks      @a message must be released using free()
 193  * @remarks      Thread safe functions
 194  * @remarks      The result string's detail specification is defined service plugin or provider.
 195  * @see          service_adaptor_get_last_result()
 196  * @return 0 on success, otherwise a negative error value
 197  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 198  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 199  * @retval #SERVICE_ADAPTOR_ERROR_NO_DATA There is no error message
 200  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 201  */
 202 int service_adaptor_get_last_error_message(char **message);
 203
 204 /*
 205 int service_adaptor_add_plugin(service_adaptor_h adaptor_client, const char *plugin_uri);
 206 int service_adaptor_remove_plugin(service_adaptor_h adaptor_client, const char *plugin_uri);
 207 int service_adaptor_get_auth(service_adaptor_h adaptor_client, const char *uri, service_auth_h *auth);
 208 */
 209
 210 /**
 211  * @brief Create service plugin handle
 212  * @details Create plugin handle using @a plugin_uri
 213  * @since_tizen 2.4
 214  *
 215  * @param[in]    service_adaptor The handle of Service Adaptor
 216  * @param[in]    plugin_uri      The specfic string for use plugin, this values are set by plugin
 217  * @param[out]   plugin          The handle for use Plugin APIs
 218  * @remarks      @a plugin must be released memory using service_plugin_destroy() when you no longer needs plugin's API
 219  * @see          service_plugin_destroy()
 220  * @return 0 on success, otherwise a negative error value
 221  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 222  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 223  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 224  * @pre  @a service_adaptor must be issued by service_adaptor_create()
 225  */
 226 int service_plugin_create(const char *uri, service_plugin_h *plugin);
 227
 228 /**
 229  * @brief        Destroy service plugin handle
 230  * @details      It must called after a program no longer needs APIs of specfic plugin
 231  * @since_tizen 2.4
 232  *
 233  * @param[in]    plugin  The handle for use Plugin APIs
 234  * @see  service_adaptor_create_plugin()
 235  * @return 0 on success, otherwise a negative error value
 236  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 237  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 238  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 239  * @pre  @a plugin must be issued by service_adaptor_create_plugin()
 240  */
 241 int service_plugin_destroy(service_plugin_h plugin);
 242
 243 /**
 244  * @brief Add Plugin Property
 245  * @details The plguin property is used for plugin's basic or optional requirement.<br>
 246  *  This value is not used in Adaptor layer, but it can be uesd to important Key for plugin with service provider.<br>
 247  * @since_tizen 2.4
 248  *
 249  * @param[in]    plugin  The handle for use Plugin APIs
 250  * @param[in]    key     The key of plugin property
 251  * @param[in]    value   The value of plugin property that matched @a key
 252  * @remarks      Some kind of property key(Not mandatory) is defined in this API (That is named to SERVICE_PLUGIN_PROPERTY_XXX)
 253  * @remarks      If the @a key already exists in the property its current value is replaced with the new @a value.
 254  * @remarks      @a plugin must be released memory using #service_plugin_destroy() when you no longer needs plugin's API
 255  * @return 0 on success, otherwise a negative error value
 256  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 257  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 258  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 259  * @see  SERVICE_PLUGIN_PROPERTY_APP_KEY
 260  * @see  SERVICE_PLUGIN_PROPERTY_APP_SECRET
 261  * @see  SERVICE_PLUGIN_PROPERTY_USER_ID
 262  * @pre  @a plugin must be issued by service_adaptor_create_plugin()
 263  */
 264 int service_plugin_add_property(service_plugin_h plugin,
 265                 const char *key,
 266                 const char *value);
 267
 268 /**
 269  * @brief Remove Plugin Property
 270  * @since_tizen 2.4
 271  *
 272  * @param[in]    plugin  The handle for use Plugin APIs
 273  * @param[in]    key     The key of plugin property
 274  * @remarks      Some kind of property key(Not mandatory) is defined in this API (That is named to SERVICE_PLUGIN_PROPERTY_XXX)
 275  * @return 0 on success, otherwise a negative error value
 276  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 277  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 278  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 279  * @see  SERVICE_PLUGIN_PROPERTY_APP_KEY
 280  * @see  SERVICE_PLUGIN_PROPERTY_APP_SECRET
 281  * @see  SERVICE_PLUGIN_PROPERTY_USER_ID
 282  */
 283 int service_plugin_remove_property(service_plugin_h plugin,
 284                 const char *key);
 285
 286 /**
 287  * @brief Gets Plugin Property
 288  * @since_tizen 2.4
 289  *
 290  * @param[in]    plugin  The handle for use Plugin APIs
 291  * @param[in]    key     The key of plugin property
 292  * @param[out]   value   The value of plugin property that matched @a key
 293  * @remarks      Some kind of property key(Not mandatory) is defined in this API (That is named to SERVICE_PLUGIN_PROPERTY_XXX)
 294  * @remarks      @a value must be released using free()
 295  * @return 0 on success, otherwise a negative error value
 296  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 297  * @retval #SERVICE_ADAPTOR_ERROR_NO_DATA There is no property
 298  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 299  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 300  * @see  SERVICE_PLUGIN_PROPERTY_APP_KEY
 301  * @see  SERVICE_PLUGIN_PROPERTY_APP_SECRET
 302  * @see  SERVICE_PLUGIN_PROPERTY_USER_ID
 303  * @pre  The function get property already set by service_adaptor_set_plugin_property()
 304  */
 305 int service_plugin_get_property(service_plugin_h plugin,
 306                 const char *key,
 307                 char **value);
 308
 309 /**
 310  * @brief Logins Plugin using Property
 311  * @since_tizen 3.0
 312  *
 313  * @param[in]    plugin  The handle for use Plugin APIs
 314  * @param[in]    callback        The callback for login
 315  * @param[in]    user_data       Passed data to callback
 316  * @remarks
 317  * @remarks      @a value must be released using free()
 318  * @return 0 on success, otherwise a negative error value
 319  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 320  * @retval #SERVICE_ADAPTOR_ERROR_NO_DATA There is no property
 321  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 322  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 323  * @pre  The function get property already set by service_adaptor_set_plugin_property()
 324  */
 325 int service_plugin_login(service_plugin_h plugin, service_plugin_login_cb callback, void *user_data);
 326
 327 /**
 328  * @brief Requests start initalization for service plugin
 329  * @since_tizen 2.4
 330  *
 331  * @param[in]    plugin          The handle for use Plugin APIs
 332  * @remarks      @a service_mask must be input using 'bit or' operation with #service_plugin_service_type_e
 333  * @remarks      - for example,
 334  * @remarks      &nbsp;&nbsp;&nbsp;&nbsp;        <b>int</b> @a service_mask |= SERVIE_PLUGIN_SERVICE_AUTH;
 335  * @remarks      &nbsp;&nbsp;&nbsp;&nbsp;        @a service_mask |= SERVICE_PLUGIN_SERVICE_STORAGE;
 336  * @remarks      &nbsp;&nbsp;&nbsp;&nbsp;        <b>int</b> ret = service_plugin_start(@a m_plugin, @a service_mask);
 337  * @remarks      If a program needs to stop plugin manually, use #service_plugin_stop(). <br>But in #service_plugin_destroy(), automatically stop service plugin
 338  * @see          service_plugin_service_type_e
 339  * @see          service_plugin_stop()
 340  * @return 0 on success, otherwise a negative error value
 341  * @return If return value is #SERVICE_ADAPTOR_ERROR_NOT_AUTHOLIZED, request signup to autholization application
 342  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 343  * @retval #SERVICE_ADAPTOR_ERROR_INVALID_PARAMETER Invalid parameter
 344  * @retval #SERVICE_ADAPTOR_ERROR_NOT_AUTHOLIZED Need atholization
 345  * @retval #SERVICE_ADAPTOR_ERROR_TIMED_OUT Timed out
 346  * @retval #SERVICE_ADAPTOR_ERROR_IPC_UNSTABLE IPC failed with Service Adaptor Daemon
 347  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 348  */
 349 int service_plugin_start(service_plugin_h plugin);
 350 /**
 351  * @brief Requests stop manually for service plugin
 352  * @since_tizen 2.4
 353  *
 354  * @param[in]    plugin          The handle for use Plugin APIs
 355  * @remarks      If a program needs to stop plugin manually, use this function. <br>But in #service_plugin_destroy(), automatically stop service plugin
 356  * @remarks      @a plugin must be released memory using #service_plugin_destroy() when you no longer needs plugin's API
 357  * @see          service_plugin_start()
 358  * @see          service_plugin_destroy()
 359  * @return 0 on success, otherwise a negative error value
 360  * @retval #SERVICE_ADAPTOR_ERROR_NONE Successful
 361  * @retval #SERVICE_ADAPTOR_ERROR_TIMED_OUT Timed out
 362  * @retval #SERVICE_ADAPTOR_ERROR_IPC_UNSTABLE IPC failed with Service Adaptor Daemon
 363  * @retval #SERVICE_ADAPTOR_ERROR_UNKNOWN Unknown error
 364  * @pre  service_plugin_start()
 365  */
 366 int service_plugin_stop(service_plugin_h plugin);
 367
 368 /**
 369  * @}
 370  */
 371
 372 #ifdef __cplusplus
 373 }
 374 #endif
 375
 376 #endif /* __SERVICE_ADAPTOR_H__ */