Development/Tutorials/KAuth/KCM HowTo

    From KDE TechBase
    Revision as of 12:54, 12 February 2010 by Drf (talk | contribs)


    Development/Tutorials/KAuth/KAuth Actions


    Creating a KCM requiring authorization upon saving
    Tutorial Series   KAuth Tutorial
    Previous   How to use KAuth Actions
    What's Next   reading=KCModule Namespace Reference
    Further Reading   n/a

    Introduction

    A very common use case for KAuth helper are KCModules, which sometimes need to obtain high privileges upon saving. For this reason, KAuth has been integrated into KCModule API and kcmshell's appearance, to grant developers an extremely easy way to deploy privileged KCMs, and at the same time a very consistent and usable interface to your users.

    This tutorial assumes you have a basic knowledge in creating KCModules.

    Creating a KCModule with KAuth

    The coding part is extremely easy, although this comes at the price of following some strict conventions, which also help KCM permission handling to stay consistent.

    Creating the save action

    The action name has to follow this format:

    org.kde.kcontrol.<modulename>.save
    

    Where <modulename> is the output of aboutData()->appName(), also known as the very first parameter you supply to KAboutData constructor.

    Following this format is compulsory to make the KCM work.

    Adding the needed code in your KCModule's constructor

    In your KCModule's constructor, supposing you created the action as described above, you have to do the following:

    setNeedsAuthorization(true);

    This function automatically does the following:

    • Creates the needed action
    • Crafts the Apply and Ok buttons (if any) into KPushButtons integrated with the action
    • Adds some visual elements to the KCM to notify the user about the status of the action (for example, if he needs to authenticate or if he's not authorized at all).

    So everything is done for you. The only requirement is that setNeedsAuthorization should be called after setAboutData and setButtons, otherwise it will fail.

    Adding the needed code to the save() function

    To save your module, here's what needs to be done in the save() function of your KCM:

    void MyKCM::save() {

     QVariantMap helperargs;
     // Populate....
    
     Action *action = authAction();
     action->setArguments(helperargs);
    
     ActionReply reply = action->execute();
    
     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...
       }
     }
    

    }

    The only difference you'll find with what you are used to do when executing KAuth Actions is the authAction() method. This method belongs to KCModule's API and returns the action internally created by setNeedsAuthorization(true), or 0 if no action was created.

    This action is already associated to the correct helper (see below) and ready to be executed: you just have to supply any additional arguments to it.

    Creating the helper

    You should already know how to create a KAuth helper, so this part won't be covered here. There are, however, some strict requirements to the helper format, just like for the action name.

    • The helper id must be org.kde.kcontrol.<modulename>, just like in the action
    • The helper must implement the save action, but can also implement any other actions (for example, some KCMs require privileges when loading as well: you still can do it in the same helper)

    =CMake and additional macros

    No additional macros are needed, except the ones already shown to build the helper.

    Conclusion

    As you have seen, there are almost no differences with a KCM not requiring high privileges, especially when deploying and building the module. In fact, porting a module requiring high privileges to KAuth is extremely easy and strongly advised, both for security and consistency, since your user will be provided with a better and more integrated overall experience.