Hello community, here is the log from the commit of package kauth for openSUSE:Factory checked in at 2014-04-02 17:21:46 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Comparing /work/SRC/openSUSE:Factory/kauth (Old) and /work/SRC/openSUSE:Factory/.kauth.new (New) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "kauth" Changes: -------- --- /work/SRC/openSUSE:Factory/kauth/kauth.changes 2014-03-10 12:18:29.000000000 +0100 +++ /work/SRC/openSUSE:Factory/.kauth.new/kauth.changes 2014-04-02 17:21:48.000000000 +0200 @@ -1,0 +2,9 @@ +Sat Mar 29 19:47:21 UTC 2014 - [email protected] + +- Update to 4.98.0 + * API improvements and cleanups + * Buildsystem fixes + * For more details please see: + http://www.kde.org/announcements/announce-frameworks5-beta1.php + +------------------------------------------------------------------- Old: ---- kauth-4.97.0.tar.xz New: ---- kauth-4.98.0.tar.xz ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Other differences: ------------------ ++++++ kauth.spec ++++++ --- /var/tmp/diff_new_pack.Tng0uz/_old 2014-04-02 17:21:49.000000000 +0200 +++ /var/tmp/diff_new_pack.Tng0uz/_new 2014-04-02 17:21:49.000000000 +0200 @@ -18,10 +18,10 @@ %define lname libKF5Auth5 Name: kauth -Version: 4.97.0 +Version: 4.98.0 Release: 0 BuildRequires: cmake >= 2.8.12 -BuildRequires: extra-cmake-modules >= 0.0.11 +BuildRequires: extra-cmake-modules >= 0.0.12 BuildRequires: fdupes BuildRequires: kcoreaddons-devel >= %{_kf5_version} BuildRequires: kf5-filesystem ++++++ kauth-4.97.0.tar.xz -> kauth-4.98.0.tar.xz ++++++ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/kauth-4.97.0/CMakeLists.txt new/kauth-4.98.0/CMakeLists.txt --- old/kauth-4.97.0/CMakeLists.txt 2014-03-01 12:50:07.000000000 +0100 +++ new/kauth-4.98.0/CMakeLists.txt 2014-03-28 19:16:05.000000000 +0100 @@ -2,7 +2,7 @@ project(KAuth) -find_package(ECM 0.0.11 REQUIRED NO_MODULE) +find_package(ECM 0.0.12 REQUIRED NO_MODULE) set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${ECM_KDE_MODULE_DIR}) set(REQUIRED_QT_VERSION 5.2.0) @@ -22,7 +22,7 @@ include(ECMSetupVersion) include(ECMGenerateHeaders) -set(KF5_VERSION "4.97.0") +set(KF5_VERSION "4.98.0") ecm_setup_version(${KF5_VERSION} VARIABLE_PREFIX KAUTH VERSION_HEADER "${CMAKE_CURRENT_BINARY_DIR}/kauth_version.h" diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/kauth-4.97.0/README.md new/kauth-4.98.0/README.md --- old/kauth-4.97.0/README.md 2014-03-01 12:50:07.000000000 +0100 +++ new/kauth-4.98.0/README.md 2014-03-28 19:16:05.000000000 +0100 @@ -40,5 +40,5 @@ - Home page: <https://projects.kde.org/projects/frameworks/kauth> - Mailing list: <https://mail.kde.org/mailman/listinfo/kde-frameworks-devel> -- IRC channel: #kde-devel on Freenode +- IRC channel: \#kde-devel on Freenode - Git repository: <https://projects.kde.org/projects/frameworks/kauth/repository> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/kauth-4.97.0/src/Messages.sh new/kauth-4.98.0/src/Messages.sh --- old/kauth-4.97.0/src/Messages.sh 1970-01-01 01:00:00.000000000 +0100 +++ new/kauth-4.98.0/src/Messages.sh 2014-03-28 19:16:05.000000000 +0100 @@ -0,0 +1,18 @@ +#!/bin/sh + +# Invoke the extractrc script on all .ui, .rc, and .kcfg files in the sources. +# The results are stored in a pseudo .cpp file to be picked up by xgettext. +lst=`find . -name \*.rc -o -name \*.ui -o -name \*.kcfg` +if [ -n "$lst" ] ; then + $EXTRACTRC $lst >> rc.cpp +fi + +# If your framework contains tips-of-the-day, call preparetips as well. +if [ -f "data/tips" ] ; then + ( cd data && $PREPARETIPS > ../tips.cpp ) +fi + +# Extract strings from all source files. +# If your framework depends on KI18n, use $XGETTEXT. If it uses Qt translation +# system, use $EXTRACT_TR_STRINGS. +$EXTRACT_TR_STRINGS `find . -name \*.cpp -o -name \*.h -name \*.qml` -o $podir/kauth5.pot diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/kauth-4.97.0/src/kauthactionreply.h new/kauth-4.98.0/src/kauthactionreply.h --- old/kauth-4.97.0/src/kauthactionreply.h 2014-03-01 12:50:07.000000000 +0100 +++ new/kauth-4.98.0/src/kauthactionreply.h 2014-03-28 19:16:05.000000000 +0100 @@ -32,59 +32,107 @@ @namespace KAuth @section kauth_intro Introduction - The KDE Authorization API allows developers to write desktop applications that run high-privileged tasks in an easy, secure and cross-platform way. Previously, if an application had to do administrative tasks, - it had to be run as root, using mechanisms such as sudo or graphical equivalents, or by setting the executable's setuid bit. This approach has some drawbacks. For example, the whole application code, - including GUI handling and network communication, had to be done as root. More code that runs as root means more possible security holes. - - The solution is the caller/helper pattern. With this pattern, the privileged code is isolated in a small helper tool that runs as root. This tool includes only the few lines of code that actually - need to be run with privileges, not the whole application logic. All the other parts of the application are run as a normal user, and the helper tool is called when needed, using a secure mechanism that - ensures that the user is authorized to do so. This pattern is not very easy to implement, because the developer has to deal with a lot of details about how to authorize the user, how to call the helper - with the right privileges, how to exchange data with the helper, etc.. This is where the new KDE Authorization API becomes useful. Thanks to this new library, every developer can implement the - caller/helper pattern to write application that require high privileges, with a few lines of code in an easy, secure and cross-platform way. - Not only: the library can also be used to lock down some actions in your application without using a helper but just checking for authorization and verifying if the user is allowed to perform it. + The KDE Authorization API allows developers to write desktop applications that + run high-privileged tasks in an easy, secure and cross-platform way. + Previously, if an application had to do administrative tasks, it had to be run + as root, using mechanisms such as sudo or graphical equivalents, or by setting + the executable's setuid bit. This approach has some drawbacks. For example, the + whole application code, including GUI handling and network communication, had + to be done as root. More code that runs as root means more possible security + holes. + + The solution is the caller/helper pattern. With this pattern, the privileged + code is isolated in a small helper tool that runs as root. This tool includes + only the few lines of code that actually need to be run with privileges, not + the whole application logic. All the other parts of the application are run as + a normal user, and the helper tool is called when needed, using a secure + mechanism that ensures that the user is authorized to do so. This pattern is + not very easy to implement, because the developer has to deal with a lot of + details about how to authorize the user, how to call the helper with the right + privileges, how to exchange data with the helper, etc.. This is where the new + KDE Authorization API becomes useful. Thanks to this new library, every + developer can implement the caller/helper pattern to write application that + require high privileges, with a few lines of code in an easy, secure and + cross-platform way. + + Not only: the library can also be used to lock down some actions in your + application without using a helper but just checking for authorization and + verifying if the user is allowed to perform it. + + The KDE Authorization library uses different backends depending on the system + where it's built. As far as the user authorization is concerned, it currently + uses PolicyKit on linux and Authorization Services on Mac OSX, and a Windows + backend will eventually be written, too. At the communication layer, the + library uses D-Bus on every supported platform. - The KDE Authorization library uses different backends depending on the system where it's built. As far as the user authorization is concerned, it currently uses PolicyKit on linux and Authorization Services - on Mac OSX, and a Windows backend will eventually be written, too. At the communication layer, the library uses D-Bus on every supported platform. @section kauth_concepts Concepts - There are a few concepts to understand when using the library. Much of those are carried from underlying APIs such as PolicyKit, so if you know something about them there shouldn't be problems. - An <i>action</i> is a single task that needs to be done by the application. You refer to an action using an action identifier, which is a string in reverse domain name syntax (to avoid duplicates). For - example, if the date/time control center module needs to change the date, it would need an action like "org.kde.datatime.change". If your application has to perform more than one privileged task, you - should configure more than one action. This allows system administrators to fine tune the policies that allow users to perform your actions. - - The <i>authorization</i> is the process that is executed to decide if a user can perform an action or not. In order to execute the helper as root, the user has to be authorized. For example, on linux, - che policykit backend will look at the policykit policy database to see what requirements the user has to meet in order to execute the action you requested. The policy set for that action could allow - or deny that user, or could say the user has to authenticate in order to gain the authorization. - - The <i>authentication</i> is the process that allows the system to know that the person is in front of the console is who he says to be. If an action can be allowed or not depending on the user's identity, - it has to be proved by entering a password or any other identification data the system requires. + There are a few concepts to understand when using the library. Much of those + are carried from underlying APIs such as PolicyKit, so if you know something + about them there shouldn't be problems. + + An <i>action</i> is a single task that needs to be done by the application. You + refer to an action using an action identifier, which is a string in reverse + domain name syntax (to avoid duplicates). For example, if the date/time control + center module needs to change the date, it would need an action like + "org.kde.datatime.change". If your application has to perform more than one + privileged task, you should configure more than one action. This allows system + administrators to fine tune the policies that allow users to perform your + actions. + + The <i>authorization</i> is the process that is executed to decide if a user + can perform an action or not. In order to execute the helper as root, the user + has to be authorized. For example, on linux, che policykit backend will look at + the policykit policy database to see what requirements the user has to meet in + order to execute the action you requested. The policy set for that action could + allow or deny that user, or could say the user has to authenticate in order to + gain the authorization. + + The <i>authentication</i> is the process that allows the system to know that + the person is in front of the console is who he says to be. If an action can be + allowed or not depending on the user's identity, it has to be proved by + entering a password or any other identification data the system requires. A typical session with the authorization API is like this: - The user want to perform some privileged task - The application asks the system if the user is authorized. - The system asks the user to authenticate, if needed, and reply the application. - - The application uses some system-provided mechanism to execute the helper's code as the root user. Previously, you had to set the setuid bit to do this, but we have something cool called + - The application uses some system-provided mechanism to execute the helper's + code as the root user. Previously, you had to set the setuid bit to do this, + but we have something cool called "dbus activation" that doesn't require the setuid bit and is much more flexible. - - The helper code, immediately after starting, checks if the caller is authorized to do what it asks. If not the helper immediately exits! + - The helper code, immediately after starting, checks if the caller is + authorized to do what it asks. If not the helper immediately exits! - If the caller is authorized, the helper executes the task and exits. - The application receives data back from the helper. - All these steps are managed by the library. Following sections will focus on how to write the helper to implement your actions and how to call the helper from the application. + All these steps are managed by the library. Following sections will focus on + how to write the helper to implement your actions and how to call the helper + from the application. @section kauth_helper Writing the helper tool - The first thing you need to do before writing anything is to decide what actions you need to implement. Every action needs to be identified by a string in the reverse domain name syntax. This helps to - avoid duplicates. An example of action id is "org.kde.datetime.change" or "org.kde.ksysguard.killprocess". Action names can only contain lowercase letters and dots (not as the first or last char). - You also need an identifier for your helper. An application using the KDE auth api can implement and use more than one helper, implementing different actions. An helper is uniquely identified in the - system context with a string. It, again, is in reverse domain name syntax to avoid duplicates. A common approach is to call the helper like the common prefix of your action names. - For example, the Date/Time kcm module could use a helper called "org.kde.datetime", to perform actions like "org.kde.datetime.changedate" and "org.kde.datetime.changetime". This naming convention - simplifies the implementation of the helper. - - From the code point of view, the helper is implemented as a QObject subclass. Every action is implemented by a public slot. In the example/ directory in the source code tree you find a complete example. - Let's look at that. - The helper.h file declares the class that implements the helper. It looks like: + The first thing you need to do before writing anything is to decide what + actions you need to implement. Every action needs to be identified by a string + in the reverse domain name syntax. This helps to avoid duplicates. An example + of action id is "org.kde.datetime.change" or "org.kde.ksysguard.killprocess". + Action names can only contain lowercase letters and dots (not as the first or + last char). You also need an identifier for your helper. An application using + the KDE auth api can implement and use more than one helper, implementing + different actions. An helper is uniquely identified in the system context with + a string. It, again, is in reverse domain name syntax to avoid duplicates. A + common approach is to call the helper like the common prefix of your action + names. For example, the Date/Time kcm module could use a helper called + "org.kde.datetime", to perform actions like "org.kde.datetime.changedate" and + "org.kde.datetime.changetime". This naming convention simplifies the + implementation of the helper. + + From the code point of view, the helper is implemented as a QObject subclass. + Every action is implemented by a public slot. In the example/ directory in the + source code tree you find a complete example. Let's look at that. The + helper.h file declares the class that implements the helper. It looks like: @code #include <kauth.h> @@ -102,14 +150,23 @@ }; @endcode - The slot names are the last part of the action name, without the helper's ID if it's a prefix, with all the dots replaced by underscores. In this case, the helper ID is "org.kde.kf5auth.example", so those - three slots implement the actions "org.kde.kf5auth.example.read", "org.kde.kf5auth.example.write" and "org.kde.kf5auth.example.longaction". The helper ID doesn't have to appear at the beginning of the action - name, but it's good practice. If you want to extend MyHelper to implement also a different action like "org.kde.datetime.changetime", since the helper ID doesn't match you'll have to implement a - slot called org_kde_datetime_changetime(). - - The slot's signature is fixed: the return type is ActionReply, a class that allows you to return results, error codes and custom data to the application when your action has finished to run. - Please note that due to QMetaObject being picky about namespaces, you NEED to declare the return type as ActionReply and not KAuth::ActionReply. So the using declaration is compulsory - The QVariantMap object that comes as argument contains custom data coming from the application. + The slot names are the last part of the action name, without the helper's ID if + it's a prefix, with all the dots replaced by underscores. In this case, the + helper ID is "org.kde.kf5auth.example", so those three slots implement the + actions "org.kde.kf5auth.example.read", "org.kde.kf5auth.example.write" and + "org.kde.kf5auth.example.longaction". The helper ID doesn't have to appear at + the beginning of the action name, but it's good practice. If you want to extend + MyHelper to implement also a different action like + "org.kde.datetime.changetime", since the helper ID doesn't match you'll have to + implement a slot called org_kde_datetime_changetime(). + + The slot's signature is fixed: the return type is ActionReply, a class that + allows you to return results, error codes and custom data to the application + when your action has finished to run. Please note that due to QMetaObject + being picky about namespaces, you NEED to declare the return type as + ActionReply and not KAuth::ActionReply. So the using declaration is compulsory + The QVariantMap object that comes as argument contains custom data coming from + the application. Let's look at the read action implementation. Its purpose is to read files: @@ -135,46 +192,65 @@ } @endcode - First, the code creates a default reply object. The default constructor creates a reply that reports success. Then it gets the filename parameter from the argument QVariantMap, that has previously been - set by the application, before calling the helper. If it fails to open the file, it creates an ActionReply object that notifies that some error has happened in the helper, then set the error code to - that returned by QFile and returns. If there is no error, it reads the file. The contents are put into the reply.data() object, which is another QVariantMap. It will be sent back to the application - with the reply. - - Because this class will be compiled into a standalone executable, we need a main() function and some code to initialize everything: you don't have to write it. Instead, you use the - KAUTH_HELPER_MAIN() macro that will take care of everything. It's used like this: + First, the code creates a default reply object. The default constructor creates + a reply that reports success. Then it gets the filename parameter from the + argument QVariantMap, that has previously been set by the application, before + calling the helper. If it fails to open the file, it creates an ActionReply + object that notifies that some error has happened in the helper, then set the + error code to that returned by QFile and returns. If there is no error, it + reads the file. The contents are put into the reply.data() object, which is + another QVariantMap. It will be sent back to the application with the reply. + + Because this class will be compiled into a standalone executable, we need a + main() function and some code to initialize everything: you don't have to write + it. Instead, you use the KAUTH_HELPER_MAIN() macro that will take care of + everything. It's used like this: @code KAUTH_HELPER_MAIN("org.kde.kf5auth.example", MyHelper) @endcode - The first parameter is the string containing the helper identifier. Please note that you need to use this same string in the application's code to tell the library which helper to call, so please - stay away from typos, because we don't have any way to detect them. The second parameter is the name of the helper's class. - Your helper, if complex, can be composed of a lot of source files, but the important thing is to include this macro in one at least one of them. + The first parameter is the string containing the helper identifier. Please note + that you need to use this same string in the application's code to tell the + library which helper to call, so please stay away from typos, because we don't + have any way to detect them. The second parameter is the name of the helper's + class. Your helper, if complex, can be composed of a lot of source files, but + the important thing is to include this macro in one at least one of them. - To build the helper, KDE macros provide a function named kauth_install_helper_files(). Use it in your cmake file like this: + To build the helper, KDE macros provide a function named + kauth_install_helper_files(). Use it in your cmake file like this: @code - kde4_add_executable(<helper_target> your sources...) + add_executable(<helper_target> your sources...) target_link_libraries(<helper_target> your libraries...) install(TARGETS <helper_target> DESTINATION ${LIBEXEC_INSTALL_DIR}) kauth_install_helper_files(<helper_target> <helper_id> <user>) @endcode - The first argument is the cmake target name for the helper executable, which you have to build and install separately. Make sure to INSTALL THE HELPER IN ${LIBEXEC_INSTALL_DIR}, - otherwise kauth_install_helper_files will not work. The second argument is the - helper id. Please be sure to don't misspell it, and to not quote it. The user parameter is the user that the helper has to be run as. It usually is root, but some actions could require less strict - permissions, so you should use the right user where possible (for example the user apache if you have to mess with apache settings). Note that the target created by this macro already links to - libkauth and QtCore + The first argument is the cmake target name for the helper executable, which + you have to build and install separately. Make sure to INSTALL THE HELPER IN + ${LIBEXEC_INSTALL_DIR}, otherwise kauth_install_helper_files will not work. The + second argument is the helper id. Please be sure to don't misspell it, and to + not quote it. The user parameter is the user that the helper has to be run as. + It usually is root, but some actions could require less strict permissions, so + you should use the right user where possible (for example the user apache if + you have to mess with apache settings). Note that the target created by this + macro already links to libkauth and QtCore @section kauth_actions Action registration - To be able to authorize the actions, they have to be added to the policy database. To do this in a cross-platform way, we provide a cmake macro. It looks like: + + To be able to authorize the actions, they have to be added to the policy + database. To do this in a cross-platform way, we provide a cmake macro. It + looks like: @code - kde4_install_auth_actions(<helper_id> <actions definition file>) + kauth_install_actions(<helper_id> <actions definition file>) @endcode - The action definition file describes which actions are implemented by your code and which default security options they should have. It is a common text file in ini format, with one section for - each action and some parameters. The definition for the read action is: + The action definition file describes which actions are implemented by your code + and which default security options they should have. It is a common text file + in ini format, with one section for each action and some parameters. The + definition for the read action is: @verbatim [org.kde.kf5auth.example.read] @@ -184,31 +260,49 @@ Persistence=session @endverbatim - The name parameter is a text describing the action for <i>who reads the file</i>. The description parameter is the message shown to the user in the authentication dialog. It should be a finite phrase. - The policy attribute specify the default rule that the user must satisfy to be authorized. Possible values are: + The name parameter is a text describing the action for <i>who reads the + file</i>. The description parameter is the message shown to the user in the + authentication dialog. It should be a finite phrase. The policy attribute + specify the default rule that the user must satisfy to be authorized. Possible + values are: - yes: the action should be always allowed - no: the action should be always denied - auth_self: the user should authenticate as itself - auth_admin: the user should authenticate as an administrator user - The persistence attribute is optional. It says how long an authorization should be retained for that action. The values could be: + The persistence attribute is optional. It says how long an authorization should + be retained for that action. The values could be: - session: the authorization persists until the user logs-out - always: the authorization will persist indefinitely @section kauth_app Calling the helper from the application - Once the helper is ready, we need to call it from the main application. In the example's mainwindow.cpp you can see how this is done. To create a reference to an action, an object of type Action has to - be created. Every Action object refers to an action by its action id. Two objects with the same action id will act on the same action. - With an Action object, you can authorize and execute the action. To execute an action you have a couple of choices: - - A synchronous call, using the Action::execute() method, will start the helper, execute the action and return the reply. - - An asynchronous call, by setting Action::setExecutesAsync(true) and calling ::execute(), will start the helper and return immediately. - - The asynchronous call is the most flexible alternative, but you need a way to obtain the reply. This is done by connecting to a signal, but the Action class is not a QObject subclass. Instead, you connect - to signals exposed by the ActionWatcher class. For every action id you use, there is one ActionWatcher object. You can retrieve it using the Action::watcher() method. If you execute an action using - Action::executeAsync(), you can connect to the actionPerformed(ActionReply) signal to be notified when the action has been completed (or failed). As a parameter, you'll get a reply object containing - all the data you need. As a convenience, you can also pass an object and a slot to the executeAsync() method to directly connect them to the signal, if you don't want to mess with watchers. - - The piece of code that calls the action of the previous example is located in example/mainwindow.cpp in the on_readAction_triggered() slot. It looks like this: + Once the helper is ready, we need to call it from the main application. In the + example's mainwindow.cpp you can see how this is done. To create a reference to + an action, an object of type Action has to be created. Every Action object + refers to an action by its action id. Two objects with the same action id will + act on the same action. With an Action object, you can authorize and execute + the action. To execute an action you have a couple of choices: + - A synchronous call, using the Action::execute() method, will start the + helper, execute the action and return the reply. + - An asynchronous call, by setting Action::setExecutesAsync(true) and calling + Action::execute(), will start the helper and return immediately. + + The asynchronous call is the most flexible alternative, but you need a way to + obtain the reply. This is done by connecting to a signal, but the Action class + is not a QObject subclass. Instead, you connect to signals exposed by the + ActionWatcher class. For every action id you use, there is one ActionWatcher + object. You can retrieve it using the Action::watcher() method. If you execute + an action using Action::executeAsync(), you can connect to the + actionPerformed(ActionReply) signal to be notified when the action has been + completed (or failed). As a parameter, you'll get a reply object containing all + the data you need. As a convenience, you can also pass an object and a slot to + the executeAsync() method to directly connect them to the signal, if you don't + want to mess with watchers. + + The piece of code that calls the action of the previous example is located in + example/mainwindow.cpp in the on_readAction_triggered() slot. It looks like + this: @code QVariantMap args; args["filename"] = filename; @@ -223,18 +317,32 @@ contents = reply.data()["contents"].toString(); @endcode - First of all, it creates the action object specifying the action id. Then it loads the filename (we want to read a forbidden file) into the arguments() QVariantMap, which will be directly passed to the - helper in the read() slot's parameter. This example code uses a synchronous call to execute the action and retrieve the reply. If the reply succeeded, the reply data is retrieved from the returned QVariantMap - object. Please note that, although the execute() method will return only when the action is completed, the GUI will remain responsive because an internal event loop is entered. This means you should be - prepared to receive other events in the meanwhile. Also, notice that you have to explicitly set the helper ID to the action: this is done for added safety, to prevent the caller from accidentally invoking - a helper, and also because KAuth actions may be used without a helper attached (the default). In this case, action.execute() will return ActionSuccess if the authentication went well. This is quite useful - if you want your user to authenticate before doing something, which however needs no privileged permissions implementation-wise. + First of all, it creates the action object specifying the action id. Then it + loads the filename (we want to read a forbidden file) into the arguments() + QVariantMap, which will be directly passed to the helper in the read() slot's + parameter. This example code uses a synchronous call to execute the action and + retrieve the reply. If the reply succeeded, the reply data is retrieved from + the returned QVariantMap object. Please note that, although the execute() + method will return only when the action is completed, the GUI will remain + responsive because an internal event loop is entered. This means you should be + prepared to receive other events in the meanwhile. Also, notice that you have + to explicitly set the helper ID to the action: this is done for added safety, + to prevent the caller from accidentally invoking a helper, and also because + KAuth actions may be used without a helper attached (the default). In this + case, action.execute() will return ActionSuccess if the authentication went + well. This is quite useful if you want your user to authenticate before doing + something, which however needs no privileged permissions implementation-wise. + @section kauth_async Asynchronous calls, data reporting, and action termination - For a more advanced example, we look at the action "org.kde.kf5auth.example.longaction" in the example helper. This is an action that takes a long time to execute, so we need some features: - - The helper needs to regularly send data to the application, to inform about the execution status. - - The application needs to be able to stop the action execution if the user stops it or close the application. + For a more advanced example, we look at the action + "org.kde.kf5auth.example.longaction" in the example helper. This is an action + that takes a long time to execute, so we need some features: + - The helper needs to regularly send data to the application, to inform about + the execution status. + - The application needs to be able to stop the action execution if the user + stops it or close the application. The example code follows: @code ActionReply MyHelper::longaction(QVariantMap args) @@ -249,16 +357,27 @@ } @endcode - In this example, the action is only waiting a "long" time using a loop, but we can see some interesting line. The progress status is sent to the application using the HelperSupport::progressStep() method. - When this method is called, the ActionWatcher associated with this action will emit the progressStep() signal, reporting back the data to the application. There are two overloads of these methods and - corresponding signals. The one used here takes an integer. Its meaning is application dependent, so you can use it as a sort of percentage. The other overload takes a QVariantMap object that is directly - passed to the app. In this way, you can report to the application all the custom data you want. - - In this example code, the loop exits when the HelperSupport::isStopped() returns true. This happens when the application calls the stop() method on the correponding action object. The stop() method, this - way, asks the helper to stop the action execution. It's up to the helper to obbey to this request, and if it does so, it should return from the slot, _not_ exit. - - The code that calls the action in the application connects a slot to the actionPerformed() signal and then call executeAsync(). The progressStep() signal is directly connected to a QProgressBar, and - the Stop button in the UI is connected to a slot that calls the Action::stop() method. + In this example, the action is only waiting a "long" time using a loop, but we + can see some interesting line. The progress status is sent to the application + using the HelperSupport::progressStep() method. When this method is called, + the ActionWatcher associated with this action will emit the progressStep() + signal, reporting back the data to the application. There are two overloads of + these methods and corresponding signals. The one used here takes an integer. + Its meaning is application dependent, so you can use it as a sort of + percentage. The other overload takes a QVariantMap object that is directly + passed to the app. In this way, you can report to the application all the + custom data you want. + + In this example code, the loop exits when the HelperSupport::isStopped() + returns true. This happens when the application calls the stop() method on the + correponding action object. The stop() method, this way, asks the helper to + stop the action execution. It's up to the helper to obbey to this request, and + if it does so, it should return from the slot, _not_ exit. + + The code that calls the action in the application connects a slot to the + actionPerformed() signal and then call executeAsync(). The progressStep() + signal is directly connected to a QProgressBar, and the Stop button in the UI + is connected to a slot that calls the Action::stop() method. @code void MainWindow::on_longAction_triggered() @@ -292,28 +411,41 @@ } @endcode - Please pay attention that when you call an action, the helper will be busy executing that action. Therefore, you can't call two execute() methods in sequence like that: + Please pay attention that when you call an action, the helper will be busy + executing that action. Therefore, you can't call two execute() methods in + sequence like that: @code action1.execute(); action2.execute(); @endcode - If you do, you'll get a HelperBusy reply from the second action. - A solution would be to launch the second action from the slot connected to the first's actionPerformed signal, but this would be very ugly. Read further to know how to solve this problem. + If you do, you'll get a HelperBusy reply from the second action. A solution + would be to launch the second action from the slot connected to the first's + actionPerformed signal, but this would be very ugly. Read further to know how + to solve this problem. @section kauth_other Other features - To allow to easily execute several actions in sequence, you can execute them in a group. This means using the Action::executeActions() static method, which takes a list of actions and asks the helper - to execute them with a single request. The helper will execute the actions in the specified order. All the signals will be emitted from the watchers associated with each action. - - Sometimes the application needs to know when a particular action has started to execute. For this purpose, you can connect to the actionStarted() signal. It is emitted immediately before the helper's - slot is called. This isn't very useful if you call execute(), but if you use executeActions() it lets you know when individual actions in the group are started. - - It doesn't happen very frequently that you code something that doesn't require some debugging, and you'll need some tool, even a basic one, to debug your helper code as well. For this reason, the - KDE Authorization library provides a message handler for the Qt debugging system. This means that every call to qDebug() & co. will be reported to the application, and printed using the same qt debugging - system, with the same debug level. - If, in the helper code, you write something like: + To allow to easily execute several actions in sequence, you can execute them in + a group. This means using the Action::executeActions() static method, which + takes a list of actions and asks the helper to execute them with a single + request. The helper will execute the actions in the specified order. All the + signals will be emitted from the watchers associated with each action. + + Sometimes the application needs to know when a particular action has started to + execute. For this purpose, you can connect to the actionStarted() signal. It is + emitted immediately before the helper's slot is called. This isn't very useful + if you call execute(), but if you use executeActions() it lets you know when + individual actions in the group are started. + + It doesn't happen very frequently that you code something that doesn't require + some debugging, and you'll need some tool, even a basic one, to debug your + helper code as well. For this reason, the KDE Authorization library provides a + message handler for the Qt debugging system. This means that every call to + qDebug() & co. will be reported to the application, and printed using the same + qt debugging system, with the same debug level. If, in the helper code, you + write something like: @code qDebug() << "I'm in the helper"; @endcode @@ -323,7 +455,8 @@ Debug message from the helper: I'm in the helper @endverbatim - Remember that the debug level is preserved, so if you use qFatal() you won't only abort the helper (which isn't suggested anyway), but also the application. + Remember that the debug level is preserved, so if you use qFatal() you won't + only abort the helper (which isn't suggested anyway), but also the application. */ namespace KAuth @@ -332,37 +465,42 @@ class ActionReplyData; /** -* @brief Class that encapsulates a reply coming from the helper after executing an action +* @brief Class that encapsulates a reply coming from the helper after executing +* an action * -* An instance of ActionReply is returned every time you execute an action with the Action -* class. You get the reply directly from the Action::execute() method or indirectly as -* a parameter of the ActionWatcher::actionPerformed() signal. +* An instance of ActionReply is returned every time you execute an action with +* the Action class. You get the reply directly from the Action::execute() method +* or indirectly as a parameter of the ActionWatcher::actionPerformed() signal. * -* ActionReply objects can contain both data from a successful action or an error indicator. -* In case of success, the errorCode() is ActionReply::NoError (zero) and the type() is -* ActionReply::Success. The data() method returns a QVariantMap object that may contain -* custom data sent back by the helper. +* ActionReply objects can contain both data from a successful action or an error +* indicator. In case of success, the errorCode() is ActionReply::NoError (zero) +* and the type() is ActionReply::Success. The data() method returns a +* QVariantMap object that may contain custom data sent back by the helper. * -* In case of errors coming from the library, the type() is ActionReply::KAuthError. In this -* case, errorCode() will always be one of the predefined errors from the ActionReply::Error enum. -* An error reply of KAuthError type always contains an empty data() object. For some kind of errors -* you could get a human-readable description with errorDescription(). +* In case of errors coming from the library, the type() is +* ActionReply::KAuthError. In this case, errorCode() will always be one of the +* predefined errors from the ActionReply::Error enum. An error reply of +* KAuthError type always contains an empty data() object. For some kind of +* errors you could get a human-readable description with errorDescription(). * -* If, instead, the helper itself has to report some errors occurred during the action execution, -* the type() will be (and has to be) ActionReply::HelperError. In this case the data() object can -* contain custom data from the helper, and the errorCode() and errorDescription() values are -* application-dependent. +* If, instead, the helper itself has to report some errors occurred during the +* action execution, the type() will be (and has to be) ActionReply::HelperError. +* In this case the data() object can contain custom data from the helper, and +* the errorCode() and errorDescription() values are application-dependent. * -* In the helper, to create an action reply object you have two choices: using the constructor, or -* the predefined replies. For example, to create a successful reply you can use the default constructor -* but to create a helper error reply, instead of writing <i>ActionReply(ActionReply::HelperError)</i> -* you could use the more convenient <i>ActionReply::HelperErrorReply</i> constant. +* In the helper, to create an action reply object you have two choices: using +* the constructor, or the predefined replies. For example, to create a +* successful reply you can use the default constructor but to create a helper +* error reply, instead of writing <i>ActionReply(ActionReply::HelperError)</i> +* you could use the more convenient <i>ActionReply::HelperErrorReply</i> +* constant. * -* You should not use the predefined error replies to create and return new errors. Replies with the -* KAuthError type are intended to be returned by the library only. However, you can use them for -* comparisons. +* You should not use the predefined error replies to create and return new +* errors. Replies with the KAuthError type are intended to be returned by the +* library only. However, you can use them for comparisons. * -* To quickly check for success or failure of an action, you can use succeeded() or failed(). +* To quickly check for success or failure of an action, you can use succeeded() +* or failed(). * * @since 4.4 */ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/kauth-4.97.0/src/kauthexecutejob.cpp new/kauth-4.98.0/src/kauthexecutejob.cpp --- old/kauth-4.97.0/src/kauthexecutejob.cpp 2014-03-01 12:50:07.000000000 +0100 +++ new/kauth-4.98.0/src/kauthexecutejob.cpp 2014-03-28 19:16:05.000000000 +0100 @@ -146,7 +146,7 @@ } else if (BackendsManager::authBackend()->capabilities() & KAuth::AuthBackend::AuthorizeFromHelperCapability) { if (!action.hasHelper()) { ActionReply r(ActionReply::InvalidActionReply()); - r.setErrorDescription(tr("The current backend only allows helper authorization, but this action does not have an helper.")); + r.setErrorDescription(tr("The current backend only allows helper authorization, but this action does not have a helper.")); actionPerformedSlot(action.name(), r); return; } -- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
