From 3d7fc925f761df8ad861aa4e91af5e7862e0acc4 Mon Sep 17 00:00:00 2001 From: "yons.kim" Date: Wed, 20 Apr 2016 17:44:22 +0900 Subject: [PATCH] [AppControl] Adds doxygen comments for AppControl Change-Id: I8ede9f51623dbd1fa8d6d424eebc2739c7ed777f --- .../Tizen.Applications/AppControl.cs | 320 ++++++++++++++++++--- .../Tizen.Applications/AppControlLaunchMode.cs | 6 +- .../Tizen.Applications/AppControlReplyCallback.cs | 2 +- .../Tizen.Applications/ReceivedAppControl.cs | 71 ++++- 4 files changed, 356 insertions(+), 43 deletions(-) diff --git a/Tizen.Applications/Tizen.Applications/AppControl.cs b/Tizen.Applications/Tizen.Applications/AppControl.cs index 44b3268..8783a70 100755 --- a/Tizen.Applications/Tizen.Applications/AppControl.cs +++ b/Tizen.Applications/Tizen.Applications/AppControl.cs @@ -16,6 +16,22 @@ namespace Tizen.Applications /// /// Represents the control message to exchange between applications. /// + /// + /// + /// public class AppControlExample : UIApplication + /// { + /// /// ... + /// protected override void OnAppControlReceived(AppControlReceivedEventArgs e) + /// { + /// AppControl appControl = new AppControl(); + /// appControl.ApplicationId = "org.tizen.calculator"; + /// AppControl.SendLaunchRequest(appControl, (launchRequest, replyRequest, result) => { + /// // ... + /// }); + /// } + /// } + /// + /// public class AppControl { private const string LogTag = "Tizen.Applications"; @@ -36,6 +52,7 @@ namespace Tizen.Applications /// /// Initializes the instance of the AppControl class. /// + /// Thrown when failed to create AppControl handle. public AppControl() { Interop.AppControl.ErrorCode err = Interop.AppControl.Create(out _handle); @@ -57,6 +74,19 @@ namespace Tizen.Applications /// /// Gets and sets the operation to be performed. /// + /// + /// The operation is the mandatory information for the launch request. If the operation is not specified, + /// AppControlOperations.Default is used for the launch request. If the operation is AppControlOperations.Default, + /// the package information is mandatory to explicitly launch the application. + /// (if the operation is null for setter, it clears the previous value.) + /// + /// + /// + /// AppControl appControl = new AppControl(); + /// appControl.Operation = AppControlOperations.Default; + /// Log.Debug(LogTag, "Operation: " + appControl.Operation); + /// + /// public string Operation { get @@ -88,6 +118,16 @@ namespace Tizen.Applications /// /// Gets and sets the explicit MIME type of the data. /// + /// + /// (if the mime is null for setter, it clears the previous value.) + /// + /// + /// + /// AppControl appControl = new AppControl(); + /// appControl.Mime = "image/jpg"; + /// Log.Debug(LogTag, "Mime: " + appControl.Mime); + /// + /// public string Mime { get @@ -119,6 +159,31 @@ namespace Tizen.Applications /// /// Gets and sets the URI of the data. /// + /// + /// Since Tizen 2.4, if the parameter 'uri' is started with 'file://' and + /// it is a regular file in this application's data path which can be obtained + /// by property DataPath in ApplicationInfo class, + /// it will be shared to the callee application. + /// Framework will grant a temporary permission to the callee application for this file and + /// revoke it when the callee application is terminated. + /// The callee application can just read it. + /// (if the uri is null for setter, it clears the previous value.) + /// + /// + /// + /// public class AppControlExample : UIApplication + /// { + /// ... + /// protected override void OnAppControlReceived(AppControlReceivedEventArgs e) + /// { + /// ... + /// AppControl appControl = new AppControl(); + /// appContrl.Uri = this.ApplicationInfo.DataPath + "image.jpg"; + /// Log.Debug(LogTag, "Set Uri: " + appControl.Uri); + /// } + /// } + /// + /// public string Uri { get @@ -150,6 +215,9 @@ namespace Tizen.Applications /// /// Gets and sets the explicit category. /// + /// + /// (if the category is null for setter, it clears the previous value.) + /// public string Category { get @@ -181,6 +249,16 @@ namespace Tizen.Applications /// /// Gets and sets the application id to explicitly launch. /// + /// + /// (if the application id is null for setter, it clears the previous value.) + /// + /// + /// + /// AppControl appControl = new AppControl(); + /// appControl.ApplicationId = "org.tizen.calculator"; + /// Log.Debug(LogTag, "ApplicationId: " + appControl.ApplicationId); + /// + /// public string ApplicationId { get @@ -212,6 +290,21 @@ namespace Tizen.Applications /// /// Gets and sets the launch mode of the application. /// + /// + /// Although LaunchMode were set as AppControlLaunchMode.Group, + /// callee application would be launched as single mode + /// if the manifest file of callee application defined the launch mode as "single". + /// This property can just set the preference of caller application to launch an application. + /// Sub-applications which were launched as group mode always have own process. + /// Since Tizen 3.0, if launch mode not set in the caller app control, + /// this property returns AppControlLaunchMode.Single launch mode. + /// + /// + /// + /// AppControl appControl = new AppControl(); + /// appControl.LaunchMode = AppControlLaunchMode.Group; + /// + /// public AppControlLaunchMode LaunchMode { get @@ -237,6 +330,17 @@ namespace Tizen.Applications /// /// Gets the collection of the extra data. /// + /// Extra data for communication between AppControls. + /// + /// + /// + /// + /// + /// AppControl appControl = new AppControl(); + /// appControl.ExtraData.Add("key", "value"); + /// ... + /// + /// public ExtraDataCollection ExtraData { get @@ -252,7 +356,21 @@ namespace Tizen.Applications /// /// Retrieves all applications that can be launched to handle the given app_control request. /// - /// + /// The AppControl + /// ApplicationIds + /// Thrown when failed because of invalid parameter + /// + /// + /// IEnumerable applicationIds = AppControl.GetMatchedApplicationIds(control); + /// if (applicationIds != null) + /// { + /// foreach (string id in applicationIds) + /// { + /// // ... + /// } + /// } + /// + /// public static IEnumerable GetMatchedApplicationIds(AppControl control) { List ids = new List(); @@ -288,8 +406,29 @@ namespace Tizen.Applications /// /// Sends the launch request. /// - /// - /// + /// + /// The operation is mandatory information for the launch request. + /// If the operation is not specified, AppControlOperations.Default is used by default. + /// If the operation is AppControlOperations.Default, the application ID is mandatory to explicitly launch the application. \n + /// Since Tizen 2.4, the launch request of the service application over out of packages is restricted by the platform. + /// Also, implicit launch requests are NOT delivered to service applications since 2.4. + /// To launch a service application, an explicit launch request with application ID given by property ApplicationId MUST be sent. + /// + /// The AppControl + /// The callback function to be called when the reply is delivered + /// Thrown when failed because of a null arguament + /// Thrown when failed because of invalid operation + /// Thrown when failed because of timeout + /// http://tizen.org/privilege/appmanager.launch + /// + /// + /// AppControl appControl = new AppControl(); + /// appControl.ApplicationId = "org.tizen.calculator"; + /// AppControl.SendLaunchRequest(appControl, (launchRequest, replyRequest, result) => { + /// // ... + /// }); + /// + /// public static void SendLaunchRequest(AppControl launchRequest, AppControlReplyCallback replyAfterLaunching = null) { Interop.AppControl.ErrorCode err; @@ -348,7 +487,7 @@ namespace Tizen.Applications } /// - /// + /// Class for Extra Data /// public class ExtraDataCollection { @@ -360,10 +499,21 @@ namespace Tizen.Applications } /// - /// + /// Adds extra data. /// - /// - /// + /// + /// The function replaces any existing value for the given key. + /// + /// The name of the extra data + /// The value associated with the given key + /// Thrown when key or value is a zero-length string + /// Thrown when the application tries to use the same key with system-defined key + /// + /// + /// AppControl appControl = new AppControl(); + /// appControl.ExtraData.Add("myKey", "myValue"); + /// + /// public void Add(string key, string value) { Interop.AppControl.ErrorCode err = Interop.AppControl.AddExtraData(_handle, key, value); @@ -377,10 +527,22 @@ namespace Tizen.Applications } /// - /// + /// Adds extra data. /// - /// - /// + /// + /// The function replaces any existing value for the given key. + /// + /// The name of the extra data + /// The value associated with the given key + /// Thrown when key or value is a zero-length string + /// Thrown when the application tries to use the same key with system-defined key + /// + /// + /// AppControl appControl = new AppControl(); + /// string[] myValues = new string[] { "first", "second", "third" }; + /// appControl.ExtraData.Add("myKey", myValues); + /// + /// public void Add(string key, IEnumerable value) { string[] valueArray = value.ToArray(); @@ -395,11 +557,20 @@ namespace Tizen.Applications } /// - /// + /// Gets the extra data. /// - /// - /// - /// + /// Only string & IEnumerable + /// The name of extra data + /// The value associated with the given key + /// Thrown when the key is invalid parameter + /// Thrown when the key is not found + /// Thrown when the key is rejected + /// + /// + /// AppControl appControl = new AppControl(); + /// string myValue = appControl.ExtraData.Get("myKey"); + /// + /// public T Get(string key) { object ret = Get(key); @@ -407,10 +578,23 @@ namespace Tizen.Applications } /// - /// + /// Gets the extra data. /// - /// - /// + /// The name of extra data + /// The value associated with the given key + /// Thrown when the key is invalid parameter + /// Thrown when the key is not found + /// Thrown when the key is rejected + /// + /// + /// AppControl appControl = new AppControl(); + /// string myValue = appControl.ExtraData.Get("myKey") as string; + /// if (myValue != null) + /// { + /// // ... + /// } + /// + /// public object Get(string key) { if (IsCollection(key)) @@ -424,9 +608,23 @@ namespace Tizen.Applications } /// - /// + /// Gets all keys in extra data. /// - /// + /// The keys in the AppControl + /// Thrown when invalid parameter + /// + /// + /// AppControl appControl = new AppControl(); + /// IEnumerable keys = appControl.GetKeys(); + /// if (keys != null) + /// { + /// foreach (string key in keys) + /// { + /// // ... + /// } + /// } + /// + /// public IEnumerable GetKeys() { List keys = new List(); @@ -460,11 +658,25 @@ namespace Tizen.Applications } /// - /// + /// Tries getting the extra data. /// - /// - /// - /// + /// The name of extra data + /// The value associated with the given key + /// The result whether getting the value is done + /// Thrown when the key is invalid parameter + /// Thrown when the key is not found + /// Thrown when the key is rejected + /// + /// + /// AppControl appControl = new AppControl(); + /// string myValue = string.Empty; + /// bool result = appControl.ExtraData.TryGet("myKey", out myValue); + /// if (result != null) + /// { + /// // ... + /// } + /// + /// public bool TryGet(string key, out string value) { Interop.AppControl.GetExtraData(_handle, key, out value); @@ -480,11 +692,28 @@ namespace Tizen.Applications } /// - /// + /// Tries getting the extra data. /// - /// - /// - /// + /// The name of extra data + /// The value associated with the given key + /// The result whether getting the value is done + /// Thrown when the key is invalid parameter + /// Thrown when the key is not found + /// Thrown when the key is rejected + /// + /// + /// AppControl appControl = new AppControl(); + /// IEnumerable myValue = null; + /// bool result = appControl.ExtraData.TryGet("myKey", out myValue); + /// if (result) + /// { + /// foreach (string value in myValue) + /// { + /// // ... + /// } + /// } + /// + /// public bool TryGet(string key, out IEnumerable value) { IntPtr valuePtr = IntPtr.Zero; @@ -511,9 +740,18 @@ namespace Tizen.Applications } /// - /// + /// Removes the extra data. /// - /// + /// The name of the extra data + /// Thrown when the key is a zero-length string + /// Thrown when the key is not found + /// Thrown when the key is rejected + /// + /// + /// AppControl appControl = new AppControl(); + /// appControl.ExtraData.Remove("myKey"); + /// + /// public void Remove(string key) { Interop.AppControl.ErrorCode err = Interop.AppControl.RemoveExtraData(_handle, key); @@ -529,19 +767,33 @@ namespace Tizen.Applications } /// - /// + /// Counts keys in the extra data. /// - /// + /// The number of counting keys + /// Thrown when invalid parameter + /// + /// + /// AppControl appControl = new AppControl(); + /// int numberOfKeys = appControl.ExtraData.Count(); + /// + /// public int Count() { return GetKeys().Count(); } /// - /// + /// Checks whether the extra data associated with the given key is of collection data type. /// - /// - /// + /// The name of the extra data + /// If true the extra data is of array data type, otherwise false + /// Thrown when the key is a zero-length string + /// + /// + /// AppControl appControl = new AppControl(); + /// bool result = appControl.ExtraData.IsCollection("myKey"); + /// + /// public bool IsCollection(string key) { bool isArray = false; diff --git a/Tizen.Applications/Tizen.Applications/AppControlLaunchMode.cs b/Tizen.Applications/Tizen.Applications/AppControlLaunchMode.cs index 7f4f5d0..ae24208 100755 --- a/Tizen.Applications/Tizen.Applications/AppControlLaunchMode.cs +++ b/Tizen.Applications/Tizen.Applications/AppControlLaunchMode.cs @@ -9,17 +9,17 @@ namespace Tizen.Applications { /// - /// + /// Enumeration for App Control Launch Mode. /// public enum AppControlLaunchMode { /// - /// + /// Prefer to launch an application as single mode /// Single = 0, /// - /// + /// Prefer to launch an application as group mode /// Group, } diff --git a/Tizen.Applications/Tizen.Applications/AppControlReplyCallback.cs b/Tizen.Applications/Tizen.Applications/AppControlReplyCallback.cs index 40e104a..3805acd 100755 --- a/Tizen.Applications/Tizen.Applications/AppControlReplyCallback.cs +++ b/Tizen.Applications/Tizen.Applications/AppControlReplyCallback.cs @@ -1,4 +1,4 @@ -// Copyright 2016 by Samsung Electronics, Inc., +// Copyright 2016 by Samsung Electronics, Inc., // // This software is the confidential and proprietary information // of Samsung Electronics, Inc. ("Confidential Information"). You diff --git a/Tizen.Applications/Tizen.Applications/ReceivedAppControl.cs b/Tizen.Applications/Tizen.Applications/ReceivedAppControl.cs index e1b18ac..2d83114 100755 --- a/Tizen.Applications/Tizen.Applications/ReceivedAppControl.cs +++ b/Tizen.Applications/Tizen.Applications/ReceivedAppControl.cs @@ -13,6 +13,28 @@ namespace Tizen.Applications /// /// Represents the received AppControl. /// + /// + /// + /// public class ReceivedAppControlExample : UIApplication + /// { + /// // ... + /// protected override void OnAppControlReceived(AppControlReceivedEventArgs e) + /// { + /// ReceivedAppControl control = e.ReceivedAppControl; + /// if (control.Operation == AppControlOperations.Pick) + /// { + /// Log.Debug(LogTag, "Received AppControl is Pick"); + /// } + /// if (control.IsReplyRequest) + /// { + /// AppControl replyRequest = new AppControl(); + /// replyRequest.ExtraData.Add("myKey", "I'm replying"); + /// control.ReplyToLaunchRequest(replyRequest, AppControlReplyResult.Succeeded); + /// } + /// } + /// } + /// + /// public class ReceivedAppControl : AppControl { private const string LogTag = "Tizen.Applications"; @@ -22,8 +44,20 @@ namespace Tizen.Applications } /// - /// + /// Gets the application ID of the caller from the launch request. /// + /// + /// The application ID of the caller + /// + /// + /// + /// protected override void OnAppControlReceived(AppControlReceivedEventArgs e) + /// { + /// ReceivedAppControl control = e.ReceivedAppControl; + /// string caller = control.CallerApplicationId; + /// } + /// + /// public string CallerApplicationId { get @@ -39,8 +73,20 @@ namespace Tizen.Applications } /// - /// + /// Checks whether the caller is requesting a reply from the launch request. /// + /// + /// If true this ReceivedAppControl is requested by the caller, otherwise false + /// + /// + /// + /// protected override void OnAppControlReceived(AppControlReceivedEventArgs e) + /// { + /// ReceivedAppControl control = e.ReceivedAppControl; + /// bool isReply = control.IsReplyRequest; + /// } + /// + /// public bool IsReplyRequest { get @@ -56,10 +102,25 @@ namespace Tizen.Applications } /// - /// + /// Replies to the launch request sent by the caller. + /// If the caller application sent the launch request to receive the result, the callee application can return the result back to the caller. /// - /// - /// + /// The AppControl in which the results of the callee are contained + /// The result code of the launch request + /// + /// + /// protected override void OnAppControlReceived(AppControlReceivedEventArgs e) + /// { + /// ReceivedAppControl control = e.ReceivedAppControl; + /// if (control.IsReplyRequest) + /// { + /// AppControl replyRequest = new AppControl(); + /// replyRequest.ExtraData.Add("myKey", "I'm replying"); + /// control.ReplyToLaunchRequest(replyRequest, AppControlReplyResult.Succeeded); + /// } + /// } + /// + /// public void ReplyToLaunchRequest(AppControl replyRequest, AppControlReplyResult result) { Interop.AppControl.ErrorCode err = Interop.AppControl.ReplyToLaunchRequest(replyRequest._handle, this._handle, (int)result); -- 2.7.4