Add API level
[platform/core/csapi/uix-voice-control.git] / Tizen.Uix.VoiceControl / Tizen.Uix.VoiceControl / VoiceControlClient.cs
index b395f47..4b8638d 100755 (executable)
@@ -25,6 +25,7 @@ namespace Tizen.Uix.VoiceControl
     /// <summary>
     /// Enum for Error values that can occur
     /// </summary>
+    /// <since_tizen> 3 </since_tizen>
     public enum Error
     {
         /// <summary>
@@ -108,6 +109,7 @@ namespace Tizen.Uix.VoiceControl
     /// <summary>
     /// Enumeration for the client state.
     /// </summary>
+    /// <since_tizen> 3 </since_tizen>
     public enum State
     {
         /// <summary>
@@ -131,6 +133,7 @@ namespace Tizen.Uix.VoiceControl
     /// <summary>
     /// Enumerations of service state.
     /// </summary>
+    /// <since_tizen> 3 </since_tizen>
     public enum ServiceState
     {
         /// <summary>
@@ -158,6 +161,7 @@ namespace Tizen.Uix.VoiceControl
     /// <summary>
     /// Enumerations of result event.
     /// </summary>
+    /// <since_tizen> 3 </since_tizen>
     public enum ResultEvent
     {
         /// <summary>
@@ -173,6 +177,7 @@ namespace Tizen.Uix.VoiceControl
     /// <summary>
     /// Enumerations of command type.
     /// </summary>
+    /// <since_tizen> 3 </since_tizen>
     public enum CommandType
     {
         /// <summary>
@@ -193,11 +198,13 @@ namespace Tizen.Uix.VoiceControl
     /// A main function of Voice Control API register command and gets notification for recognition result. 
     /// Applications can add their own commands and be provided result when their command is recognized by user voice input.
     /// </summary>
+    /// <since_tizen> 3 </since_tizen>
     public static class VoiceControlClient
     {
         /// <summary>
         /// Called when client gets the recognition result.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <remarks>
         /// If the duplicated commands are recognized, the event(e.g. Result.Rejected) of command may be rejected
         /// for selecting command as priority.If you set similar or same commands or the recognized results are multi-results, cmdList has the multi commands.
@@ -205,7 +212,6 @@ namespace Tizen.Uix.VoiceControl
         /// <param name="evt">The ResultEvent</param>
         /// <param name="cmdList">Command List</param>
         /// <param name="result">Result</param>
-        public delegate void RecognitionResultDelegate(ResultEvent evt, VoiceCommandList cmdList, string result);
 
         private static event EventHandler<RecognitionResultEventArgs> _recognitionResult;
         private static event EventHandler<StateChangedEventArgs> _stateChanged;
@@ -220,6 +226,7 @@ namespace Tizen.Uix.VoiceControl
         private static List<string> s_supportedLanguages;
         private static VcSupportedLanguageCb s_supportedLanguagesCb;
         private static VcResultCb s_resultCb;
+        private static RecognitionResult s_recognitionResult;
 
         /// <summary>
         /// Gets current language.
@@ -228,15 +235,16 @@ namespace Tizen.Uix.VoiceControl
         /// For example, "ko_KR" for Korean, "en_US" for American English.
         /// Empty string is returned incase of some internal error
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <value>
         /// Current language in voice control.
         /// </value>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
-        /// <precondition>
+        /// <pre>
         /// The State must be Initialized or Ready.
-        /// </precondition>
+        /// </pre>
         public static string CurrentLanguage
         {
             get
@@ -257,15 +265,16 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Gets current state of voice control client.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <value>
         /// Current state of voice control client.
         /// </value>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
-        /// <precondition>
+        /// <pre>
         /// The State must be Initialized or Ready.
-        /// </precondition>
+        /// </pre>
         public static State State
         {
             get
@@ -286,15 +295,16 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Gets current state of voice control service.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <value>
         /// Current state of voice control service.
         /// </value>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
-        /// <precondition>
+        /// <pre>
         /// The State must be Ready.
-        /// </precondition>
+        /// </pre>
         public static ServiceState ServiceState
         {
             get
@@ -315,6 +325,7 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Sets the invocation name.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
@@ -338,9 +349,9 @@ namespace Tizen.Uix.VoiceControl
         /// <exception cref="ArgumentException"> This Exception can be due to Invalid Parameter. </exception>
         /// <exception cref="NotSupportedException"> This Exception can be due to Not Supported. </exception>
         /// <exception cref="UnauthorizedAccessException"> This Exception can be due to Permission Denied. </exception>
-        /// <precondition>
+        /// <pre>
         /// The State must be Ready.
-        /// </precondition>
+        /// </pre>
         public static void SetInvocationName(string name)
         {
             ErrorCode error = VcSetInvocationName(name);
@@ -354,6 +365,7 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Initializes voice control.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
@@ -368,9 +380,9 @@ namespace Tizen.Uix.VoiceControl
         /// <exception cref="OutOfMemoryException"> This Exception can be due to Out Of Memory. </exception>
         /// <exception cref="NotSupportedException"> This Exception can be due to Not Supported. </exception>
         /// <exception cref="UnauthorizedAccessException"> This Exception can be due to Permission Denied. </exception>
-        /// <postcondition>
+        /// <post>
         /// The State will be Initialized.
-        /// </postcondition>
+        /// </post>
         public static void Initialize()
         {
             ErrorCode error = VcInitialize();
@@ -384,6 +396,7 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Deinitializes voice control.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
@@ -411,6 +424,7 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Connects the voice control service.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
@@ -425,12 +439,12 @@ namespace Tizen.Uix.VoiceControl
         /// <exception cref="InvalidOperationException"> This Exception can be due to Operation Failed. </exception>
         /// <exception cref="NotSupportedException"> This Exception can be due to Not Supported. </exception>
         /// <exception cref="UnauthorizedAccessException"> This Exception can be due to Permission Denied. </exception>
-        /// <precondition>
+        /// <pre>
         /// The State should be Initialized
-        /// </precondition>
-        /// <postcondition>
+        /// </pre>
+        /// <post>
         /// The State will be Ready
-        /// </postcondition>
+        /// </post>
         public static void Prepare()
         {
             ErrorCode error = VcPrepare();
@@ -444,6 +458,7 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Disconnects the voice control service.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
@@ -457,12 +472,12 @@ namespace Tizen.Uix.VoiceControl
         /// <exception cref="InvalidOperationException"> This Exception can be due to Invalid State. </exception>
         /// <exception cref="NotSupportedException"> This Exception can be due to Not Supported. </exception>
         /// <exception cref="UnauthorizedAccessException"> This Exception can be due to Permission Denied. </exception>
-        /// <precondition>
+        /// <pre>
         /// The State should be Ready
-        /// </precondition>
-        /// <postcondition>
+        /// </pre>
+        /// <post>
         /// The State should be Initialized
-        /// </postcondition>
+        /// </post>
         public static void Unprepare()
         {
             ErrorCode error = VcUnprepare();
@@ -479,6 +494,7 @@ namespace Tizen.Uix.VoiceControl
         /// followed by ISO 639-1 for the two-letter language code.
         /// For example, "ko_KR" for Korean, "en_US" for American English.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
@@ -493,10 +509,10 @@ namespace Tizen.Uix.VoiceControl
         /// <exception cref="InvalidOperationException"> This Exception can be due to Operation Failed. </exception>
         /// <exception cref="NotSupportedException"> This Exception can be due to Not Supported. </exception>
         /// <exception cref="UnauthorizedAccessException"> This Exception can be due to Permission Denied. </exception>
-        /// <precondition>
+        /// <pre>
         /// The State should be Ready or Initialized
-        /// </precondition>
-        public static IEnumerable<string> GetSupportedLangauges()
+        /// </pre>
+        public static IEnumerable<string> GetSupportedLanguages()
         {
             s_supportedLanguages = new List<string>();
             s_supportedLanguagesCb = (IntPtr language, IntPtr userData) =>
@@ -508,7 +524,7 @@ namespace Tizen.Uix.VoiceControl
             ErrorCode error = VcForeachSupportedLanguages(s_supportedLanguagesCb, IntPtr.Zero);
             if (error != ErrorCode.None)
             {
-                Log.Error(LogTag, "GetSupportedLangauges Failed with error " + error);
+                Log.Error(LogTag, "GetSupportedLanguages Failed with error " + error);
                 throw ExceptionFactory.CreateException(error);
             }
 
@@ -518,6 +534,7 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Gets the system command list.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <returns>
         /// The Command List else null in case of no System Commands
         /// </returns>
@@ -539,10 +556,10 @@ namespace Tizen.Uix.VoiceControl
         /// <exception cref="InvalidOperationException"> This Exception can be due to Operation Failed. </exception>
         /// <exception cref="NotSupportedException"> This Exception can be due to Not Supported. </exception>
         /// <exception cref="UnauthorizedAccessException"> This Exception can be due to Permission Denied. </exception>
-        /// <precondition>
+        /// <pre>
         /// The State should be Ready
-        /// </precondition>
-        public static VoiceCommandList GetSytemCommandList()
+        /// </pre>
+        public static VoiceCommandList GetSystemCommandList()
         {
             IntPtr handle = IntPtr.Zero;
             ErrorCode error = VcGetSystemCommandList(out handle);
@@ -570,6 +587,7 @@ namespace Tizen.Uix.VoiceControl
         /// Also, the developer can set whether the dialogue starts automatically or not, using autoStart.
         /// If the developer sets autoStart as true, the framework will start to record next speech and continue the dialogue.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
@@ -590,9 +608,9 @@ namespace Tizen.Uix.VoiceControl
         /// <exception cref="ArgumentException"> This Exception can be due to Invalid Parameter. </exception>
         /// <exception cref="NotSupportedException"> This Exception can be due to Not Supported. </exception>
         /// <exception cref="UnauthorizedAccessException"> This Exception can be due to Permission Denied. </exception>
-        /// <precondition>
+        /// <pre>
         /// The State should be Ready
-        /// </precondition>
+        /// </pre>
         public static void RequestDialog(string dispText, string uttText, bool autoStart)
         {
             ErrorCode error = VcRequestDialog(dispText, uttText, autoStart);
@@ -606,6 +624,7 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Sets command list.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
@@ -626,9 +645,9 @@ namespace Tizen.Uix.VoiceControl
         /// <exception cref="ArgumentException"> This Exception can be due to Invalid Parameter. </exception>
         /// <exception cref="NotSupportedException"> This Exception can be due to Not Supported. </exception>
         /// <exception cref="UnauthorizedAccessException"> This Exception can be due to Permission Denied. </exception>
-        /// <precondition>
+        /// <pre>
         /// The State should be Ready
-        /// </precondition>
+        /// </pre>
         public static void SetCommandList(VoiceCommandList list, CommandType type)
         {
             if ((type == CommandType.Foreground) || (type == CommandType.Background))
@@ -650,6 +669,7 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Unsets command list.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
@@ -665,9 +685,9 @@ namespace Tizen.Uix.VoiceControl
         /// <exception cref="ArgumentException"> This Exception can be due to Invalid Parameter. </exception>
         /// <exception cref="NotSupportedException"> This Exception can be due to Not Supported. </exception>
         /// <exception cref="UnauthorizedAccessException"> This Exception can be due to Permission Denied. </exception>
-        /// <precondition>
+        /// <pre>
         /// The State should be Ready
-        /// </precondition>
+        /// </pre>
         public static void UnsetCommandList(CommandType type)
         {
             if ((type == CommandType.Foreground) || (type == CommandType.Background))
@@ -692,6 +712,7 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Gets the recognition result.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         /// <privilege>
         /// http://tizen.org/privilege/recorder
         /// </privilege>
@@ -702,22 +723,19 @@ namespace Tizen.Uix.VoiceControl
         /// http://tizen.org/feature/speech.control
         /// http://tizen.org/feature/microphone
         /// </feature>
-        /// <param name="resultDelegate">
-        /// Callback function to get recognition result
-        /// </param>
         /// <exception cref="InvalidOperationException"> This Exception can be due to Invalid State. </exception>
         /// <exception cref="ArgumentException"> This Exception can be due to Invalid Parameter. </exception>
         /// <exception cref="NotSupportedException"> This Exception can be due to Not Supported. </exception>
-        /// <precondition>
+        /// <returns>The Recognition Result if possible else a null object</returns>
+        /// <pre>
         /// The State should be Ready
-        /// </precondition>
-        public static void GetResult(RecognitionResultDelegate resultDelegate)
+        /// </pre>
+        public static RecognitionResult GetResult()
         {
+            s_recognitionResult = null;
             s_resultCb = (ResultEvent evt, IntPtr cmdList, IntPtr result, IntPtr userData) =>
             {
-                VoiceCommandList list = new VoiceCommandList(new SafeCommandListHandle(cmdList));
-                string resultStr = Marshal.PtrToStringAnsi(result);
-                resultDelegate(evt, list, resultStr);
+                s_recognitionResult = new RecognitionResult(evt, cmdList, result);
             };
             ErrorCode error = VcGetResult(s_resultCb, IntPtr.Zero);
             if (error != ErrorCode.None)
@@ -725,14 +743,17 @@ namespace Tizen.Uix.VoiceControl
                 Log.Error(LogTag, "GetResult Failed with error " + error);
                 throw ExceptionFactory.CreateException(error);
             }
+
+            return s_recognitionResult;
         }
 
         /// <summary>
         /// Event to be invoked when the recognition is done.
         /// </summary>
-        /// <precondition>
+        /// <since_tizen> 3 </since_tizen>
+        /// <pre>
         /// The State should be Initialized
-        /// </precondition>
+        /// </pre>
         public static event EventHandler<RecognitionResultEventArgs> RecognitionResult
         {
             add
@@ -742,7 +763,7 @@ namespace Tizen.Uix.VoiceControl
                     Log.Info(LogTag, "Recognition Result Event Triggered");
                     if ((cmdList != null) && (result != null))
                     {
-                        RecognitionResultEventArgs args = new RecognitionResultEventArgs(evt, cmdList, result);
+                        RecognitionResultEventArgs args = new RecognitionResultEventArgs(new RecognitionResult( evt, cmdList, result));
                         _recognitionResult?.Invoke(null, args);
                     }
                     else
@@ -776,9 +797,10 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Event to be invoked when VoiceControl service state changes.
         /// </summary>
-        /// <precondition>
+        /// <since_tizen> 3 </since_tizen>
+        /// <pre>
         /// The State should be Initialized
-        /// </precondition>
+        /// </pre>
         public static event EventHandler<ServiceStateChangedEventArgs> ServiceStateChanged
         {
             add
@@ -814,9 +836,10 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Event to be invoked when VoiceControl client state changes.
         /// </summary>
-        /// <precondition>
+        /// <since_tizen> 3 </since_tizen>
+        /// <pre>
         /// The State should be Initialized
-        /// </precondition>
+        /// </pre>
         public static event EventHandler<StateChangedEventArgs> StateChanged
         {
             add
@@ -852,9 +875,10 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Event to be invoked when an error occurs.
         /// </summary>
-        /// <precondition>
+        /// <since_tizen> 3 </since_tizen>
+        /// <pre>
         /// The State should be Initialized
-        /// </precondition>
+        /// </pre>
         public static event EventHandler<ErrorOccuredEventArgs> ErrorOccured
         {
             add
@@ -892,9 +916,10 @@ namespace Tizen.Uix.VoiceControl
         /// <summary>
         /// Event to be invoked when default laungage change.
         /// </summary>
-        /// <precondition>
+        /// <since_tizen> 3 </since_tizen>
+        /// <pre>
         /// The State should be Initialized
-        /// </precondition>
+        /// </pre>
         public static event EventHandler<CurrentLanguageChangedEventArgs> CurrentLanguageChanged
         {
             add