|
|
| (25 intermediate revisions by 9 users not shown) |
| Line 1: |
Line 1: |
| {{Template:I18n/Language Navigation Bar|Development/Tutorials/KAuth/KAuth Actions}}
| | This tutorial was moved to [https://develop.kde.org/docs/features/kauth/ develop.kde.org/docs/features/kauth/] |
| | |
| {{TutorialBrowser|
| |
| | |
| series=KAuth Tutorial|
| |
| | |
| name=Using KAuth actions in your application|
| |
| | |
| pre=[[Development/Tutorials/KAuth/KAuth_Basics|KAuth Basics]]|
| |
| | |
| next=[[Development/Tutorials/KAuth/Helper_HowTo|Creating a KAuth helper to perform a privileged action]]|
| |
| | |
| reading=None
| |
| }}
| |
| | |
| == Using actions in your applications ==
| |
| Now that you've learned the basic KAuth concepts and how to register a set of actions into the system, it's time to see how to actually use KAuth actions inside your application. This tutorial will cover the caller side: how to implement an helper associated to an action will be covered in the next tutorial.
| |
| | |
| == A simple case: creating and executing an action that has no helper associated ==
| |
| Creating an action in your code is rather simple:
| |
| | |
| 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.
| |
| | |
| 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>
| |
| KAuth::ActionReply reply = readAction.execute();
| |
| if (reply.failed()) {
| |
| QMessageBox::information(this, "Error", QString("KAuth returned an error code: %1").arg(reply.errorCode()));
| |
| } else {
| |
| // Do your stuff here...
| |
| }
| |
| </code>
| |
| | |
| ''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.
| |
| | |
| == Creating and executing an action that has an helper attached to it ==
| |
| The basics are pretty much the same. This is how the snippet changes:
| |
| | |
| <code cpp>
| |
| KAuth::Action readAction = "org.kde.auth.example.read";
| |
| readAction.setHelperID("org.kde.auth.example");
| |
| QVariantMap args;
| |
| args["filename"] = filename;
| |
| readAction.setArguments(args);
| |
| | |
| KAuth::ActionReply reply = readAction.execute();
| |
| if (reply.failed()) {
| |
| QMessageBox::information(this, "Error", QString("KAuth returned an error code: %1").arg(reply.errorCode()));
| |
| } else {
| |
| contents = reply.data()["contents"].toString();
| |
| }
| |
| </code>
| |
| | |
| 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()''.
| |
| | |
| In this case, ''Action::execute()'' also launches the execution phase of the helper, given that the authorization was successful.
| |
| | |
| There are more advanced usages for helper actions, such as progress reporting and data retrieval during execution, but these will be covered in the next tutorial.
| |
| | |
| == Executing actions asynchronously ==
| |
| 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>
| |
| void MainWindow::on_longAction_triggered()
| |
| {
| |
| Action longAction = "org.kde.auth.example.longaction";
| |
| connect(longAction.watcher(), SIGNAL(progressStep(int)),
| |
| progressBar, SLOT(setValue(int)));
| |
| connect(longAction.watcher(), SIGNAL(actionPerformed(ActionReply)),
| |
| this, SLOT(longActionPerformed(ActionReply)));
| |
| | |
| longAction.setExecutesAsync(true);
| |
| if (longAction.execute() != Action::Authorized) {
| |
| this->statusBar()->showMessage("Could not execute the long action");
| |
| }
| |
| | |
| //...
| |
| }
| |
| | |
| void MainWindow::stopLongAction()
| |
| {
| |
| Action("org.kde.auth.example.longaction").stop();
| |
| }
| |
| | |
| void MainWindow::longActionPerformed(ActionReply reply)
| |
| {
| |
| //...
| |
| | |
| if (reply.succeded())
| |
| this->statusBar()->showMessage("Action succeded", 10000);
| |
| else
| |
| this->statusBar()->showMessage(QString("Could not execute the long action: %1").arg(reply.errorCode()), 10000);
| |
| }
| |
| </code>
| |
| | |
| 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.
| |
| | |
| Also, note that asyncronous actions may be stopped with ''Action::stop()''
| |
