Development/Tutorials/KAuth/KAuth Actions: Difference between revisions

    From KDE TechBase
    (Creating the page)
     
    mNo edit summary
     
    (26 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.

    Latest revision as of 23:37, 27 January 2024

    This tutorial was moved to develop.kde.org/docs/features/kauth/