From: Jyothi Kumar Sambolu Date: Thu, 15 Sep 2016 10:44:05 +0000 (+0530) Subject: [Preference] CS API implementation with doxygen comments X-Git-Tag: submit/trunk/20170823.075128~121^2~125 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=7a10b3b4e9998ded66400fb5c8848af1ad91df43;p=platform%2Fcore%2Fcsapi%2Ftizenfx.git [Preference] CS API implementation with doxygen comments Change-Id: I05013552f5da06055b671e1b97a2c96f5717556c Signed-off-by: Jyothi Kumar Sambolu --- diff --git a/Tizen.Applications/Interop/Interop.Libraries.cs b/Tizen.Applications/Interop/Interop.Libraries.cs index a306507..ffb57fe 100755 --- a/Tizen.Applications/Interop/Interop.Libraries.cs +++ b/Tizen.Applications/Interop/Interop.Libraries.cs @@ -22,6 +22,7 @@ internal static partial class Interop public const string Glib = "libglib-2.0.so.0"; public const string Libc = "libc.so.6"; public const string Notification = "libnotification.so.0"; + public const string Preference = "libcapi-appfw-preference.so.0"; public const string Alarm = "libcapi-appfw-alarm.so.0"; } } diff --git a/Tizen.Applications/Interop/Interop.Preference.cs b/Tizen.Applications/Interop/Interop.Preference.cs new file mode 100644 index 0000000..795911f --- /dev/null +++ b/Tizen.Applications/Interop/Interop.Preference.cs @@ -0,0 +1,69 @@ +// Copyright 2016 by Samsung Electronics, Inc., +// +// This software is the confidential and proprietary information +// of Samsung Electronics, Inc. ("Confidential Information"). You +// shall not disclose such Confidential Information and shall use +// it only in accordance with the terms of the license agreement +// you entered into with Samsung. + +using System; +using System.Runtime.InteropServices; +using Tizen.Applications; + +/// +/// Contains Interop declarations of Preference classes. +/// +internal static partial class Interop +{ + /// + /// Contains Interop declarations of Preference device API. + /// + internal static partial class Preference + { + internal delegate void ChangedCallback(string key, IntPtr userData); + + internal delegate bool ItemCallback(string key, IntPtr userData); + + [DllImport(Libraries.Preference, EntryPoint = "preference_set_int")] + internal static extern int SetInt(string key, int value); + + [DllImport(Libraries.Preference, EntryPoint = "preference_get_int")] + internal static extern int GetInt(string key, out int value); + + [DllImport(Libraries.Preference, EntryPoint = "preference_set_double")] + internal static extern int SetDouble(string key, double value); + + [DllImport(Libraries.Preference, EntryPoint = "preference_get_double")] + internal static extern int GetDouble(string key, out double value); + + [DllImport(Libraries.Preference, EntryPoint = "preference_set_string")] + internal static extern int SetString(string key, string value); + + [DllImport(Libraries.Preference, EntryPoint = "preference_get_string")] + internal static extern int GetString(string key, out string value); + + [DllImport(Libraries.Preference, EntryPoint = "preference_set_boolean")] + internal static extern int SetBoolean(string key, bool value); + + [DllImport(Libraries.Preference, EntryPoint = "preference_get_boolean")] + internal static extern int GetBoolean(string key, out bool value); + + [DllImport(Libraries.Preference, EntryPoint = "preference_remove")] + internal static extern int Remove(string key); + + [DllImport(Libraries.Preference, EntryPoint = "preference_is_existing")] + internal static extern int IsExisting(string key, out bool existing); + + [DllImport(Libraries.Preference, EntryPoint = "preference_remove_all")] + internal static extern int RemoveAll(); + + [DllImport(Libraries.Preference, EntryPoint = "preference_set_changed_cb")] + internal static extern int SetChangedCb(string key, ChangedCallback callback, IntPtr userData); + + [DllImport(Libraries.Preference, EntryPoint = "preference_unset_changed_cb")] + internal static extern int UnsetChangedCb(string key); + + [DllImport(Libraries.Preference, EntryPoint = "preference_foreach_item")] + internal static extern int ForeachItem(ItemCallback callback, IntPtr userData); + } +} diff --git a/Tizen.Applications/Tizen.Applications.Net45.csproj b/Tizen.Applications/Tizen.Applications.Net45.csproj index 4ce9087..f3af594 100644 --- a/Tizen.Applications/Tizen.Applications.Net45.csproj +++ b/Tizen.Applications/Tizen.Applications.Net45.csproj @@ -60,6 +60,7 @@ + @@ -94,6 +95,8 @@ + + diff --git a/Tizen.Applications/Tizen.Applications.csproj b/Tizen.Applications/Tizen.Applications.csproj index 69c820c..d657c80 100644 --- a/Tizen.Applications/Tizen.Applications.csproj +++ b/Tizen.Applications/Tizen.Applications.csproj @@ -57,6 +57,7 @@ + @@ -91,6 +92,8 @@ + + diff --git a/Tizen.Applications/Tizen.Applications/Preference.cs b/Tizen.Applications/Tizen.Applications/Preference.cs new file mode 100644 index 0000000..44cc1a7 --- /dev/null +++ b/Tizen.Applications/Tizen.Applications/Preference.cs @@ -0,0 +1,450 @@ +// Copyright 2016 by Samsung Electronics, Inc., +// +// This software is the confidential and proprietary information +// of Samsung Electronics, Inc. ("Confidential Information"). You +// shall not disclose such Confidential Information and shall use +// it only in accordance with the terms of the license agreement +// you entered into with Samsung. + +using System; +using System.Collections.Generic; +using Tizen.Internals.Errors; + +namespace Tizen.Applications +{ + /// + /// The Preference class provides APIs to store and retrieve application specific data/preference. A preference is saved in the form of a key-value pair. + /// Keys are always text strings and value can be any one of four types: integer, double, string and boolean. + /// + public static class Preference + { + private const string LogTag = "Tizen.Applications"; + private static Interop.Preference.ChangedCallback s_preferenceChangedCallback; + private static IDictionary s_eventMap = new Dictionary(); + + static Preference() + { + s_preferenceChangedCallback = (string key, IntPtr userData) => + { + try + { + s_eventMap[key]?.FireEvent(); + } + catch (Exception e) + { + Log.Warn(LogTag, e.Message); + } + }; + } + + /// + /// Retrieves all keys of the application preferences + /// + /// + /// The list of keys + /// + /// + /// + /// Preference.Set("Option_enabled", true); + /// Preference.Set("active_user", "Joe"); + /// Preference.Set("default_volume", 10); + /// Preference.Set("brightness", "0.6"); + /// foreach(string key in Preference.Keys) + /// { + /// Console.WriteLine("key {0}", key); + /// } + /// + /// + public static IEnumerable Keys + { + get + { + var collection = new List(); + Interop.Preference.ItemCallback itemsCallback = (string key, IntPtr userData) => + { + collection.Add(key); + return true; + }; + Interop.Preference.ForeachItem(itemsCallback, IntPtr.Zero); + return collection; + } + } + + /// + /// Gets the event context for the given key. + /// + /// + /// The preference key + /// The event context of respective key + /// Thrown if the key is not found + /// Thrown if the key is an invalid parameter. + /// + /// + /// private static void Preference_PreferenceChanged(object sender, PreferenceChangedEventArgs e) + /// { + /// Console.WriteLine("key {0}", e.Key); + /// } + /// + /// Preference.EventContext context = null; + /// Preference.GetEventContext("active_user").TryGetTarget(out context); + /// if(context != null) + /// { + /// context.Changed += Preference_PreferenceChanged; + /// } + /// + /// Preference.Set("active_user", "Poe"); + /// + /// Preference.GetEventContext("active_user").TryGetTarget(out context); + /// if (context != null) + /// { + /// context.Changed -= Preference_PreferenceChanged; + /// } + /// + /// + public static WeakReference GetEventContext(string key) + { + if (!s_eventMap.ContainsKey(key)) + { + if (Contains(key)) + { + s_eventMap[key] = new EventContext(key); + } + else + { + throw PreferenceErrorFactory.GetException((int)ErrorCode.KeyNotAvailable); + } + } + + return new WeakReference(s_eventMap[key]); + } + + /// + /// Checks whether the given key exists in the preference. + /// + /// The name of the key to check + /// true if the key exists in the preference, otherwise false + /// Thrown if the key is an invalid parameter. + /// Thrown when method failed due to internal IO error. + /// + /// + /// Preference.Set("active_user", "Joe"); + /// bool exists = Preference.Contains("active_user"); + /// if (exists) + /// { + /// string value = Preference.Get("active_user"); + /// Console.WriteLine("user {0}", value); + /// } + /// + /// + public static bool Contains(string key) + { + bool contains; + int ret = Interop.Preference.IsExisting(key, out contains); + if (ret != (int)PreferenceErrorFactory.PreferenceError.None) + { + Log.Error(LogTag, "Failed to find key"); + throw PreferenceErrorFactory.GetException(ret); + } + + return contains; + } + + /// + /// Sets a key-value pair representing the preference. + /// + /// + /// If the key already exists in the Preference, old value will be overwritten with new value. + /// Data types supported for value are: integer, double, string and bool. + /// + /// The name of the key to create/modigy + /// The value corresponding to the key. + /// Thrown if the key is an invalid parameter. + /// Thrown when method failed due to internal IO error. + /// + /// + /// Preference.Set("Option_enabled", true); + /// Preference.Set("active_user", "Joe"); + /// Preference.Set("default_volume", 10); + /// Preference.Set("brightness", "0.6"); + /// + /// + public static void Set(string key, object value) + { + int ret = 0; + if (value is int) + { + ret = Interop.Preference.SetInt(key, (int)value); + if (ret != (int)PreferenceErrorFactory.PreferenceError.None) + { + Log.Error(LogTag, "Failed to find key"); + throw PreferenceErrorFactory.GetException(ret); + } + } + else if (value is double) + { + ret = Interop.Preference.SetDouble(key, (double)value); + if (ret != (int)PreferenceErrorFactory.PreferenceError.None) + { + Log.Error(LogTag, "Failed to find key"); + throw PreferenceErrorFactory.GetException(ret); + } + } + else if (value is string) + { + ret = Interop.Preference.SetString(key, (string)value); + if (ret != (int)PreferenceErrorFactory.PreferenceError.None) + { + Log.Error(LogTag, "Failed to find key"); + throw PreferenceErrorFactory.GetException(ret); + } + } + else if (value is bool) + { + ret = Interop.Preference.SetBoolean(key, (bool)value); + if (ret != (int)PreferenceErrorFactory.PreferenceError.None) + { + Log.Error(LogTag, "Failed to find key"); + throw PreferenceErrorFactory.GetException(ret); + } + } + } + + /// + /// Gets the value of a preference item with the specified key. + /// Note that this is a generic method. + /// + /// The generic type to return. + /// The key of the preference + /// The value of the preference item if it is of the specified generic type. + /// Thrown if the key is not found + /// Thrown if the key is an invalid parameter. + /// Thrown when method failed due to internal IO error. + /// + /// + /// bool exists = Preference.Contains("active_user"); + /// if (exists) + /// { + /// string value = Preference.Get("active_user"); + /// Console.WriteLine("user {0}", value); + /// } + /// + /// + public static T Get(string key) + { + object result = null; + int ret = (int)PreferenceErrorFactory.PreferenceError.None; + if (typeof(T) == typeof(bool)) + { + bool val; + ret = Interop.Preference.GetBoolean(key, out val); + result = val; + } + else if (typeof(T) == typeof(int)) + { + int val; + ret = Interop.Preference.GetInt(key, out val); + result = val; + } + else if (typeof(T) == typeof(string)) + { + string val; + ret = Interop.Preference.GetString(key, out val); + result = val; + } + else if (typeof(T) == typeof(double)) + { + double val; + ret = Interop.Preference.GetDouble(key, out val); + result = val; + } + else + { + Log.Error(LogTag, "Failed to remove key"); + throw new ArgumentException("Invalid parameter"); + } + + if (ret != (int)PreferenceErrorFactory.PreferenceError.None) + { + Log.Error(LogTag, "Failed to remove key"); + throw PreferenceErrorFactory.GetException(ret); + } + + return (result != null) ? (T)result : default(T); + } + + /// + /// Removes any preference value with the given key. + /// + /// The key to remove + /// Thrown if the key is not found + /// Thrown when method failed due to internal IO error. + /// + /// + /// bool exists = Preference.Contains("active_user"); + /// if (exists) + /// { + /// string value = Preference.Remove("active_user"); + /// } + /// + /// + public static void Remove(string key) + { + int ret = Interop.Preference.Remove(key); + if (ret != (int)PreferenceErrorFactory.PreferenceError.None) + { + Log.Error(LogTag, "Failed to remove key"); + throw PreferenceErrorFactory.GetException(ret); + } + } + + /// + /// Removes all key-value pairs from the preference. + /// + /// Thrown when method failed due to internal IO error. + /// + /// + /// Preference.Set("Option_enabled", true); + /// Preference.Set("active_user", "Joe"); + /// Preference.Set("default_volume", 10); + /// Preference.Set("brightness", "0.6"); + /// Preference.RemoveAll(); + /// + /// + public static void RemoveAll() + { + int ret = Interop.Preference.RemoveAll(); + if (ret != (int)PreferenceErrorFactory.PreferenceError.None) + { + Log.Error(LogTag, "Failed to remove all keys"); + throw PreferenceErrorFactory.GetException(ret); + } + } + + private static void AllowChangeNotifications(string key) + { + int ret = Interop.Preference.SetChangedCb(key, s_preferenceChangedCallback, IntPtr.Zero); + if (ret != (int)PreferenceErrorFactory.PreferenceError.None) + { + Log.Error(LogTag, "Failed to set key notification"); + throw PreferenceErrorFactory.GetException(ret); + } + } + + private static void DisallowChangeNotifications(string key) + { + int ret = Interop.Preference.UnsetChangedCb(key); + if (ret != (int)PreferenceErrorFactory.PreferenceError.None) + { + Log.Error(LogTag, "Failed to remove key notification"); + throw PreferenceErrorFactory.GetException(ret); + } + } + + /// + /// The class manages event handlers of preference keys. The class enables having event handlers for individual preference keys. + /// + public class EventContext + { + private string _key; + + internal EventContext(string key) + { + _key = key; + } + + /// + /// Occurs whenever there is change in the value of preference key. + /// + /// Thrown when the key does not exist or when there is an invalid parameter. + /// Thrown when the Bundle instance has been disposed. + /// + /// + /// private static void Preference_PreferenceChanged(object sender, PreferenceChangedEventArgs e) + /// { + /// Console.WriteLine("key {0}", e.Key); + /// } + /// Preference.EventContext context = null; + /// Preference.GetEventContext("active_user").TryGetTarget(out context); + /// if(context != null) + /// { + /// context.Changed += Preference_PreferenceChanged; + /// } + /// + /// Preference.Set("active_user", "Poe"); + /// + /// Preference.GetEventContext("active_user").TryGetTarget(out context); + /// if (context != null) + /// { + /// context.Changed -= Preference_PreferenceChanged; + /// } + /// + /// + public event EventHandler Changed + { + add + { + if (_changed == null) + { + AllowChangeNotifications(_key); + } + + _changed += value; + } + + remove + { + _changed -= value; + if (_changed == null) + { + DisallowChangeNotifications(_key); + s_eventMap.Remove(_key); + } + } + } + + private event EventHandler _changed; + + internal void FireEvent() + { + _changed?.Invoke(null, new PreferenceChangedEventArgs() { Key = _key }); + } + } + + } + + internal static class PreferenceErrorFactory + { + internal enum PreferenceError + { + None = ErrorCode.None, + OutOfMemory = ErrorCode.OutOfMemory, + InvalidParameter = ErrorCode.InvalidParameter, + KeyNotAvailable = ErrorCode.KeyNotAvailable, + IoError = ErrorCode.IoError + } + + static internal Exception GetException(int error) + { + if ((PreferenceError)error == PreferenceError.OutOfMemory) + { + return new OutOfMemoryException("Out of memory"); + } + else if ((PreferenceError)error == PreferenceError.InvalidParameter) + { + return new ArgumentException("Invalid parameter"); + } + else if ((PreferenceError)error == PreferenceError.KeyNotAvailable) + { + return new KeyNotFoundException("Key does not exist in the bundle"); + } + else if ((PreferenceError)error == PreferenceError.IoError) + { + return new System.IO.IOException("I/O Error"); + } + else + { + return new ArgumentException("Unknown error"); + } + } + } +} diff --git a/Tizen.Applications/Tizen.Applications/PreferenceChangedEventArgs.cs b/Tizen.Applications/Tizen.Applications/PreferenceChangedEventArgs.cs new file mode 100644 index 0000000..f01689c --- /dev/null +++ b/Tizen.Applications/Tizen.Applications/PreferenceChangedEventArgs.cs @@ -0,0 +1,23 @@ +// Copyright 2016 by Samsung Electronics, Inc., +// +// This software is the confidential and proprietary information +// of Samsung Electronics, Inc. ("Confidential Information"). You +// shall not disclose such Confidential Information and shall use +// it only in accordance with the terms of the license agreement +// you entered into with Samsung. + +using System; + +namespace Tizen.Applications +{ + /// + /// This class is an event arguments of the PreferenceChanged events. + /// + public class PreferenceChangedEventArgs : EventArgs + { + /// + /// The key of the preference whose value is changed. + /// + public string Key { get; internal set; } + } +}