Merge "[NUI] Fix build warnings: Fix xml comments"
[platform/core/csapi/tizenfx.git] / src / Tizen.Applications.Common / Tizen.Applications / AppControl.cs
1 /*
2  * Copyright (c) 2016 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 using System;
18 using System.Collections.Generic;
19 using System.Linq;
20 using System.Runtime.InteropServices;
21
22 namespace Tizen.Applications
23 {
24     /// <summary>
25     /// Represents the control message to exchange between applications.
26     /// </summary>
27     /// <example>
28     /// <code>
29     /// public class AppControlExample : UIApplication
30     /// {
31     ///     /// ...
32     ///     protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
33     ///     {
34     ///         AppControl appControl = new AppControl();
35     ///         appControl.ApplicationId = "org.tizen.calculator";
36     ///         AppControl.SendLaunchRequest(appControl, (launchRequest, replyRequest, result) => {
37     ///             // ...
38     ///         });
39     ///     }
40     /// }
41     /// </code>
42     /// </example>
43     public class AppControl
44     {
45         private const string LogTag = "Tizen.Applications";
46
47         private static Dictionary<int, Interop.AppControl.ReplyCallback> s_replyNativeCallbackMaps = new Dictionary<int, Interop.AppControl.ReplyCallback>();
48         private static int s_replyNativeCallbackId = 0;
49
50         private readonly SafeAppControlHandle _handle;
51
52         private string _operation = null;
53         private string _mime = null;
54         private string _uri = null;
55         private string _category = null;
56         private string _applicationId = null;
57         private ExtraDataCollection _extraData = null;
58
59         /// <summary>
60         /// Initializes the instance of the AppControl class.
61         /// </summary>
62         /// <exception cref="InvalidOperationException">Thrown when failed to create the AppControl handle.</exception>
63         public AppControl()
64         {
65             Interop.AppControl.ErrorCode err = Interop.AppControl.Create(out _handle);
66             if (err != Interop.AppControl.ErrorCode.None)
67             {
68                 throw new InvalidOperationException("Failed to create the appcontrol handle. Err = " + err);
69             }
70         }
71
72         /// <summary>
73         /// Initializes the instance of the AppControl class with a parameter.
74         /// </summary>
75         /// <param name="enableAppStartedResultEvent">The flag value to receive an additional launch result event on the launch request.</param>
76         /// <exception cref="InvalidOperationException">Thrown when failed to create the AppControl handle.</exception>
77         public AppControl(bool enableAppStartedResultEvent)
78         {
79             Interop.AppControl.ErrorCode err = Interop.AppControl.Create(out _handle);
80             if (err != Interop.AppControl.ErrorCode.None)
81             {
82                 throw new InvalidOperationException("Failed to create the appcontrol handle. Err = " + err);
83             }
84
85             if (enableAppStartedResultEvent)
86             {
87                 err = Interop.AppControl.EnableAppStartedResultEvent(_handle);
88                 if (err != Interop.AppControl.ErrorCode.None)
89                 {
90                     throw new InvalidOperationException("Failed to set EnableAppStartedResultEvent");
91                 }
92             }
93         }
94
95         /// <summary>
96         /// Initializes the instance of the AppControl class with the SafeAppControlHandle.
97         /// </summary>
98         /// <param name="handle"></param>
99         public AppControl(SafeAppControlHandle handle)
100         {
101             if (handle == null)
102             {
103                 throw new ArgumentNullException("handle");
104             }
105
106             Interop.AppControl.ErrorCode err = Interop.AppControl.DangerousClone(out _handle, handle.DangerousGetHandle());
107             if (err != Interop.AppControl.ErrorCode.None)
108             {
109                 throw new InvalidOperationException("Failed to clone the appcontrol handle. Err = " + err);
110             }
111         }
112
113         private AppControl(IntPtr handle)
114         {
115             Interop.AppControl.ErrorCode err = Interop.AppControl.DangerousClone(out _handle, handle);
116             if (err != Interop.AppControl.ErrorCode.None)
117             {
118                 throw new InvalidOperationException("Failed to clone the appcontrol handle. Err = " + err);
119             }
120         }
121
122         #region Public Properties
123
124         /// <summary>
125         /// Gets the SafeAppControlHandle instance.
126         /// </summary>
127         public SafeAppControlHandle SafeAppControlHandle
128         {
129             get
130             {
131                 return _handle;
132             }
133         }
134
135         /// <summary>
136         /// Gets and sets the operation to be performed.
137         /// </summary>
138         /// <value>
139         /// The operation is the mandatory information for the launch request. If the operation is not specified,
140         /// AppControlOperations.Default is used for the launch request. If the operation is AppControlOperations.Default,
141         /// the package information is mandatory to explicitly launch the application.
142         /// (if the operation is null for setter, it clears the previous value.)
143         /// </value>
144         /// <example>
145         /// <code>
146         /// AppControl appControl = new AppControl();
147         /// appControl.Operation = AppControlOperations.Default;
148         /// Log.Debug(LogTag, "Operation: " + appControl.Operation);
149         /// </code>
150         /// </example>
151         public string Operation
152         {
153             get
154             {
155                 if (String.IsNullOrEmpty(_operation))
156                 {
157                     Interop.AppControl.ErrorCode err = Interop.AppControl.GetOperation(_handle, out _operation);
158                     if (err != Interop.AppControl.ErrorCode.None)
159                     {
160                         Log.Warn(LogTag, "Failed to get the operation from the appcontrol. Err = " + err);
161                     }
162                 }
163                 return _operation;
164             }
165             set
166             {
167                 Interop.AppControl.ErrorCode err = Interop.AppControl.SetOperation(_handle, value);
168                 if (err == Interop.AppControl.ErrorCode.None)
169                 {
170                     _operation = value;
171                 }
172                 else
173                 {
174                     Log.Warn(LogTag, "Failed to set the operation to the appcontrol. Err = " + err);
175                 }
176             }
177         }
178
179         /// <summary>
180         /// Gets and sets the explicit MIME type of the data.
181         /// </summary>
182         /// <value>
183         /// (if the mime is null for setter, it clears the previous value.)
184         /// </value>
185         /// <example>
186         /// <code>
187         /// AppControl appControl = new AppControl();
188         /// appControl.Mime = "image/jpg";
189         /// Log.Debug(LogTag, "Mime: " + appControl.Mime);
190         /// </code>
191         /// </example>
192         public string Mime
193         {
194             get
195             {
196                 if (String.IsNullOrEmpty(_mime))
197                 {
198                     Interop.AppControl.ErrorCode err = Interop.AppControl.GetMime(_handle, out _mime);
199                     if (err != Interop.AppControl.ErrorCode.None)
200                     {
201                         Log.Warn(LogTag, "Failed to get the mime from the appcontrol. Err = " + err);
202                     }
203                 }
204                 return _mime;
205             }
206             set
207             {
208                 Interop.AppControl.ErrorCode err = Interop.AppControl.SetMime(_handle, value);
209                 if (err == Interop.AppControl.ErrorCode.None)
210                 {
211                     _mime = value;
212                 }
213                 else
214                 {
215                     Log.Warn(LogTag, "Failed to set the mime to the appcontrol. Err = " + err);
216                 }
217             }
218         }
219
220         /// <summary>
221         /// Gets and sets the URI of the data.
222         /// </summary>
223         /// <value>
224         /// Since Tizen 2.4, if the parameter 'uri' is started with 'file://' and
225         /// it is a regular file in this application's data path, which can be obtained
226         /// by property DataPath in ApplicationInfo class,
227         /// it will be shared to the callee application.
228         /// Framework will grant a temporary permission to the callee application for this file and
229         /// revoke it when the callee application is terminated.
230         /// The callee application can just read it.
231         /// (if the uri is null for setter, it clears the previous value.)
232         /// </value>
233         /// <example>
234         /// <code>
235         /// public class AppControlExample : UIApplication
236         /// {
237         ///     ...
238         ///     protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
239         ///     {
240         ///         ...
241         ///         AppControl appControl = new AppControl();
242         ///         appContrl.Uri = this.ApplicationInfo.DataPath + "image.jpg";
243         ///         Log.Debug(LogTag, "Set Uri: " + appControl.Uri);
244         ///     }
245         /// }
246         /// </code>
247         /// </example>
248         public string Uri
249         {
250             get
251             {
252                 if (String.IsNullOrEmpty(_uri))
253                 {
254                     Interop.AppControl.ErrorCode err = Interop.AppControl.GetUri(_handle, out _uri);
255                     if (err != Interop.AppControl.ErrorCode.None)
256                     {
257                         Log.Warn(LogTag, "Failed to get the uri from the appcontrol. Err = " + err);
258                     }
259                 }
260                 return _uri;
261             }
262             set
263             {
264                 Interop.AppControl.ErrorCode err = Interop.AppControl.SetUri(_handle, value);
265                 if (err == Interop.AppControl.ErrorCode.None)
266                 {
267                     _uri = value;
268                 }
269                 else
270                 {
271                     Log.Warn(LogTag, "Failed to set the uri to the appcontrol. Err = " + err);
272                 }
273             }
274         }
275
276         /// <summary>
277         /// Gets and sets the explicit category.
278         /// </summary>
279         /// <value>
280         /// (if the category is null for setter, it clears the previous value.)
281         /// </value>
282         public string Category
283         {
284             get
285             {
286                 if (String.IsNullOrEmpty(_category))
287                 {
288                     Interop.AppControl.ErrorCode err = Interop.AppControl.GetCategory(_handle, out _category);
289                     if (err != Interop.AppControl.ErrorCode.None)
290                     {
291                         Log.Warn(LogTag, "Failed to get the category from the appcontrol. Err = " + err);
292                     }
293                 }
294                 return _category;
295             }
296             set
297             {
298                 Interop.AppControl.ErrorCode err = Interop.AppControl.SetCategory(_handle, value);
299                 if (err == Interop.AppControl.ErrorCode.None)
300                 {
301                     _category = value;
302                 }
303                 else
304                 {
305                     Log.Warn(LogTag, "Failed to set the category to the appcontrol. Err = " + err);
306                 }
307             }
308         }
309
310         /// <summary>
311         /// Gets and sets the application ID to explicitly launch.
312         /// </summary>
313         /// <value>
314         /// (if the application ID is null for setter, it clears the previous value.)
315         /// </value>
316         /// <example>
317         /// <code>
318         /// AppControl appControl = new AppControl();
319         /// appControl.ApplicationId = "org.tizen.calculator";
320         /// Log.Debug(LogTag, "ApplicationId: " + appControl.ApplicationId);
321         /// </code>
322         /// </example>
323         public string ApplicationId
324         {
325             get
326             {
327                 if (String.IsNullOrEmpty(_applicationId))
328                 {
329                     Interop.AppControl.ErrorCode err = Interop.AppControl.GetAppId(_handle, out _applicationId);
330                     if (err != Interop.AppControl.ErrorCode.None)
331                     {
332                         Log.Warn(LogTag, "Failed to get the application id from the AppControl. Err = " + err);
333                     }
334                 }
335                 return _applicationId;
336             }
337             set
338             {
339                 Interop.AppControl.ErrorCode err = Interop.AppControl.SetAppId(_handle, value);
340                 if (err == Interop.AppControl.ErrorCode.None)
341                 {
342                     _applicationId = value;
343                 }
344                 else
345                 {
346                     Log.Warn(LogTag, "Failed to set the application id to the AppControl. Err = " + err);
347                 }
348             }
349         }
350
351         /// <summary>
352         /// Gets and sets the launch mode of the application.
353         /// </summary>
354         /// <value>
355         /// Although, LaunchMode were set as AppControlLaunchMode.Group, the
356         /// callee application would be launched as a single mode
357         /// if the manifest file of callee application defined the launch mode as "single".
358         /// This property can just set the preference of the caller application to launch an application.
359         /// Sub-applications, which were launched as a group mode always have own process.
360         /// Since Tizen 3.0, if launch mode is not set in the caller application control,
361         /// this property returns the AppControlLaunchMode.Single launch mode.
362         /// </value>
363         /// <example>
364         /// <code>
365         /// AppControl appControl = new AppControl();
366         /// appControl.LaunchMode = AppControlLaunchMode.Group;
367         /// </code>
368         /// </example>
369         public AppControlLaunchMode LaunchMode
370         {
371             get
372             {
373                 int value = 0;
374                 Interop.AppControl.ErrorCode err = Interop.AppControl.GetLaunchMode(_handle, out value);
375                 if (err != Interop.AppControl.ErrorCode.None)
376                 {
377                     Log.Warn(LogTag, "Failed to get the LaunchMode from the AppControl. Err = " + err);
378                 }
379                 return (AppControlLaunchMode)value;
380             }
381             set
382             {
383                 Interop.AppControl.ErrorCode err = Interop.AppControl.SetLaunchMode(_handle, (int)value);
384                 if (err != Interop.AppControl.ErrorCode.None)
385                 {
386                     Log.Warn(LogTag, "Failed to set the LaunchMode to the AppControl. Err = " + err);
387                 }
388             }
389         }
390
391         /// <summary>
392         /// Gets the collection of the extra data.
393         /// </summary>
394         /// <value>
395         /// Extra data for communication between AppControls.
396         /// </value>
397         /// <example>
398         /// <code>
399         /// AppControl appControl = new AppControl();
400         /// appControl.ExtraData.Add("key", "value");
401         /// ...
402         /// </code>
403         /// </example>
404         public ExtraDataCollection ExtraData
405         {
406             get
407             {
408                 if (_extraData == null)
409                     _extraData = new ExtraDataCollection(_handle);
410                 return _extraData;
411             }
412         }
413
414         #endregion // Public Properties
415
416         /// <summary>
417         /// Retrieves all applications that can be launched to handle the given app_control request.
418         /// </summary>
419         /// <param name="control">The AppControl.</param>
420         /// <returns>ApplicationIds.</returns>
421         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid parameter.</exception>
422         /// <example>
423         /// <code>
424         /// IEnumerable<string> applicationIds = AppControl.GetMatchedApplicationIds(control);
425         /// if (applicationIds != null)
426         /// {
427         ///     foreach (string id in applicationIds)
428         ///     {
429         ///         // ...
430         ///     }
431         /// }
432         /// </code>
433         /// </example>
434         public static IEnumerable<string> GetMatchedApplicationIds(AppControl control)
435         {
436             if (control == null)
437             {
438                 throw new ArgumentNullException("control");
439             }
440
441             List<string> ids = new List<string>();
442             Interop.AppControl.AppMatchedCallback callback = (handle, applicationId, userData) =>
443             {
444                 if (applicationId == null)
445                 {
446                         return false;
447                 }
448
449                 ids.Add(applicationId);
450                 return true;
451             };
452
453             Interop.AppControl.ErrorCode err = Interop.AppControl.ForeachAppMatched(control._handle, callback, IntPtr.Zero);
454             if (err != Interop.AppControl.ErrorCode.None)
455             {
456                     throw new InvalidOperationException("Failed to get matched application ids. err = " + err);
457             }
458
459             return ids;
460         }
461
462         /// <summary>
463         /// Sends the launch request.
464         /// </summary>
465         /// <remarks>
466         /// The operation is mandatory information for the launch request.
467         /// If the operation is not specified, AppControlOperations.Default is used by default.
468         /// If the operation is AppControlOperations.Default, the application ID is mandatory to explicitly launch the application. \n
469         /// Since Tizen 2.4, the launch request of the service application over out of packages is restricted by the platform.
470         /// Also, implicit launch requests are NOT delivered to service applications since 2.4.
471         /// To launch a service application, an explicit launch request with the application ID given by property ApplicationId MUST be sent.
472         /// </remarks>
473         /// <param name="launchRequest">The AppControl.</param>
474         /// <exception cref="ArgumentNullException">Thrown when failed because of a null argument.</exception>
475         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
476         /// <exception cref="TimeoutException">Thrown when failed because of timeout.</exception>
477         /// <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
478         /// <example>
479         /// <code>
480         /// AppControl appControl = new AppControl();
481         /// appControl.ApplicationId = "org.tizen.calculator";
482         /// AppControl.SendLaunchRequest(appControl);
483         /// </code>
484         /// </example>
485         public static void SendLaunchRequest(AppControl launchRequest)
486         {
487             SendLaunchRequest(launchRequest, null);
488         }
489
490         /// <summary>
491         /// Sends the launch request.
492         /// </summary>
493         /// <remarks>
494         /// The operation is mandatory information for the launch request.
495         /// If the operation is not specified, AppControlOperations.Default is used by default.
496         /// If the operation is AppControlOperations.Default, the application ID is mandatory to explicitly launch the application. \n
497         /// Since Tizen 2.4, the launch request of the service application over out of packages is restricted by the platform.
498         /// Also, implicit launch requests are NOT delivered to service applications since 2.4.
499         /// To launch a service application, an explicit launch request with the application ID given by property ApplicationId MUST be sent.
500         /// </remarks>
501         /// <param name="launchRequest">The AppControl.</param>
502         /// <param name="replyAfterLaunching">The callback function to be called when the reply is delivered.</param>
503         /// <exception cref="ArgumentException">Thrown when failed because of the argument is invalid.</exception>
504         /// <exception cref="Exceptions.AppNotFoundException">Thrown when the application to run is not found.</exception>
505         /// <exception cref="Exceptions.LaunchFailedException">Thrown when the request failed to launch the application.</exception>
506         /// <exception cref="Exceptions.LaunchRejectedException">Thrown when the launch request is rejected.</exception>
507         /// <exception cref="Exceptions.OutOfMemoryException">Thrown when the memory is insufficient.</exception>
508         /// <exception cref="Exceptions.PermissionDeniedException">Thrown when the permission is denied.</exception>
509         /// <exception cref="TimeoutException">Thrown when failed because of timeout.</exception>
510         /// <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
511         /// <example>
512         /// <code>
513         /// AppControl appControl = new AppControl();
514         /// appControl.ApplicationId = "org.tizen.calculator";
515         /// AppControl.SendLaunchRequest(appControl, (launchRequest, replyRequest, result) => {
516         ///     // ...
517         /// });
518         /// </code>
519         /// </example>
520         public static void SendLaunchRequest(AppControl launchRequest, AppControlReplyCallback replyAfterLaunching)
521         {
522             if (launchRequest == null)
523             {
524                 throw new ArgumentNullException("launchRequest");
525             }
526
527             Interop.AppControl.ErrorCode err;
528
529             if (replyAfterLaunching != null)
530             {
531                 int id = 0;
532                 lock (s_replyNativeCallbackMaps)
533                 {
534                     id = s_replyNativeCallbackId++;
535                     s_replyNativeCallbackMaps[id] = (launchRequestHandle, replyRequestHandle, result, userData) =>
536                     {
537                         if (replyAfterLaunching != null)
538                         {
539                             Log.Debug(LogTag, "Reply Callback is launched");
540                             replyAfterLaunching(new AppControl(launchRequestHandle), new AppControl(replyRequestHandle), (AppControlReplyResult)result);
541                             if (result != Interop.AppControl.AppStartedStatus)
542                             {
543                                 lock (s_replyNativeCallbackMaps)
544                                 {
545                                     s_replyNativeCallbackMaps.Remove(id);
546                                 }
547                             }
548                         }
549                     };
550                 }
551                 err = Interop.AppControl.SendLaunchRequest(launchRequest._handle, s_replyNativeCallbackMaps[id], IntPtr.Zero);
552             }
553             else
554             {
555                 err = Interop.AppControl.SendLaunchRequest(launchRequest._handle, null, IntPtr.Zero);
556             }
557
558             if (err != Interop.AppControl.ErrorCode.None)
559             {
560                 switch (err)
561                 {
562                     case Interop.AppControl.ErrorCode.InvalidParameter:
563                         throw new ArgumentException("Invalid Arguments");
564                     case Interop.AppControl.ErrorCode.TimedOut:
565                         throw new TimeoutException("Timed out");
566                     case Interop.AppControl.ErrorCode.OutOfMemory:
567                         throw new Exceptions.OutOfMemoryException("Out-of-memory");
568                     case Interop.AppControl.ErrorCode.AppNotFound:
569                         throw new Exceptions.AppNotFoundException("App not found");
570                     case Interop.AppControl.ErrorCode.LaunchRejected:
571                         throw new Exceptions.LaunchRejectedException("Launch rejected");
572                     case Interop.AppControl.ErrorCode.LaunchFailed:
573                         throw new Exceptions.LaunchFailedException("Launch failed");
574                     case Interop.AppControl.ErrorCode.PermissionDenied:
575                         throw new Exceptions.PermissionDeniedException("Permission denied");
576
577                     default:
578                         throw new Exceptions.LaunchRejectedException("Launch rejected");
579                 }
580             }
581         }
582
583         /// <summary>
584         /// Sends the terminate request to the application that is launched by AppControl.
585         /// </summary>
586         /// <remarks>
587         /// You are not allowed to terminate other general applications using this API.
588         /// This API can be used to terminate sub-applications, which were launched as a group mode by the caller application.
589         /// Once the callee application is being terminated by this API,
590         /// other applications, which were launched by the callee application as a group mode will be terminated as well.
591         /// </remarks>
592         /// <param name="terminateRequest">The AppControl.</param>
593         /// <exception cref="ArgumentException">Thrown when failed because of the argument is invalid.</exception>
594         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
595         /// <exception cref="TimeoutException">Thrown when failed because of timeout.</exception>
596         /// <example>
597         /// <code>
598         /// AppControl terminateRequest = new AppControl();
599         /// terminateRequest.ApplicationId = "org.tizen.calculator";
600         /// AppControl.SendTerminateRequest(terminateRequest);
601         /// </code>
602         /// </example>
603         public static void SendTerminateRequest(AppControl terminateRequest)
604         {
605             if (terminateRequest == null)
606             {
607                 throw new ArgumentNullException("terminateRequest");
608             }
609             Interop.AppControl.ErrorCode err;
610
611             err = Interop.AppControl.SendTerminateRequest(terminateRequest._handle);
612
613             if (err != Interop.AppControl.ErrorCode.None)
614             {
615                 switch (err)
616                 {
617                     case Interop.AppControl.ErrorCode.InvalidParameter:
618                         throw new ArgumentException("Invalid Arguments");
619                     case Interop.AppControl.ErrorCode.TimedOut:
620                         throw new TimeoutException("Timed out");
621                     default:
622                         throw new InvalidOperationException("Error = " + err);
623                 }
624             }
625         }
626
627         /// <summary>
628         /// Class for extra data.
629         /// </summary>
630         public class ExtraDataCollection
631         {
632             private readonly SafeAppControlHandle _handle;
633
634             internal ExtraDataCollection(SafeAppControlHandle handle)
635             {
636                 _handle = handle;
637             }
638
639             /// <summary>
640             /// Adds extra data.
641             /// </summary>
642             /// <remarks>
643             /// The function replaces any existing value for the given key.
644             /// </remarks>
645             /// <param name="key">The name of the extra data.</param>
646             /// <param name="value">The value associated with the given key.</param>
647             /// <exception cref="ArgumentNullException">Thrown when a key or a value is a zero-length string.</exception>
648             /// <exception cref="ArgumentException">Thrown when the application tries to use the same key with the system-defined key.</exception>
649             /// <example>
650             /// <code>
651             /// AppControl appControl = new AppControl();
652             /// appControl.ExtraData.Add("myKey", "myValue");
653             /// </code>
654             /// </example>
655             public void Add(string key, string value)
656             {
657                 if (string.IsNullOrEmpty(key))
658                 {
659                     throw new ArgumentNullException("key");
660                 }
661                 if (string.IsNullOrEmpty(value))
662                 {
663                     throw new ArgumentNullException("value");
664                 }
665                 Interop.AppControl.ErrorCode err = Interop.AppControl.AddExtraData(_handle, key, value);
666                 if (err != Interop.AppControl.ErrorCode.None)
667                 {
668                     switch (err)
669                     {
670                         case Interop.AppControl.ErrorCode.InvalidParameter:
671                             throw new ArgumentException("Invalid parameter: key or value is a zero-length string");
672                         case Interop.AppControl.ErrorCode.KeyRejected:
673                             throw new ArgumentException("Key is rejected: the key is system-defined key.");
674                         default:
675                             throw new InvalidOperationException("Error = " + err);
676                     }
677                 }
678             }
679
680             /// <summary>
681             /// Adds extra data.
682             /// </summary>
683             /// <remarks>
684             /// The function replaces any existing value for the given key.
685             /// </remarks>
686             /// <param name="key">The name of the extra data.</param>
687             /// <param name="value">The value associated with the given key.</param>
688             /// <exception cref="ArgumentNullException">Thrown when key or value is a zero-length string.</exception>
689             /// <exception cref="ArgumentException">Thrown when the application tries to use the same key with the system-defined key.</exception>
690             /// <example>
691             /// <code>
692             /// AppControl appControl = new AppControl();
693             /// string[] myValues = new string[] { "first", "second", "third" };
694             /// appControl.ExtraData.Add("myKey", myValues);
695             /// </code>
696             /// </example>
697             public void Add(string key, IEnumerable<string> value)
698             {
699                 if (string.IsNullOrEmpty(key))
700                 {
701                     throw new ArgumentNullException("key");
702                 }
703                 if (value == null)
704                 {
705                     throw new ArgumentNullException("value");
706                 }
707                 string[] valueArray = value.ToArray();
708                 Interop.AppControl.ErrorCode err = Interop.AppControl.AddExtraDataArray(_handle, key, valueArray, valueArray.Length);
709                 if (err != Interop.AppControl.ErrorCode.None)
710                 {
711                     switch (err)
712                     {
713                         case Interop.AppControl.ErrorCode.InvalidParameter:
714                             throw new ArgumentException("Invalid parameter: key or value is a zero-length string");
715                         case Interop.AppControl.ErrorCode.KeyRejected:
716                             throw new ArgumentException("Key is rejected: the key is system-defined key.");
717                         default:
718                             throw new InvalidOperationException("Error = " + err);
719                     }
720                 }
721             }
722
723             /// <summary>
724             /// Gets the extra data.
725             /// </summary>
726             /// <typeparam name="T">Only string and IEnumerable&lt;string&gt;</typeparam>
727             /// <param name="key">The name of extra data.</param>
728             /// <returns>The value associated with the given key.</returns>
729             /// <exception cref="ArgumentNullException">Thrown when the key is an invalid parameter.</exception>
730             /// <exception cref="KeyNotFoundException">Thrown when the key is not found.</exception>
731             /// <exception cref="ArgumentException">Thrown when the key is rejected.</exception>
732             /// <example>
733             /// <code>
734             /// AppControl appControl = new AppControl();
735             /// string myValue = appControl.ExtraData.Get<string>("myKey");
736             /// </code>
737             /// </example>
738             public T Get<T>(string key)
739             {
740                 object ret = Get(key);
741                 return (T)ret;
742             }
743
744             /// <summary>
745             /// Gets the extra data.
746             /// </summary>
747             /// <param name="key">The name of extra data.</param>
748             /// <returns>The value associated with the given key.</returns>
749             /// <exception cref="ArgumentNullException">Thrown when the key is an invalid parameter.</exception>
750             /// <exception cref="KeyNotFoundException">Thrown when the key is not found.</exception>
751             /// <exception cref="ArgumentException">Thrown when the key is rejected.</exception>
752             /// <example>
753             /// <code>
754             /// AppControl appControl = new AppControl();
755             /// string myValue = appControl.ExtraData.Get("myKey") as string;
756             /// if (myValue != null)
757             /// {
758             ///     // ...
759             /// }
760             /// </code>
761             /// </example>
762             public object Get(string key)
763             {
764                 if (IsCollection(key))
765                 {
766                     return GetDataCollection(key);
767                 }
768                 else
769                 {
770                     return GetData(key);
771                 }
772             }
773
774             /// <summary>
775             /// Gets all keys in extra data.
776             /// </summary>
777             /// <returns>The keys in the AppControl.</returns>
778             /// <exception cref="InvalidOperationException">Thrown when the key is an invalid parameter.</exception>
779             /// <example>
780             /// <code>
781             /// AppControl appControl = new AppControl();
782             /// IEnumerable<string> keys = appControl.GetKeys();
783             /// if (keys != null)
784             /// {
785             ///     foreach (string key in keys)
786             ///     {
787             ///         // ...
788             ///     }
789             /// }
790             /// </code>
791             /// </example>
792             public IEnumerable<string> GetKeys()
793             {
794                 List<string> keys = new List<string>();
795                 Interop.AppControl.ExtraDataCallback callback = (handle, key, userData) =>
796                 {
797                     if (key == null)
798                     {
799                         return false;
800                     }
801
802                     keys.Add(key);
803                     return true;
804                 };
805
806                 Interop.AppControl.ErrorCode err = Interop.AppControl.ForeachExtraData(_handle, callback, IntPtr.Zero);
807                 if (err != Interop.AppControl.ErrorCode.None)
808                 {
809                     throw new InvalidOperationException("Failed to get keys. err = " + err);
810                 }
811
812                 return keys;
813             }
814
815             /// <summary>
816             /// Tries getting the extra data.
817             /// </summary>
818             /// <param name="key">The name of extra data.</param>
819             /// <param name="value">The value associated with the given key.</param>
820             /// <returns>The result whether getting the value is done.</returns>
821             /// <exception cref="ArgumentNullException">Thrown when the key is an invalid parameter.</exception>
822             /// <exception cref="KeyNotFoundException">Thrown when the key is not found.</exception>
823             /// <exception cref="ArgumentException">Thrown when the key is rejected.</exception>
824             /// <example>
825             /// <code>
826             /// AppControl appControl = new AppControl();
827             /// string myValue = string.Empty;
828             /// bool result = appControl.ExtraData.TryGet("myKey", out myValue);
829             /// if (result != null)
830             /// {
831             ///     // ...
832             /// }
833             /// </code>
834             /// </example>
835             public bool TryGet(string key, out string value)
836             {
837                 if (string.IsNullOrEmpty(key))
838                 {
839                     throw new ArgumentNullException("key");
840                 }
841                 Interop.AppControl.GetExtraData(_handle, key, out value);
842                 if (value != null)
843                 {
844                     return true;
845                 }
846                 else
847                 {
848                     value = default(string);
849                     return false;
850                 }
851             }
852
853             /// <summary>
854             /// Tries getting the extra data.
855             /// </summary>
856             /// <param name="key">The name of extra data.</param>
857             /// <param name="value">The value associated with the given key.</param>
858             /// <returns>The result whether getting the value is done.</returns>
859             /// <exception cref="ArgumentNullException">Thrown when the key is an invalid parameter.</exception>
860             /// <exception cref="KeyNotFoundException">Thrown when the key is not found.</exception>
861             /// <exception cref="ArgumentException">Thrown when the key is rejected.</exception>
862             /// <example>
863             /// <code>
864             /// AppControl appControl = new AppControl();
865             /// IEnumerable<string> myValue = null;
866             /// bool result = appControl.ExtraData.TryGet("myKey", out myValue);
867             /// if (result)
868             /// {
869             ///     foreach (string value in myValue)
870             ///     {
871             ///         // ...
872             ///     }
873             /// }
874             /// </code>
875             /// </example>
876             public bool TryGet(string key, out IEnumerable<string> value)
877             {
878                 if (string.IsNullOrEmpty(key))
879                 {
880                     throw new ArgumentNullException("key");
881                 }
882                 IntPtr valuePtr = IntPtr.Zero;
883                 int len = -1;
884                 Interop.AppControl.ErrorCode err = Interop.AppControl.GetExtraDataArray(_handle, key, out valuePtr, out len);
885                 if (err == Interop.AppControl.ErrorCode.None && valuePtr != IntPtr.Zero)
886                 {
887                     List<string> stringList = new List<string>();
888                     for (int i = 0; i < len; ++i)
889                     {
890                         IntPtr charArr = Marshal.ReadIntPtr(valuePtr, IntPtr.Size * i);
891                         stringList.Add(Marshal.PtrToStringAnsi(charArr));
892                         Interop.Libc.Free(charArr);
893                     }
894                     Interop.Libc.Free(valuePtr);
895                     value = stringList;
896                     return true;
897                 }
898                 else
899                 {
900                     value = default(IEnumerable<string>);
901                     return false;
902                 }
903             }
904
905             /// <summary>
906             /// Removes the extra data.
907             /// </summary>
908             /// <param name="key">The name of the extra data.</param>
909             /// <exception cref="ArgumentNullException">Thrown when the key is a zero-length string.</exception>
910             /// <exception cref="KeyNotFoundException">Thrown when the key is not found.</exception>
911             /// <exception cref="ArgumentException">Thrown when the key is rejected.</exception>
912             /// <example>
913             /// <code>
914             /// AppControl appControl = new AppControl();
915             /// appControl.ExtraData.Remove("myKey");
916             /// </code>
917             /// </example>
918             public void Remove(string key)
919             {
920                 if (string.IsNullOrEmpty(key))
921                 {
922                     throw new ArgumentNullException("key");
923                 }
924                 Interop.AppControl.ErrorCode err = Interop.AppControl.RemoveExtraData(_handle, key);
925                 if (err != Interop.AppControl.ErrorCode.None)
926                 {
927                     switch (err)
928                     {
929                         case Interop.AppControl.ErrorCode.InvalidParameter:
930                             throw new ArgumentException("Invalid parameter: key is a zero-length string");
931                         case Interop.AppControl.ErrorCode.KeyNotFound:
932                             throw new KeyNotFoundException("Key is not found"); ;
933                         case Interop.AppControl.ErrorCode.KeyRejected:
934                             throw new ArgumentException("Key is rejected: the key is system-defined key.");
935                         default:
936                             throw new InvalidOperationException("Error = " + err);
937                     }
938                 }
939             }
940
941             /// <summary>
942             /// Counts keys in the extra data.
943             /// </summary>
944             /// <returns>The number of counting keys.</returns>
945             /// <exception cref="InvalidOperationException">Thrown when the key is an invalid parameter.</exception>
946             /// <example>
947             /// <code>
948             /// AppControl appControl = new AppControl();
949             /// int numberOfKeys = appControl.ExtraData.Count();
950             /// </code>
951             /// </example>
952             public int Count()
953             {
954                 return GetKeys().Count();
955             }
956
957             /// <summary>
958             /// Checks whether the extra data associated with the given key is of the collection data type.
959             /// </summary>
960             /// <param name="key">The name of the extra data.</param>
961             /// <returns>If true, the extra data is of the array data type, otherwise false.</returns>
962             /// <exception cref="ArgumentNullException">Thrown when the key is a zero-length string.</exception>
963             /// <exception cref="InvalidOperationException">Thrown when failed to check the key.</exception>
964             /// <example>
965             /// <code>
966             /// AppControl appControl = new AppControl();
967             /// bool result = appControl.ExtraData.IsCollection("myKey");
968             /// </code>
969             /// </example>
970             public bool IsCollection(string key)
971             {
972                 if (string.IsNullOrEmpty(key))
973                 {
974                     throw new ArgumentNullException("key");
975                 }
976                 bool isArray = false;
977                 Interop.AppControl.ErrorCode err = Interop.AppControl.IsExtraDataArray(_handle, key, out isArray);
978                 if (err != Interop.AppControl.ErrorCode.None)
979                 {
980                     throw new InvalidOperationException("Error = " + err);
981                 }
982                 return isArray;
983             }
984
985             private string GetData(string key)
986             {
987                 if (string.IsNullOrEmpty(key))
988                 {
989                     throw new ArgumentNullException("key");
990                 }
991                 string value = string.Empty;
992                 Interop.AppControl.ErrorCode err = Interop.AppControl.GetExtraData(_handle, key, out value);
993                 if (err != Interop.AppControl.ErrorCode.None)
994                 {
995                     switch (err)
996                     {
997                         case Interop.AppControl.ErrorCode.InvalidParameter:
998                             throw new ArgumentException("Invalid parameter: key is a zero-length string");
999                         case Interop.AppControl.ErrorCode.KeyNotFound:
1000                             throw new KeyNotFoundException("Key is not found"); ;
1001                         case Interop.AppControl.ErrorCode.InvalidDataType:
1002                             throw new ArgumentException("Invalid data type: value is data collection type");
1003                         case Interop.AppControl.ErrorCode.KeyRejected:
1004                             throw new ArgumentException("Key is rejected: the key is system-defined key.");
1005                         default:
1006                             throw new InvalidOperationException("Error = " + err);
1007                     }
1008                 }
1009                 return value;
1010             }
1011
1012             private IEnumerable<string> GetDataCollection(string key)
1013             {
1014                 if (string.IsNullOrEmpty(key))
1015                 {
1016                     throw new ArgumentNullException("key");
1017                 }
1018                 IntPtr valuePtr = IntPtr.Zero;
1019                 int len = -1;
1020                 Interop.AppControl.ErrorCode err = Interop.AppControl.GetExtraDataArray(_handle, key, out valuePtr, out len);
1021                 if (err != Interop.AppControl.ErrorCode.None)
1022                 {
1023                     switch (err)
1024                     {
1025                         case Interop.AppControl.ErrorCode.InvalidParameter:
1026                             throw new ArgumentException("Invalid parameter: key is a zero-length string");
1027                         case Interop.AppControl.ErrorCode.KeyNotFound:
1028                             throw new KeyNotFoundException("Key is not found"); ;
1029                         case Interop.AppControl.ErrorCode.InvalidDataType:
1030                             throw new ArgumentException("Invalid data type: value is data collection type");
1031                         case Interop.AppControl.ErrorCode.KeyRejected:
1032                             throw new ArgumentException("Key is rejected: the key is system-defined key.");
1033                         default:
1034                             throw new InvalidOperationException("Error = " + err);
1035                     }
1036                 }
1037
1038                 List<string> valueArray = new List<string>();
1039                 if (valuePtr != IntPtr.Zero)
1040                 {
1041                     for (int i = 0; i < len; ++i)
1042                     {
1043                         IntPtr charArr = Marshal.ReadIntPtr(valuePtr, IntPtr.Size * i);
1044                         valueArray.Add(Marshal.PtrToStringAnsi(charArr));
1045                         Interop.Libc.Free(charArr);
1046                     }
1047                     Interop.Libc.Free(valuePtr);
1048                 }
1049                 return valueArray;
1050             }
1051         }
1052     }
1053 }