include/system_settings.h

   1 /*
   2  * Copyright (c) 2011 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_SYSTEM_SYSTEM_SETTINGS_H__
  18 #define __TIZEN_SYSTEM_SYSTEM_SETTINGS_H__
  19
  20 #include <tizen.h>
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27 /**
  28  * @file system_settings.h
  29  */
  30
  31 /**
  32  * @addtogroup CAPI_SYSTEM_SYSTEM_SETTINGS_MODULE
  33  * @{
  34  */
  35
  36
  37 /**
  38  * @brief Enumeration for system settings error.
  39  * @since_tizen 2.3
  40  */
  41 typedef enum
  42 {
  43         SYSTEM_SETTINGS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  44         SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  45         SYSTEM_SETTINGS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  46         SYSTEM_SETTINGS_ERROR_IO_ERROR =  TIZEN_ERROR_IO_ERROR, /**< Internal I/O error */
  47         SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED =  TIZEN_ERROR_PERMISSION_DENIED, /**< Permition denied */
  48         SYSTEM_SETTINGS_ERROR_NOT_SUPPORTED =  TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported @if MOBILE (Since 2.3.1) @endif */
  49         SYSTEM_SETTINGS_ERROR_CALL_UNSUPPORTED_API = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported @if MOBILE (Since 2.3.1) @endif */
  50
  51         /* lock screen app error code */
  52         SYSTEM_SETTINGS_ERROR_LOCKSCREEN_APP_PASSWORD_MODE = TIZEN_ERROR_SYSTEM_SETTING | 0x01, /**< Current lock screen app set 'password' type */
  53 }
  54 system_settings_error_e;
  55
  56
  57 /**
  58  * @brief Enumeration for System Settings Key.
  59  * @since_tizen 2.3
  60  */
  61 typedef enum {
  62     SYSTEM_SETTINGS_KEY_INCOMING_CALL_RINGTONE, /**< (string) The file path of the current ringtone */
  63     SYSTEM_SETTINGS_KEY_WALLPAPER_HOME_SCREEN, /**< (string) The file path of the current home screen wallpaper */
  64     SYSTEM_SETTINGS_KEY_WALLPAPER_LOCK_SCREEN, /**< (string) The file path of the current lock screen wallpaper */
  65     SYSTEM_SETTINGS_KEY_FONT_SIZE, /**< (int) The current system font size */
  66     SYSTEM_SETTINGS_KEY_FONT_TYPE, /**< (string) The current system font type */
  67
  68     SYSTEM_SETTINGS_KEY_MOTION_ACTIVATION, /**< (bool) Indicates whether the motion service is activated */
  69     SYSTEM_SETTINGS_KEY_EMAIL_ALERT_RINGTONE,  /**< (string) The file path of the current email alert ringtone */
  70     SYSTEM_SETTINGS_KEY_USB_DEBUGGING_ENABLED,  /**< (bool) Indicates whether the USB debugging is enabled (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif) */
  71     SYSTEM_SETTINGS_KEY_3G_DATA_NETWORK_ENABLED,  /**< bool) Indicates whether the 3G data network is enabled (Since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif) */
  72     SYSTEM_SETTINGS_KEY_LOCKSCREEN_APP = SYSTEM_SETTINGS_KEY_3G_DATA_NETWORK_ENABLED+2,  /**< (string) Indicates lockscreen app pkg name  */
  73
  74     SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE,/**< (string) The current system default font type (only support Get) */
  75     SYSTEM_SETTINGS_KEY_LOCALE_COUNTRY,         /**< (string) Indicates the current country setting in the <LANGUAGE>_<REGION> syntax. The country setting is in the ISO 639-2 format, and the region setting is in the ISO 3166-1 alpha-2 format */
  76     SYSTEM_SETTINGS_KEY_LOCALE_LANGUAGE,        /**< (string) Indicates the current language setting in the <LANGUAGE>_<REGION> syntax. The language setting is in the ISO 639-2 format and the region setting is in the ISO 3166-1 alpha-2 format. */
  77     SYSTEM_SETTINGS_KEY_LOCALE_TIMEFORMAT_24HOUR,       /**< (bool) Indicates whether the 24-hour clock is used. If the value is @c false, the 12-hour clock is used. */
  78     SYSTEM_SETTINGS_KEY_LOCALE_TIMEZONE,        /**< (string) Indicates the current time zone. */
  79
  80     SYSTEM_SETTINGS_KEY_TIME_CHANGED,           /**< (int) Once System changes time, this event occurs to notify time change. */
  81     SYSTEM_SETTINGS_KEY_SOUND_LOCK,                                     /**< GET (bool) Indicates whether the screen lock sound is enabled on the device. ex) LCD on/off sound */
  82     SYSTEM_SETTINGS_KEY_SOUND_SILENT_MODE,                      /**< GET (bool) Indicates whether the device is in the silent mode. */
  83     SYSTEM_SETTINGS_KEY_SOUND_TOUCH,                            /**< GET (bool) Indicates whether the screen touch sound is enabled on the device. */
  84     SYSTEM_SETTINGS_KEY_DISPLAY_SCREEN_ROTATION_AUTO,   /**< GET (bool) Indicates whether rotation control is automatic.*/
  85
  86     SYSTEM_SETTINGS_KEY_DEVICE_NAME,                                    /**< GET (string) Indicates device name. */
  87     SYSTEM_SETTINGS_KEY_MOTION_ENABLED,                                 /**< GET (bool) Indicates whether the device user has enabled the motion feature. */
  88     SYSTEM_SETTINGS_KEY_NETWORK_WIFI_NOTIFICATION,              /**< GET (bool) Indicates whether Wi-Fi-related notifications are enabled on the device. */
  89     SYSTEM_SETTINGS_KEY_NETWORK_FLIGHT_MODE,                    /**< GET (bool) Indicates whether the device is in the flight mode. */
  90     SYSTEM_SETTINGS_KEY_SCREEN_BACKLIGHT_TIME,                  /**< (int) Indicates the backlight time (in seconds). @internal The following values can be used: 15, 30, 60, 120, 300, and 600. */
  91
  92     SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATION,                     /**< (string) Indicates the file path of the current notification tone set by the user. */
  93     SYSTEM_SETTINGS_KEY_SOUND_NOTIFICATION_REPETITION_PERIOD,   /**< (int) Indicates the time period for notification repetitions. */
  94     SYSTEM_SETTINGS_KEY_LOCK_STATE,     /**< (int) Indicates the current lock state */
  95     SYSTEM_SETTINGS_KEY_MAX,
  96
  97 } system_settings_key_e;
  98
  99 /**
 100  * @brief Enumeration for Idle Lock State
 101  * @since_tizen 2.3.1
 102  */
 103 typedef enum {
 104     SYSTEM_SETTINGS_LOCK_STATE_UNLOCK = 0, /**< Device is unlocked */
 105     SYSTEM_SETTINGS_LOCK_STATE_LOCK, /**< Device is locked */
 106     SYSTEM_SETTINGS_LOCK_STATE_LAUNCHING_LOCK /**< Device is being locked */
 107 } system_settings_idle_lock_state_e;
 108
 109
 110 /**
 111  * @brief Enumeration for font size.
 112  * @since_tizen 2.3
 113  */
 114 typedef enum {
 115     SYSTEM_SETTINGS_FONT_SIZE_SMALL = 0, /**< A small size */
 116     SYSTEM_SETTINGS_FONT_SIZE_NORMAL, /**< A normal size */
 117     SYSTEM_SETTINGS_FONT_SIZE_LARGE, /**< A large size */
 118     SYSTEM_SETTINGS_FONT_SIZE_HUGE, /**< A huge size */
 119     SYSTEM_SETTINGS_FONT_SIZE_GIANT, /**< A giant size */
 120 } system_settings_font_size_e;
 121
 122
 123 /**
 124  * @brief Called when the system settings changes.
 125  * @since_tizen 2.3
 126  * @param[in] key The key name of the system settings changed system settings
 127  * @param[in] user_data The user data passed from the callback registration function
 128  * @pre system_settings_set_changed_cb() will invoke this callback function.
 129  * @see system_settings_set_changed_cb()
 130  * @see system_settings_unset_changed_cb()
 131  */
 132 typedef void (*system_settings_changed_cb)(system_settings_key_e key, void *user_data);
 133
 134 /**
 135  * @platform
 136  * @brief Sets the system settings value associated with the given key as an integer.
 137  * @since_tizen 2.3
 138  * @privlevel platform
 139  * @privilege %http://tizen.org/privilege/systemsettings.admin
 140  * @param[in] key The key name of the system settings changed
 141  * @param[in] key The key name of the system settings
 142  * @param[out] value The new system settings value of the given key
 143  * @return @c 0 on success, otherwise a negative error value
 144  * @retval  #SYSTEM_SETTINGS_ERROR_NONE Successful
 145  * @retval  #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
 146  * @retval  #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
 147  * @retval  #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
 148  */
 149 int system_settings_set_value_int(system_settings_key_e key, int value);
 150
 151 /**
 152  * @brief Gets the system settings value associated with the given key as an integer.
 153  * @since_tizen 2.3
 154  * @param[in] key The key name of the system settings
 155  * @param[out] value The current system settings value of the given key
 156  * @return @c 0 on success, otherwise a negative error value
 157  * @retval  #SYSTEM_SETTINGS_ERROR_NONE Successful
 158  * @retval  #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
 159  * @retval  #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
 160  * @retval  #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
 161  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this API since 2.3.1.
 162  */
 163 int system_settings_get_value_int(system_settings_key_e key, int *value);
 164
 165
 166 /**
 167  * @platform
 168  * @brief Sets the system settings value associated with the given key as a boolean.
 169  * @since_tizen 2.3
 170  * @privlevel platform
 171  * @privilege %http://tizen.org/privilege/systemsettings.admin
 172  * @param[in] key The key name of the system settings
 173  * @param[out] value The new system settings value of the given key
 174  * @return @c 0 on success, otherwise a negative error value
 175  * @retval  #SYSTEM_SETTINGS_ERROR_NONE Successful
 176  * @retval  #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
 177  * @retval  #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
 178  * @retval  #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
 179  */
 180 int system_settings_set_value_bool(system_settings_key_e key, bool value);
 181
 182 /**
 183  * @brief Gets the system settings value associated with the given key as a boolean.
 184  * @since_tizen 2.3
 185  * @param[in] key The key name of the system settings
 186  * @param[out] value The current system settings value of the given key
 187  * @return @c 0 on success, otherwise a negative error value
 188  * @retval  #SYSTEM_SETTINGS_ERROR_NONE Successful
 189  * @retval  #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
 190  * @retval  #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
 191  * @retval  #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
 192  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this API since 2.3.1.
 193  */
 194 int system_settings_get_value_bool(system_settings_key_e key, bool *value);
 195
 196 /**
 197  * @platform
 198  * @brief Sets the system settings value associated with the given key as a string.
 199  * @since_tizen 2.3
 200  * @privlevel platform
 201  * @privilege %http://tizen.org/privilege/systemsettings.admin
 202  * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for setting.
 203  * @param[in] key The key name of the system settings
 204  * @param[out] value The new system settings value of the given key
 205  * @return @c 0 on success, otherwise a negative error value
 206  * @retval  #SYSTEM_SETTINGS_ERROR_NONE Successful
 207  * @retval  #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
 208  * @retval  #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
 209  * @retval  #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
 210  */
 211 int system_settings_set_value_string(system_settings_key_e key, const char *value);
 212
 213 /**
 214  * @brief Gets the system settings value associated with the given key as a string.
 215  * @since_tizen 2.3
 216  * @remarks You must release @a value using free().
 217  * @param[in] key The key name of the system settings
 218  * @param[out] value The current system settings value of the given key
 219  * @return  0 on success, otherwise a negative error value
 220  * @retval  #SYSTEM_SETTINGS_ERROR_NONE Successful
 221  * @retval  #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
 222  * @retval  #SYSTEM_SETTINGS_ERROR_IO_ERROR Internal I/O error
 223  * @retval  #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
 224  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this API since 2.3.1.
 225  */
 226 int system_settings_get_value_string(system_settings_key_e key, char **value);
 227
 228 /**
 229  * @brief Registers a change event callback for the given system settings key.
 230  * @since_tizen 2.3
 231  * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb.
 232  * @param[in] key The key name of the system settings
 233  * @param[in] callback The callback function to invoke
 234  * @param[in] user_data The user data to be passed to the callback function
 235  * @return  0 on success, otherwise a negative error value
 236  * @retval  #SYSTEM_SETTINGS_ERROR_NONE Successful
 237  * @retval  #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
 238  * @retval  #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
 239  * @post system_settings_changed_cb() will be invoked.
 240  *
 241  * @see system_settings_unset_changed_cb()
 242  * @see system_settings_changed_cb()
 243  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this API since 2.3.1.
 244  *
 245 */
 246 int system_settings_set_changed_cb(system_settings_key_e key, system_settings_changed_cb callback, void *user_data);
 247
 248 /**
 249  * @brief Unregisters the callback function.
 250  * @since_tizen 2.3
 251  * @remarks #SYSTEM_SETTINGS_KEY_DEFAULT_FONT_TYPE is not available for set_changed_cb.
 252  * @param[in] key The key name of the system settings
 253  * @return  0 on success, otherwise a negative error value
 254  * @retval  #SYSTEM_SETTINGS_ERROR_NONE Successful
 255  * @retval  #SYSTEM_SETTINGS_ERROR_INVALID_PARAMETER Invalid parameter
 256  * @retval  #SYSTEM_SETTINGS_ERROR_PERMISSION_DENIED Permission violation error
 257  *
 258  * @see system_settings_set_changed_cb()
 259  * @warning %http://tizen.org/privilege/systemsettings (public level privilege) <b>MUST NOT</b> be declared to use this API since 2.3.1.
 260  */
 261 int system_settings_unset_changed_cb(system_settings_key_e key);
 262
 263
 264 /**
 265  * @}
 266  */
 267
 268
 269 #ifdef __cplusplus
 270 }
 271 #endif
 272
 273 #endif /* __TIZEN_SYSTEM_SYSTEM_SETTINGS_H__ */