Differential D18822 Diff 51593 src/kauthhelpersupport.h

Changeset View

Standalone View

View Options

src/kauthhelpersupport.h

Show All 17 Lines
18*/ 18​*/
19 19​
20#ifndef HELPER_SUPPORT_H 20​#ifndef HELPER_SUPPORT_H
21#define HELPER_SUPPORT_H 21​#define HELPER_SUPPORT_H
22 22​
23#include <QObject> 23​#include <QObject>
24#include <QVariant> 24​#include <QVariant>
25 25​
26#include <kauth_export.h> 26​#include <kauthcore_export.h>
27 27​
28#define KAUTH_HELPER_MAIN(ID, HelperClass) \ 28​#define KAUTH_HELPER_MAIN(ID, HelperClass) \
29 int main(int argc, char **argv) { return KAuth::HelperSupport::helperMain(argc, argv, ID, new HelperClass()); } 29​ int main(int argc, char **argv) { return KAuth::HelperSupport::helperMain(argc, argv, ID, new HelperClass()); }
30 30​
31namespace KAuth 31​namespace KAuth
32{ 32​{
33 33​
34/** 34​/**
35 * @brief Support class with some KAUTH_EXPORT methods useful to the helper's code 35​ * @brief Support class with some KAUTHCORE_EXPORT methods useful to the helper's code
36 * 36​ *
37 * This class provides the API to write the helper tool that executes your actions. 37​ * This class provides the API to write the helper tool that executes your actions.
38 * You don't create instances of HelperSupport. Instead, you use its KAUTH_EXPORT methods. 38​ * You don't create instances of HelperSupport. Instead, you use its KAUTHCORE_EXPORT methods.
39 * 39​ *
40 * This them you can notify the application of progress in your action's execution 40​ * This them you can notify the application of progress in your action's execution
41 * and you can check if the application asked you to terminate it. 41​ * and you can check if the application asked you to terminate it.
42 * 42​ *
43 * @since 4.4 43​ * @since 4.4
44 */ 44​ */
45namespace HelperSupport 45​namespace HelperSupport
46{ 46​{
47/** 47​/**
48 * @brief Send a progressStep signal to the caller application 48​ * @brief Send a progressStep signal to the caller application
49 * 49​ *
50 * You can use this method to notify progress information about the 50​ * You can use this method to notify progress information about the
51 * action execution. When you call this method, the KAuth::ExecuteJob 51​ * action execution. When you call this method, the KAuth::ExecuteJob
52 * object associated with the current action will emit the KJob::percent(KJob*, unsigned long) 52​ * object associated with the current action will emit the KJob::percent(KJob*, unsigned long)
53 * signal. The meaning of the integer passed here is totally application dependent, 53​ * signal. The meaning of the integer passed here is totally application dependent,
54 * but you'll want to use it as a sort of percentage. 54​ * but you'll want to use it as a sort of percentage.
55 * If you need to be more expressive, use the other overload which takes a QVariantMap 55​ * If you need to be more expressive, use the other overload which takes a QVariantMap
56 * 56​ *
57 * @param step The progress indicator 57​ * @param step The progress indicator
58 */ 58​ */
59KAUTH_EXPORT void progressStep(int step); 59​KAUTHCORE_EXPORT void progressStep(int step);
60 60​
61/** 61​/**
62* @brief Send a progressStep signal to the caller application 62​* @brief Send a progressStep signal to the caller application
63* 63​*
64* You can use this method to notify progress information about the 64​* You can use this method to notify progress information about the
65* action execution. When you call this method, the KAuth::ExecuteJob 65​* action execution. When you call this method, the KAuth::ExecuteJob
66* object associated with the current action will emit the progressStep(QVariantMap) 66​* object associated with the current action will emit the progressStep(QVariantMap)
67* signal. The meaning of the data passed here is totally application dependent. 67​* signal. The meaning of the data passed here is totally application dependent.
68* 68​*
69* If you only need a simple percentage value, use the other overload which takes an int. 69​* If you only need a simple percentage value, use the other overload which takes an int.
70* 70​*
71* @param data The progress data 71​* @param data The progress data
72*/ 72​*/
73KAUTH_EXPORT void progressStep(const QVariantMap &data); 73​KAUTHCORE_EXPORT void progressStep(const QVariantMap &data);
74 74​
75/** 75​/**
76 * @brief Check if the caller asked the helper to stop the execution 76​ * @brief Check if the caller asked the helper to stop the execution
77 * 77​ *
78 * This method will return true if the helper has been asked to stop the 78​ * This method will return true if the helper has been asked to stop the
79 * execution of the current action. If this happens, your helper should 79​ * execution of the current action. If this happens, your helper should
80 * return (NOT exit). The meaning of the data you return in this case is 80​ * return (NOT exit). The meaning of the data you return in this case is
81 * application-dependent. 81​ * application-dependent.
82 * 82​ *
83 * It's good practice to check it regularly if you have a long-running action 83​ * It's good practice to check it regularly if you have a long-running action
84 * 84​ *
85 * @see ExecuteJob::kill 85​ * @see ExecuteJob::kill
86 * @return true if the helper has been asked to stop, false otherwise 86​ * @return true if the helper has been asked to stop, false otherwise
87 */ 87​ */
88KAUTH_EXPORT bool isStopped(); 88​KAUTHCORE_EXPORT bool isStopped();
89 89​
90/** 90​/**
91 * @brief Method that implements the main function of the helper tool. Do not call directly 91​ * @brief Method that implements the main function of the helper tool. Do not call directly
92 * 92​ *
93 * This method is called in the proper way by the code generated by the KAUTH_HELPER_MAIN(), 93​ * This method is called in the proper way by the code generated by the KAUTH_HELPER_MAIN(),
94 * which creates a main() function for the helper tool. 94​ * which creates a main() function for the helper tool.
95 * macro. You shouldn't call this method directly. 95​ * macro. You shouldn't call this method directly.
96 * 96​ *
97 * @param argc The argc parameter from the main() function. 97​ * @param argc The argc parameter from the main() function.
98 * @param argv The argv parameter from the main() function. 98​ * @param argv The argv parameter from the main() function.
99 * @param id The helper ID as passed to the macro 99​ * @param id The helper ID as passed to the macro
100 * @param responder The responder object for the helper. The macro passes a default-constructed, 100​ * @param responder The responder object for the helper. The macro passes a default-constructed,
101 * heap-allocated object of the class specified as the last macro parameter 101​ * heap-allocated object of the class specified as the last macro parameter
102 */ 102​ */
103KAUTH_EXPORT int helperMain(int argc, char **argv, const char *id, QObject *responder); 103​KAUTHCORE_EXPORT int helperMain(int argc, char **argv, const char *id, QObject *responder);
104} // namespace HelperSupport 104​} // namespace HelperSupport
105 105​
106} // namespace Auth 106​} // namespace Auth
107 107​
108#endif 108​#endif