Debian Codegraph @

docs/rst/scripting/lua_api/lua_core_api.rst

raw
1 .. _lua_core_api:
2
3 Core
4 ====
5
6 The :ref:`WpCore <core_api>` API is mostly transparent to lua, as the core
7 object is not exposed to the scripts.
8
9 For some functionality, though, the following static functions are exposed.
10
11 .. function:: Core.get_properties()
12
13 Binds :c:func:`wp_core_get_properties`
14
15 Returns a table with the properties of the core. These are the same
16 properties that appear on WirePlumber's *client* object in the PipeWire
17 global registry.
18
19 :returns: the properties of the core
20 :rtype: table
21
22 .. function:: Core.get_info()
23
24 Returns a table with information about the core. The table contains
25 the following fields:
26
27 =========== ===========
28 Field Contains
29 =========== ===========
30 cookie The value of :c:func:`wp_core_get_remote_cookie`
31 name The value of :c:func:`wp_core_get_remote_name`
32 user_name The value of :c:func:`wp_core_get_remote_user_name`
33 host_name The value of :c:func:`wp_core_get_remote_host_name`
34 version The value of :c:func:`wp_core_get_remote_version`
35 properties The value of :c:func:`wp_core_get_remote_properties`
36 =========== ===========
37
38 :returns: information about the core
39 :rtype: table
40
41 .. function:: Core.idle_add(callback)
42
43 Binds :c:func:`wp_core_idle_add_closure`
44
45 Schedules to call *callback* the next time that the event loop will be idle
46
47 :param function callback: the function to call; the function takes no
48 arguments and must return true/false, as it is a GSourceFunc:
49 return true to have the event loop call it again the next time it is idle,
50 false to stop calling it and remove the associated GSource
51 :returns: the GSource associated with this idle callback
52 :rtype: GSource, see :func:`GSource.destroy`
53
54 .. function:: Core.timeout_add(timeout_ms, callback)
55
56 Binds :c:func:`wp_core_timeout_add_closure`
57
58 Schedules to call *callback* after *timeout_ms* milliseconds
59
60 :param function callback: the function to call; the function takes no
61 arguments and must return true/false, as it is a GSourceFunc:
62 return true to have the event loop call it again periodically every
63 *timeout_ms* milliseconds, false to stop calling it and remove the
64 associated GSource
65 :returns: the GSource associated with this idle callback
66 :rtype: GSource, see :func:`GSource.destroy`
67
68 .. function:: GSource.destroy(self)
69
70 For the purpose of working with :func:`Core.idle_add` and
71 :func:`Core.timeout_add`, the GSource object that is returned by those
72 functions contains this method.
73
74 Call this method to destroy the source, so that the associated callback
75 is not called again. This can be used to stop a repeating timer callback
76 or just to abort some idle operation
77
78 This method binds *g_source_destroy*
79
80 .. function:: Core.sync(callback)
81
82 Binds :c:func:`wp_core_sync`
83
84 Calls *callback* after synchronizing the transaction state with PipeWire
85
86 :param function callback: a function to be called after syncing with PipeWire;
87 the function takes one argument that will be an error string, if something
88 went wrong and nil otherwise and returns nothing
89
90 .. function:: Core.quit()
91
92 Quits the current *wpexec* process
93
94 .. note::
95
96 This can only be called when the script is running in *wpexec*;
97 if it is running in the main WirePlumber daemon, it will print
98 a warning and do nothing
99
100 .. function:: Core.require_api(..., callback)
101
102 Ensures that the specified API plugins are loaded.
103
104 API plugins are plugins that provide some API extensions for use in scripts.
105 These plugins must always have their name end in "-api" and the names
106 specified here must not have the "-api" extension.
107
108 For instance, the "mixer-api" module provides an API to change volume/mute
109 controls from scripts, via action signals. It can be used like this:
110
111 .. code-block:: lua
112
113 Core.require_api("mixer", function(mixer)
114 -- get the volume of node 35
115 local volume = mixer:call("get-volume", 35)
116
117 -- the return value of "get-volume" is a GVariant(a{sv}),
118 -- which gets translated to a Lua table
119 Debug.dump_table(volume)
120 end)
121
122 See also the example in :func:`GObject.call`
123
124 .. note::
125
126 This can only be called when the script is running in *wpexec*;
127 if it is running in the main WirePlumber daemon, it will print
128 a warning and do nothing
129
130 :param strings ...: a list of string arguments, which specify the names of
131 the api plugins to load, if they are not already loaded
132 :param callback: the function to call after the plugins have been loaded;
133 this function takes references to the plugins as parameters
134
135 .. function:: Core.test_feature()
136
137 Binds :c:func:`wp_core_test_feature`
138
139 Tests if the specified feature is provided in the current WirePlumber
140 configuration.
141
142 :param string feature: the name of the feature to test
143 :returns: true if the feature is provided, false otherwise
144 :rtype: boolean