Line data Source code
1 : /**
2 : * @file
3 : *
4 : * @brief Access plugin handle.
5 : *
6 : * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
7 : */
8 :
9 : #ifdef HAVE_KDBCONFIG_H
10 : #include "kdbconfig.h"
11 : #endif
12 :
13 : #include <kdbassert.h>
14 : #include <kdbinternal.h>
15 :
16 :
17 : /**
18 : * @brief Allows one to Export Methods for a Plugin.
19 : *
20 : * This function must be called within ELEKTRA_PLUGIN_EXPORT.
21 : * It define the plugin's methods that will be exported.
22 : *
23 : * All KDB methods implemented by the plugin basically could
24 : * have random names (convention is elektraName*), except
25 : * ELEKTRA_PLUGIN_EXPORT.
26 : *
27 : * This is the single symbol that will be looked up
28 : * when loading the plugin, and the first method of the backend
29 : * implementation that will be called.
30 : *
31 : * You need to use a macro so that both dynamic and static loading
32 : * of the plugin works. For example for the doc plugin:
33 : * @snippet doc.c export
34 : *
35 : * The first parameter is the name of the plugin.
36 : * Then every plugin should have:
37 : * @c ELEKTRA_PLUGIN_OPEN,
38 : * @c ELEKTRA_PLUGIN_CLOSE,
39 : * @c ELEKTRA_PLUGIN_GET,
40 : * @c ELEKTRA_PLUGIN_SET and optionally
41 : * @c ELEKTRA_PLUGIN_ERROR and
42 : * @c ELEKTRA_PLUGIN_COMMIT.
43 : *
44 : * The list is terminated with
45 : * @c ELEKTRA_PLUGIN_END.
46 : *
47 : * You must use static "char arrays" in a read only segment.
48 : * Don't allocate storage, it won't be freed.
49 : *
50 : * @param pluginName the name of this plugin
51 : * @return an object that contains all plugin information needed by
52 : * libelektra.so
53 : * @ingroup plugin
54 : */
55 169593 : Plugin * elektraPluginExport (const char * pluginName, ...)
56 : {
57 : va_list va;
58 : Plugin * returned;
59 169593 : plugin_t method = 0;
60 :
61 169593 : if (pluginName == 0) return 0;
62 :
63 169593 : returned = elektraCalloc (sizeof (struct _Plugin));
64 :
65 : /* Start processing parameters */
66 169593 : va_start (va, pluginName);
67 169593 : returned->name = pluginName;
68 :
69 1081191 : while ((method = va_arg (va, plugin_t)))
70 : {
71 742005 : switch (method)
72 : {
73 : case ELEKTRA_PLUGIN_OPEN:
74 134257 : returned->kdbOpen = va_arg (va, kdbOpenPtr);
75 134257 : break;
76 : case ELEKTRA_PLUGIN_CLOSE:
77 131055 : returned->kdbClose = va_arg (va, kdbClosePtr);
78 131055 : break;
79 : case ELEKTRA_PLUGIN_GET:
80 169593 : returned->kdbGet = va_arg (va, kdbGetPtr);
81 169593 : break;
82 : case ELEKTRA_PLUGIN_SET:
83 169053 : returned->kdbSet = va_arg (va, kdbSetPtr);
84 169053 : break;
85 : case ELEKTRA_PLUGIN_ERROR:
86 80020 : returned->kdbError = va_arg (va, kdbErrorPtr);
87 80020 : break;
88 : case ELEKTRA_PLUGIN_COMMIT:
89 58027 : returned->kdbCommit = va_arg (va, kdbCommitPtr);
90 58027 : break;
91 : default:
92 0 : ELEKTRA_ASSERT (0, "plugin passed something unexpected");
93 : // fallthrough, will end here
94 : case ELEKTRA_PLUGIN_END:
95 0 : va_end (va);
96 0 : return returned;
97 : }
98 : }
99 : return returned;
100 : }
101 :
102 :
103 : /**
104 : * @brief Returns the configuration of that plugin.
105 : *
106 : * - The user/ config holds plugin specific configuration
107 : * - The system/ config holds backend specific configuration
108 : *
109 : * So prefer cascading lookups to honor both.
110 : *
111 : * @param handle a pointer to the plugin
112 : * @ingroup plugin
113 : * @return keyset to the configuration for that plugin
114 : */
115 166676 : KeySet * elektraPluginGetConfig (Plugin * handle)
116 : {
117 166676 : return handle->config;
118 : }
119 :
120 : /**
121 : * @brief Store a pointer to any plugin related data.
122 : *
123 : * @see elektraPluginGetData
124 : * @param plugin a pointer to the plugin
125 : * @param data the pointer to the data
126 : * @ingroup plugin
127 : */
128 267471 : void elektraPluginSetData (Plugin * plugin, void * data)
129 : {
130 267471 : plugin->data = data;
131 267471 : }
132 :
133 : /**
134 : * @brief Get a pointer to any plugin related data stored before.
135 : *
136 : * If elektraPluginSetData() was not called earlier, NULL will be returned.
137 : *
138 : * @see elektraPluginSetData
139 : * @param plugin a pointer to the plugin
140 : * @return a pointer to the data
141 : * @ingroup plugin
142 : */
143 263447 : void * elektraPluginGetData (Plugin * plugin)
144 : {
145 263447 : return plugin->data;
146 : }
147 :
148 : /**
149 : * @brief Get a pointer to the global keyset.
150 : *
151 : * Initialized for all plugins by the KDB, except for manually
152 : * created plugins with `elektraPluginOpen()`.
153 : * The global keyset is tied to a KDB handle, initialized on
154 : * `kdbOpen()` and deleted on `kdbClose()`.
155 : *
156 : * Plugins using this keyset are responsible for cleaning up
157 : * their parts of the keyset which they do not need any more.
158 : *
159 : * @param plugin a pointer to the plugin
160 : * @return a pointer to the global keyset
161 : * @ingroup plugin
162 : */
163 42169 : KeySet * elektraPluginGetGlobalKeySet (Plugin * plugin)
164 : {
165 42169 : return plugin->global;
166 : }
|