Development/Tutorials/KAuth/KAuth Actions - Revision history

AnneW at 15:33, 19 July 2012

2012-07-19T15:33:42Z

Lin-unix: Added link to KAuth Troubleshooting wiki page

2011-11-25T17:59:27Z

Added link to KAuth Troubleshooting wiki page

Jan: Add syntax highlighting

2011-10-21T22:04:18Z

Add syntax highlighting

Neverendingo: Text replace - "" to ""

2011-06-29T19:42:17Z

Text replace - "</code>" to "</syntaxhighlight>"

Neverendingo: Text replace - "`" to ""`


2011-06-29T19:38:48Z
Text replace - "<code cpp>" to "<syntaxhighlight lang="cpp">"

				
				
				
				
			
			← Older revision
			Revision as of 19:38, 29 June 2011
			
Line 26:
Line 26:
  If your action has no helper associated with it (so you just want to check if the user is authorized before going on), the next step is just doing the following:   If your action has no helper associated with it (so you just want to check if the user is authorized before going on), the next step is just doing the following:
    
− <code cpp> + <syntaxhighlight lang="cpp">
  KAuth::ActionReply reply = readAction.execute();   KAuth::ActionReply reply = readAction.execute();
  if (reply.failed()) {   if (reply.failed()) {
Line 40:
Line 40:
  The basics are pretty much the same. This is how the snippet changes:   The basics are pretty much the same. This is how the snippet changes:
    
− <code cpp> + <syntaxhighlight lang="cpp">
  KAuth::Action readAction = "org.kde.auth.example.read";   KAuth::Action readAction = "org.kde.auth.example.read";
  readAction.setHelperID("org.kde.auth.example");   readAction.setHelperID("org.kde.auth.example");
Line 64:
Line 64:
  In the previous examples all the actions have been executed synchronously. However, when you have an action attached to an helper which is likely to be taking a long time, a synchronous approach is not very well fitting. KAuth is able to handle action execution asynchronously just by setting ''Action::setExecutesAsync(true)''. To monitor the action's progress there's a new object, ''ActionWatcher'', that can be used for this purpose. Let's see how a long action could be handled:   In the previous examples all the actions have been executed synchronously. However, when you have an action attached to an helper which is likely to be taking a long time, a synchronous approach is not very well fitting. KAuth is able to handle action execution asynchronously just by setting ''Action::setExecutesAsync(true)''. To monitor the action's progress there's a new object, ''ActionWatcher'', that can be used for this purpose. Let's see how a long action could be handled:
    
− <code cpp> + <syntaxhighlight lang="cpp">
  void MainWindow::on_longAction_triggered()   void MainWindow::on_longAction_triggered()
    {     {
Line 113:
Line 113:
  You can easily check the error type through ''ActionReply::type'':   You can easily check the error type through ''ActionReply::type'':
    
− <code cpp> + <syntaxhighlight lang="cpp">
  if (reply.failed())   if (reply.failed())
  {   {
Line 142:
Line 142:
  Let's see how the longAction example changes when dealing with a KPushButton:   Let's see how the longAction example changes when dealing with a KPushButton:
    
− <code cpp> + <syntaxhighlight lang="cpp">
  void MainWindow::setupAction()   void MainWindow::setupAction()
    {     {



Jmc: Fixed a typo: succeded() → succeeded()
2011-03-17T18:33:54Z
Fixed a typo: succeded() → succeeded()

				
				
				
				
			
			← Older revision
			Revision as of 18:33, 17 March 2011
			
Line 91:
Line 91:
        //...         //...
    
−       if (reply.succeded()) +       if (reply.succeeded())
−          this->statusBar()->showMessage("Action succeded", 10000); +          this->statusBar()->showMessage("Action succeeded", 10000);
        else         else
           this->statusBar()->showMessage(QString("Could not execute the long action: %1").arg(reply.errorCode()), 10000);            this->statusBar()->showMessage(QString("Could not execute the long action: %1").arg(reply.errorCode()), 10000);



Drf at 13:11, 12 February 2010
2010-02-12T13:11:45Z


				
				
				
				
			
			← Older revision
			Revision as of 13:11, 12 February 2010
			
Line 101:
Line 101:
    
  Also, note that asyncronous actions may be stopped with ''Action::stop()''   Also, note that asyncronous actions may be stopped with ''Action::stop()''
  + 
  + == Handling ActionReply ==
  + As you have seen in the previous examples, action execution always returns an ''ActionReply''. Let's see how to handle it
  + 
  + === Handling errors ===
  + ''ActionReply'' has two main possible statuses: ''Success'' or ''Failed''. In case of failure, the error could be associated to two different sources:
  + 
  + *KAuth's internals
  + *An error in the execution phase (e.g.: the helper encountered an error)
  + 
  + You can easily check the error type through ''ActionReply::type'':
  + 
  + <code cpp>
  + if (reply.failed())
  + {
  +   if (reply.type() == ActionReply::KAuthError) {
  +         // There has been an internal KAuth error
  +         KMessageBox::error(this, i18n("Unable to authenticate/execute the action: %1, %2", reply.errorCode(), reply.errorDescription()));
  +   } else {
  +          // Our helper triggered a custom error
  +          // Act accordingly...
  +   }
  + }
  + </code>
  + 
  + ''ActionReply::KAuthError'' is a reserved type that reports an internal error happened in KAuth. This could also mean a failure in the authorization/authentication phase: you have to check the error code for that.
  + 
  + Otherwise, it means the helper threw an error (as you will see in the next tutorial): in this case, errorCode and description are provided by the helper itself
  + 
  + === Getting back data ===
  + Just like ''Action'' has '''arguments''', ''ActionReply'' has '''data''', which works in a very similar flavour. Upon a successful reply, you can use ''ActionReply::data()'' to obtain a QVariantMap carrying some custom data streamed from the helper
  + 
  + === Differences when using or not using an helper ===
  + When not using an helper, ActionReply will just report success without any data attached to it or an ''ActionReply::KAuthError''.
    
  == Integrating KAuth Actions into KDE UI elements ==   == Integrating KAuth Actions into KDE UI elements ==



Drf at 12:12, 12 February 2010
2010-02-12T12:12:53Z


				
				
				
				
			
			← Older revision
			Revision as of 12:12, 12 February 2010
			
Line 74:
Line 74:
    
       longAction.setExecutesAsync(true);        longAction.setExecutesAsync(true);
−      if (longAction.execute() != Action::Authorized) { +      ActionReply earlyReply = longAction.execute();
  +     if (earlyReply.failed()) {
           this->statusBar()->showMessage("Could not execute the long action");            this->statusBar()->showMessage("Could not execute the long action");
        }         }
Line 104:
Line 105:
  KDE provides a way to integrate KAuth action seamlessly into a user interface. UI elements such as ''KPushButton'' can be associated with an action, and will update their appearance based on the action's status. Also, KPushButton is able to perform an early authorization, if supported by the authorization system, before notifying back the application.   KDE provides a way to integrate KAuth action seamlessly into a user interface. UI elements such as ''KPushButton'' can be associated with an action, and will update their appearance based on the action's status. Also, KPushButton is able to perform an early authorization, if supported by the authorization system, before notifying back the application.
    
− ===How it works=== + ===Integrating KPushButton===
  Let's see how the longAction example changes when dealing with a KPushButton:   Let's see how the longAction example changes when dealing with a KPushButton:
    
Line 125:
Line 126:
  void MainWindow::performAction(KAuth::Action *action)   void MainWindow::performAction(KAuth::Action *action)
  {   {
−      if (action->execute() != Action::Authorized) { +      ActionReply earlyReply = action->execute();
  +     if (earlyReply.failed()) {
           this->statusBar()->showMessage("Could not execute the long action");            this->statusBar()->showMessage("Could not execute the long action");
        }         }
Line 153:
Line 155:
    
  To the bottom line, associating actions to KPushButtons is a great idea if you want to start up an action dynamically, and getting good and consistent visual integration while doing it.   To the bottom line, associating actions to KPushButtons is a great idea if you want to start up an action dynamically, and getting good and consistent visual integration while doing it.
  + 
  + ===Other GUI elements===
  + As of today, KAuth is also able to integrate with ''KAction'' with an almost identical workflow, that hence won't be covered here, as the API is identical.
    
  ==Conclusion==   ==Conclusion==
  As you have seen, there are lots of ways to use an action in your application, and most of the times the best solution depends on what you're trying to achieve. A good reading and advised reading is the KAuth::Action API documentation, which is quite extensive and covers everything that was shown in this tutorial   As you have seen, there are lots of ways to use an action in your application, and most of the times the best solution depends on what you're trying to achieve. A good reading and advised reading is the KAuth::Action API documentation, which is quite extensive and covers everything that was shown in this tutorial



Drf at 12:42, 11 February 2010
2010-02-11T12:42:04Z


				
				
				
				
			
			← Older revision
			Revision as of 12:42, 11 February 2010
			
Line 1:
Line 1:
− [http://www.example.com link title]{{Template:I18n/Language Navigation Bar|Development/Tutorials/KAuth/KAuth Actions}}   + {{Template:I18n/Language Navigation Bar|Development/Tutorials/KAuth/KAuth Actions}}  
    
  {{TutorialBrowser|   {{TutorialBrowser|



Drf at 12:40, 11 February 2010
2010-02-11T12:40:08Z


				
				
				
				
			
			← Older revision
			Revision as of 12:40, 11 February 2010
			
Line 1:
Line 1:
− {{Template:I18n/Language Navigation Bar|Development/Tutorials/KAuth/KAuth Actions}}   + [http://www.example.com link title]{{Template:I18n/Language Navigation Bar|Development/Tutorials/KAuth/KAuth Actions}}  
    
  {{TutorialBrowser|   {{TutorialBrowser|
Line 11:
Line 11:
  next=[[Development/Tutorials/KAuth/Helper_HowTo|Creating a KAuth helper to perform a privileged action]]|     next=[[Development/Tutorials/KAuth/Helper_HowTo|Creating a KAuth helper to perform a privileged action]]|  
    
− reading=[[http://api.kde.org/4.x-api/kdelibs-apidocs/kdecore/html/classKAuth_1_1Action.html|KAuth::Action Class Reference]] + reading=[http://api.kde.org/4.x-api/kdelibs-apidocs/kdecore/html/classKAuth_1_1Action.html KAuth::Action Class Reference]
  }}     }}

@@ Line 19: / Line 19: @@
 === A simple case: creating and executing an action that has no helper associated ===
 Creating an action in your code is rather simple:
+<syntaxhighlight lang="cpp">
- Action readAction = "org.kde.auth.example.read";
+KAuth::Action readAction = "org.kde.auth.example.read";
 As you can see, Actions are usually created on the stack and just when needed. To create an action, you just have to specify its own identifier.

@@ Line 33: / Line 33: @@
     // Do your stuff here...
+}
-</code>
+</syntaxhighlight>
 ''Action::execute()'' starts up all the phases from authorization to execution and returns an ActionReply. In our case, if the reply failed is because the authorization was unsuccessful: in any case, ActionReply carries additional information about the error occurred.
@@ Line 53: / Line 53: @@
     contents = reply.data()["contents"].toString();
+}
-</code>
+</syntaxhighlight>
 There are more parameters this time. First of all, the helper has to be explicitely declared throughout ''Action::setHelperID''. This is also done to prevent calling an helper accidentally. We are also able to pass some parameters to the helper, through ''Action::setArguments''. In the very same way, the helper, upon success, is able to give back to the application a QVariantMap, accessible through ''ActionReply::data()''.
@@ Line 96: / Line 96: @@
          this->statusBar()->showMessage(QString("Could not execute the long action: %1").arg(reply.errorCode()), 10000);
+  }
-</code>
+</syntaxhighlight>
 As you can see, we're using the watcher to monitor the progress and the result. Please note that even if the action is asynchronous a check on an early reply is performed: this is because with some authorization systems the authorization might take place very early, and hence before the asyncronous action returns to the event loop.
@@ Line 124: / Line 124: @@
+   }
+}
-</code>
+</syntaxhighlight>
 ''ActionReply::KAuthError'' is a reserved type that reports an internal error happened in KAuth. This could also mean a failure in the authorization/authentication phase: you have to check the error code for that.
@@ Line 182: / Line 182: @@
          this->statusBar()->showMessage(QString("Could not execute the long action: %1").arg(reply.errorCode()), 10000);
+  }
-</code>
+</syntaxhighlight>
 As you may notice, here the action is allocated on the heap through ''new''. This is because KPushButton will keep a reference to the same action throughout all his vital cycle, in a different flavour compared to what we've seen before.

← Older revision		Revision as of 15:33, 19 July 2012
Line 1:		Line 1:
−	~~{{Template:I18n/Language Navigation Bar\|Development/Tutorials/KAuth/KAuth Actions}}~~	+

	{{TutorialBrowser\|		{{TutorialBrowser\|

← Older revision		Revision as of 13:11, 12 February 2010
Line 101:		Line 101:

	Also, note that asyncronous actions may be stopped with ''Action::stop()''		Also, note that asyncronous actions may be stopped with ''Action::stop()''
		+
		+	== Handling ActionReply ==
		+	As you have seen in the previous examples, action execution always returns an ''ActionReply''. Let's see how to handle it
		+
		+	=== Handling errors ===
		+	''ActionReply'' has two main possible statuses: ''Success'' or ''Failed''. In case of failure, the error could be associated to two different sources:
		+
		+	*KAuth's internals
		+	*An error in the execution phase (e.g.: the helper encountered an error)
		+
		+	You can easily check the error type through ''ActionReply::type'':
		+
		+	<code cpp>
		+	if (reply.failed())
		+	{
		+	if (reply.type() == ActionReply::KAuthError) {
		+	// There has been an internal KAuth error
		+	KMessageBox::error(this, i18n("Unable to authenticate/execute the action: %1, %2", reply.errorCode(), reply.errorDescription()));
		+	} else {
		+	// Our helper triggered a custom error
		+	// Act accordingly...
		+	}
		+	}
		+	</code>
		+
		+	''ActionReply::KAuthError'' is a reserved type that reports an internal error happened in KAuth. This could also mean a failure in the authorization/authentication phase: you have to check the error code for that.
		+
		+	Otherwise, it means the helper threw an error (as you will see in the next tutorial): in this case, errorCode and description are provided by the helper itself
		+
		+	=== Getting back data ===
		+	Just like ''Action'' has '''arguments''', ''ActionReply'' has '''data''', which works in a very similar flavour. Upon a successful reply, you can use ''ActionReply::data()'' to obtain a QVariantMap carrying some custom data streamed from the helper
		+
		+	=== Differences when using or not using an helper ===
		+	When not using an helper, ActionReply will just report success without any data attached to it or an ''ActionReply::KAuthError''.

	== Integrating KAuth Actions into KDE UI elements ==		== Integrating KAuth Actions into KDE UI elements ==

← Older revision		Revision as of 12:42, 11 February 2010
Line 1:		Line 1:
−	~~[http://www.example.com link title]~~{{Template:I18n/Language Navigation Bar\|Development/Tutorials/KAuth/KAuth Actions}}	+	{{Template:I18n/Language Navigation Bar\|Development/Tutorials/KAuth/KAuth Actions}}

	{{TutorialBrowser\|		{{TutorialBrowser\|