Merge remote-tracking branch 'phonenumber-utils/tizen'
[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 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 parameter.
74         /// </summary>
75         /// <param name="enableAppStartedResultEvent">The flag value to receive an additional launch result event on launch request.</param>
76         /// <exception cref="InvalidOperationException">Thrown when failed to create 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,
356         /// callee application would be launched as 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 caller application to launch an application.
359         /// Sub-applications which were launched as group mode always have own process.
360         /// Since Tizen 3.0, if launch mode not set in the caller app control,
361         /// this property returns 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 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 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 arguament</exception>
475         /// <exception cref="InvalidOperationException">Thrown when failed because of 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 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 arguament is invalid</exception>
504         /// <exception cref="InvalidOperationException">Thrown when failed because of invalid operation</exception>
505         /// <exception cref="TimeoutException">Thrown when failed because of timeout</exception>
506         /// <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
507         /// <example>
508         /// <code>
509         /// AppControl appControl = new AppControl();
510         /// appControl.ApplicationId = "org.tizen.calculator";
511         /// AppControl.SendLaunchRequest(appControl, (launchRequest, replyRequest, result) => {
512         ///     // ...
513         /// });
514         /// </code>
515         /// </example>
516         public static void SendLaunchRequest(AppControl launchRequest, AppControlReplyCallback replyAfterLaunching)
517         {
518             if (launchRequest == null)
519             {
520                 throw new ArgumentNullException("launchRequest");
521             }
522
523             Interop.AppControl.ErrorCode err;
524
525             if (replyAfterLaunching != null)
526             {
527                 int id = 0;
528                 lock (s_replyNativeCallbackMaps)
529                 {
530                     id = s_replyNativeCallbackId++;
531                     s_replyNativeCallbackMaps[id] = (launchRequestHandle, replyRequestHandle, result, userData) =>
532                     {
533                         if (replyAfterLaunching != null)
534                         {
535                             Log.Debug(LogTag, "Reply Callback is launched");
536                             replyAfterLaunching(new AppControl(launchRequestHandle), new AppControl(replyRequestHandle), (AppControlReplyResult)result);
537                             if (result != Interop.AppControl.AppStartedStatus)
538                             {
539                                 lock (s_replyNativeCallbackMaps)
540                                 {
541                                     s_replyNativeCallbackMaps.Remove(id);
542                                 }
543                             }
544                         }
545                     };
546                 }
547                 err = Interop.AppControl.SendLaunchRequest(launchRequest._handle, s_replyNativeCallbackMaps[id], IntPtr.Zero);
548             }
549             else
550             {
551                 err = Interop.AppControl.SendLaunchRequest(launchRequest._handle, null, IntPtr.Zero);
552             }
553
554             if (err != Interop.AppControl.ErrorCode.None)
555             {
556                 switch (err)
557                 {
558                     case Interop.AppControl.ErrorCode.InvalidParameter:
559                         throw new ArgumentException("Invalid Arguments");
560                     case Interop.AppControl.ErrorCode.TimedOut:
561                         throw new TimeoutException("Timed out");
562                     default:
563                         throw new InvalidOperationException("Error = " + err);
564                 }
565             }
566         }
567
568         /// <summary>
569         /// Sends the terminate request to the application that is launched by AppControl.
570         /// </summary>
571         /// <remarks>
572         /// You are not allowed to terminate other general applications using this API.
573         /// This API can be used to terminate sub-applications which were launched as group mode by caller application.
574         /// Once callee application is being terminated by this API,
575         /// other applications which were launched by callee application as group mode will be terminated as well
576         /// </remarks>
577         /// <param name="terminateRequest">The AppControl</param>
578         /// <exception cref="ArgumentException">Thrown when failed because of arguament is invalid</exception>
579         /// <exception cref="InvalidOperationException">Thrown when failed because of invalid operation</exception>
580         /// <exception cref="TimeoutException">Thrown when failed because of timeout</exception>
581         /// <example>
582         /// <code>
583         /// AppControl terminateRequest = new AppControl();
584         /// terminateRequest.ApplicationId = "org.tizen.calculator";
585         /// AppControl.SendTerminateRequest(terminateRequest);
586         /// </code>
587         /// </example>
588         public static void SendTerminateRequest(AppControl terminateRequest)
589         {
590             if (terminateRequest == null)
591             {
592                 throw new ArgumentNullException("terminateRequest");
593             }
594             Interop.AppControl.ErrorCode err;
595
596             err = Interop.AppControl.SendTerminateRequest(terminateRequest._handle);
597
598             if (err != Interop.AppControl.ErrorCode.None)
599             {
600                 switch (err)
601                 {
602                     case Interop.AppControl.ErrorCode.InvalidParameter:
603                         throw new ArgumentException("Invalid Arguments");
604                     case Interop.AppControl.ErrorCode.TimedOut:
605                         throw new TimeoutException("Timed out");
606                     default:
607                         throw new InvalidOperationException("Error = " + err);
608                 }
609             }
610         }
611
612         /// <summary>
613         /// Class for Extra Data
614         /// </summary>
615         public class ExtraDataCollection
616         {
617             private readonly SafeAppControlHandle _handle;
618
619             internal ExtraDataCollection(SafeAppControlHandle handle)
620             {
621                 _handle = handle;
622             }
623
624             /// <summary>
625             /// Adds extra data.
626             /// </summary>
627             /// <remarks>
628             /// The function replaces any existing value for the given key.
629             /// </remarks>
630             /// <param name="key">The name of the extra data</param>
631             /// <param name="value">The value associated with the given key</param>
632             /// <exception cref="ArgumentNullException">Thrown when key or value is a zero-length string</exception>
633             /// <exception cref="ArgumentException">Thrown when the application tries to use the same key with system-defined key</exception>
634             /// <example>
635             /// <code>
636             /// AppControl appControl = new AppControl();
637             /// appControl.ExtraData.Add("myKey", "myValue");
638             /// </code>
639             /// </example>
640             public void Add(string key, string value)
641             {
642                 if (string.IsNullOrEmpty(key))
643                 {
644                     throw new ArgumentNullException("key");
645                 }
646                 if (string.IsNullOrEmpty(value))
647                 {
648                     throw new ArgumentNullException("value");
649                 }
650                 Interop.AppControl.ErrorCode err = Interop.AppControl.AddExtraData(_handle, key, value);
651                 if (err != Interop.AppControl.ErrorCode.None)
652                 {
653                     switch (err)
654                     {
655                         case Interop.AppControl.ErrorCode.InvalidParameter:
656                             throw new ArgumentException("Invalid parameter: key or value is a zero-length string");
657                         case Interop.AppControl.ErrorCode.KeyRejected:
658                             throw new ArgumentException("Key is rejected: the key is system-defined key.");
659                         default:
660                             throw new InvalidOperationException("Error = " + err);
661                     }
662                 }
663             }
664
665             /// <summary>
666             /// Adds extra data.
667             /// </summary>
668             /// <remarks>
669             /// The function replaces any existing value for the given key.
670             /// </remarks>
671             /// <param name="key">The name of the extra data</param>
672             /// <param name="value">The value associated with the given key</param>
673             /// <exception cref="ArgumentNullException">Thrown when key or value is a zero-length string</exception>
674             /// <exception cref="ArgumentException">Thrown when the application tries to use the same key with system-defined key</exception>
675             /// <example>
676             /// <code>
677             /// AppControl appControl = new AppControl();
678             /// string[] myValues = new string[] { "first", "second", "third" };
679             /// appControl.ExtraData.Add("myKey", myValues);
680             /// </code>
681             /// </example>
682             public void Add(string key, IEnumerable<string> value)
683             {
684                 if (string.IsNullOrEmpty(key))
685                 {
686                     throw new ArgumentNullException("key");
687                 }
688                 if (value == null)
689                 {
690                     throw new ArgumentNullException("value");
691                 }
692                 string[] valueArray = value.ToArray();
693                 Interop.AppControl.ErrorCode err = Interop.AppControl.AddExtraDataArray(_handle, key, valueArray, valueArray.Length);
694                 if (err != Interop.AppControl.ErrorCode.None)
695                 {
696                     switch (err)
697                     {
698                         case Interop.AppControl.ErrorCode.InvalidParameter:
699                             throw new ArgumentException("Invalid parameter: key or value is a zero-length string");
700                         case Interop.AppControl.ErrorCode.KeyRejected:
701                             throw new ArgumentException("Key is rejected: the key is system-defined key.");
702                         default:
703                             throw new InvalidOperationException("Error = " + err);
704                     }
705                 }
706             }
707
708             /// <summary>
709             /// Gets the extra data.
710             /// </summary>
711             /// <typeparam name="T">Only string and IEnumerable&lt;string&gt;</typeparam>
712             /// <param name="key">The name of extra data</param>
713             /// <returns>The value associated with the given key</returns>
714             /// <exception cref="ArgumentNullException">Thrown when the key is invalid parameter</exception>
715             /// <exception cref="KeyNotFoundException">Thrown when the key is not found</exception>
716             /// <exception cref="ArgumentException">Thrown when the key is rejected</exception>
717             /// <example>
718             /// <code>
719             /// AppControl appControl = new AppControl();
720             /// string myValue = appControl.ExtraData.Get<string>("myKey");
721             /// </code>
722             /// </example>
723             public T Get<T>(string key)
724             {
725                 object ret = Get(key);
726                 return (T)ret;
727             }
728
729             /// <summary>
730             /// Gets the extra data.
731             /// </summary>
732             /// <param name="key">The name of extra data</param>
733             /// <returns>The value associated with the given key</returns>
734             /// <exception cref="ArgumentNullException">Thrown when the key is invalid parameter</exception>
735             /// <exception cref="KeyNotFoundException">Thrown when the key is not found</exception>
736             /// <exception cref="ArgumentException">Thrown when the key is rejected</exception>
737             /// <example>
738             /// <code>
739             /// AppControl appControl = new AppControl();
740             /// string myValue = appControl.ExtraData.Get("myKey") as string;
741             /// if (myValue != null)
742             /// {
743             ///     // ...
744             /// }
745             /// </code>
746             /// </example>
747             public object Get(string key)
748             {
749                 if (IsCollection(key))
750                 {
751                     return GetDataCollection(key);
752                 }
753                 else
754                 {
755                     return GetData(key);
756                 }
757             }
758
759             /// <summary>
760             /// Gets all keys in extra data.
761             /// </summary>
762             /// <returns>The keys in the AppControl</returns>
763             /// <exception cref="InvalidOperationException">Thrown when invalid parameter</exception>
764             /// <example>
765             /// <code>
766             /// AppControl appControl = new AppControl();
767             /// IEnumerable<string> keys = appControl.GetKeys();
768             /// if (keys != null)
769             /// {
770             ///     foreach (string key in keys)
771             ///     {
772             ///         // ...
773             ///     }
774             /// }
775             /// </code>
776             /// </example>
777             public IEnumerable<string> GetKeys()
778             {
779                 List<string> keys = new List<string>();
780                 Interop.AppControl.ExtraDataCallback callback = (handle, key, userData) =>
781                 {
782                     if (key == null)
783                     {
784                         return false;
785                     }
786
787                     keys.Add(key);
788                     return true;
789                 };
790
791                 Interop.AppControl.ErrorCode err = Interop.AppControl.ForeachExtraData(_handle, callback, IntPtr.Zero);
792                 if (err != Interop.AppControl.ErrorCode.None)
793                 {
794                     throw new InvalidOperationException("Failed to get keys. err = " + err);
795                 }
796
797                 return keys;
798             }
799
800             /// <summary>
801             /// Tries getting the extra data.
802             /// </summary>
803             /// <param name="key">The name of extra data</param>
804             /// <param name="value">The value associated with the given key</param>
805             /// <returns>The result whether getting the value is done</returns>
806             /// <exception cref="ArgumentNullException">Thrown when the key is invalid parameter</exception>
807             /// <exception cref="KeyNotFoundException">Thrown when the key is not found</exception>
808             /// <exception cref="ArgumentException">Thrown when the key is rejected</exception>
809             /// <example>
810             /// <code>
811             /// AppControl appControl = new AppControl();
812             /// string myValue = string.Empty;
813             /// bool result = appControl.ExtraData.TryGet("myKey", out myValue);
814             /// if (result != null)
815             /// {
816             ///     // ...
817             /// }
818             /// </code>
819             /// </example>
820             public bool TryGet(string key, out string value)
821             {
822                 if (string.IsNullOrEmpty(key))
823                 {
824                     throw new ArgumentNullException("key");
825                 }
826                 Interop.AppControl.GetExtraData(_handle, key, out value);
827                 if (value != null)
828                 {
829                     return true;
830                 }
831                 else
832                 {
833                     value = default(string);
834                     return false;
835                 }
836             }
837
838             /// <summary>
839             /// Tries getting the extra data.
840             /// </summary>
841             /// <param name="key">The name of extra data</param>
842             /// <param name="value">The value associated with the given key</param>
843             /// <returns>The result whether getting the value is done</returns>
844             /// <exception cref="ArgumentNullException">Thrown when the key is invalid parameter</exception>
845             /// <exception cref="KeyNotFoundException">Thrown when the key is not found</exception>
846             /// <exception cref="ArgumentException">Thrown when the key is rejected</exception>
847             /// <example>
848             /// <code>
849             /// AppControl appControl = new AppControl();
850             /// IEnumerable<string> myValue = null;
851             /// bool result = appControl.ExtraData.TryGet("myKey", out myValue);
852             /// if (result)
853             /// {
854             ///     foreach (string value in myValue)
855             ///     {
856             ///         // ...
857             ///     }
858             /// }
859             /// </code>
860             /// </example>
861             public bool TryGet(string key, out IEnumerable<string> value)
862             {
863                 if (string.IsNullOrEmpty(key))
864                 {
865                     throw new ArgumentNullException("key");
866                 }
867                 IntPtr valuePtr = IntPtr.Zero;
868                 int len = -1;
869                 Interop.AppControl.ErrorCode err = Interop.AppControl.GetExtraDataArray(_handle, key, out valuePtr, out len);
870                 if (err == Interop.AppControl.ErrorCode.None && valuePtr != IntPtr.Zero)
871                 {
872                     List<string> stringList = new List<string>();
873                     for (int i = 0; i < len; ++i)
874                     {
875                         IntPtr charArr = Marshal.ReadIntPtr(valuePtr, IntPtr.Size * i);
876                         stringList.Add(Marshal.PtrToStringAnsi(charArr));
877                         Interop.Libc.Free(charArr);
878                     }
879                     Interop.Libc.Free(valuePtr);
880                     value = stringList;
881                     return true;
882                 }
883                 else
884                 {
885                     value = default(IEnumerable<string>);
886                     return false;
887                 }
888             }
889
890             /// <summary>
891             /// Removes the extra data.
892             /// </summary>
893             /// <param name="key">The name of the extra data</param>
894             /// <exception cref="ArgumentNullException">Thrown when the key is a zero-length string</exception>
895             /// <exception cref="KeyNotFoundException">Thrown when the key is not found</exception>
896             /// <exception cref="ArgumentException">Thrown when the key is rejected</exception>
897             /// <example>
898             /// <code>
899             /// AppControl appControl = new AppControl();
900             /// appControl.ExtraData.Remove("myKey");
901             /// </code>
902             /// </example>
903             public void Remove(string key)
904             {
905                 if (string.IsNullOrEmpty(key))
906                 {
907                     throw new ArgumentNullException("key");
908                 }
909                 Interop.AppControl.ErrorCode err = Interop.AppControl.RemoveExtraData(_handle, key);
910                 if (err != Interop.AppControl.ErrorCode.None)
911                 {
912                     switch (err)
913                     {
914                         case Interop.AppControl.ErrorCode.InvalidParameter:
915                             throw new ArgumentException("Invalid parameter: key is a zero-length string");
916                         case Interop.AppControl.ErrorCode.KeyNotFound:
917                             throw new KeyNotFoundException("Key is not found"); ;
918                         case Interop.AppControl.ErrorCode.KeyRejected:
919                             throw new ArgumentException("Key is rejected: the key is system-defined key.");
920                         default:
921                             throw new InvalidOperationException("Error = " + err);
922                     }
923                 }
924             }
925
926             /// <summary>
927             /// Counts keys in the extra data.
928             /// </summary>
929             /// <returns>The number of counting keys</returns>
930             /// <exception cref="InvalidOperationException">Thrown when invalid parameter</exception>
931             /// <example>
932             /// <code>
933             /// AppControl appControl = new AppControl();
934             /// int numberOfKeys = appControl.ExtraData.Count();
935             /// </code>
936             /// </example>
937             public int Count()
938             {
939                 return GetKeys().Count();
940             }
941
942             /// <summary>
943             /// Checks whether the extra data associated with the given key is of collection data type.
944             /// </summary>
945             /// <param name="key">The name of the extra data</param>
946             /// <returns>If true the extra data is of array data type, otherwise false</returns>
947             /// <exception cref="ArgumentNullException">Thrown when the key is a zero-length string</exception>
948             /// <exception cref="InvalidOperationException">Thrown when failed to check the key</exception>
949             /// <example>
950             /// <code>
951             /// AppControl appControl = new AppControl();
952             /// bool result = appControl.ExtraData.IsCollection("myKey");
953             /// </code>
954             /// </example>
955             public bool IsCollection(string key)
956             {
957                 if (string.IsNullOrEmpty(key))
958                 {
959                     throw new ArgumentNullException("key");
960                 }
961                 bool isArray = false;
962                 Interop.AppControl.ErrorCode err = Interop.AppControl.IsExtraDataArray(_handle, key, out isArray);
963                 if (err != Interop.AppControl.ErrorCode.None)
964                 {
965                     throw new InvalidOperationException("Error = " + err);
966                 }
967                 return isArray;
968             }
969
970             private string GetData(string key)
971             {
972                 if (string.IsNullOrEmpty(key))
973                 {
974                     throw new ArgumentNullException("key");
975                 }
976                 string value = string.Empty;
977                 Interop.AppControl.ErrorCode err = Interop.AppControl.GetExtraData(_handle, key, out value);
978                 if (err != Interop.AppControl.ErrorCode.None)
979                 {
980                     switch (err)
981                     {
982                         case Interop.AppControl.ErrorCode.InvalidParameter:
983                             throw new ArgumentException("Invalid parameter: key is a zero-length string");
984                         case Interop.AppControl.ErrorCode.KeyNotFound:
985                             throw new KeyNotFoundException("Key is not found"); ;
986                         case Interop.AppControl.ErrorCode.InvalidDataType:
987                             throw new ArgumentException("Invalid data type: value is data collection type");
988                         case Interop.AppControl.ErrorCode.KeyRejected:
989                             throw new ArgumentException("Key is rejected: the key is system-defined key.");
990                         default:
991                             throw new InvalidOperationException("Error = " + err);
992                     }
993                 }
994                 return value;
995             }
996
997             private IEnumerable<string> GetDataCollection(string key)
998             {
999                 if (string.IsNullOrEmpty(key))
1000                 {
1001                     throw new ArgumentNullException("key");
1002                 }
1003                 IntPtr valuePtr = IntPtr.Zero;
1004                 int len = -1;
1005                 Interop.AppControl.ErrorCode err = Interop.AppControl.GetExtraDataArray(_handle, key, out valuePtr, out len);
1006                 if (err != Interop.AppControl.ErrorCode.None)
1007                 {
1008                     switch (err)
1009                     {
1010                         case Interop.AppControl.ErrorCode.InvalidParameter:
1011                             throw new ArgumentException("Invalid parameter: key is a zero-length string");
1012                         case Interop.AppControl.ErrorCode.KeyNotFound:
1013                             throw new KeyNotFoundException("Key is not found"); ;
1014                         case Interop.AppControl.ErrorCode.InvalidDataType:
1015                             throw new ArgumentException("Invalid data type: value is data collection type");
1016                         case Interop.AppControl.ErrorCode.KeyRejected:
1017                             throw new ArgumentException("Key is rejected: the key is system-defined key.");
1018                         default:
1019                             throw new InvalidOperationException("Error = " + err);
1020                     }
1021                 }
1022
1023                 List<string> valueArray = new List<string>();
1024                 if (valuePtr != IntPtr.Zero)
1025                 {
1026                     for (int i = 0; i < len; ++i)
1027                     {
1028                         IntPtr charArr = Marshal.ReadIntPtr(valuePtr, IntPtr.Size * i);
1029                         valueArray.Add(Marshal.PtrToStringAnsi(charArr));
1030                         Interop.Libc.Free(charArr);
1031                     }
1032                     Interop.Libc.Free(valuePtr);
1033                 }
1034                 return valueArray;
1035             }
1036         }
1037     }
1038 }