Debian Codegraph @

docs/rst/scripting/lua_api/lua_object_interest_api.rst

raw
1 .. _lua_object_interest_api:
2
3 Object Interest
4 ===============
5
6 The Interest object allows you to declare interest in a specific object, or
7 a set of objects, and filter them. This is used in the
8 :ref:`ObjectManager <lua_object_manager_api>` but also in other places where
9 methods allow you to iterate over a set of objects or lookup a specific object.
10
11 *Interest* is a binding of :c:struct:`WpObjectInterest`, but it uses a
12 Lua-idiomatic way of construction instead of mapping directly the C functions,
13 for convenience.
14
15 Construction
16 ~~~~~~~~~~~~
17
18 The most common use for *Interest* is in the
19 :ref:`ObjectManager <lua_object_manager_api>`, where you have to use the
20 following construction method to create it.
21
22 .. function:: Interest(decl)
23
24 :param table decl: an interest declaration
25 :returns: the interest
26 :rtype: Interest (:c:struct:`WpObjectInterest`)
27
28 The interest consists of a GType and an array of constraints. It is constructed
29 with a table that contains all the constraints, plus the GType in the ``type``
30 field.
31
32 .. code-block:: lua
33
34 local om = ObjectManager {
35 Interest {
36 type = "node",
37 Constraint { "node.name", "matches", "alsa*", type = "pw-global" },
38 Constraint { "media.class", "equals", "Audio/Sink", type = "pw-global" },
39 }
40 }
41
42 In the above example, the interest will match all objects of type
43 :c:struct:`WpNode` that contain the following 2 global properties:
44
45 - "node.name", with a value that begins with the string "alsa"
46 - "media.class", with a value that equals exactly the string "Audio/Sink"
47
48 When an object method requires an *Interest* as an argument, you may as well
49 directly pass the declaration table as argument instead of using the
50 :func:`Interest` constructor function. For instance,
51
52 .. code-block:: lua
53
54 local fl_port = node:lookup_port {
55 Constraint { "port.name", "equals", "playback_FL" }
56 }
57
58 In the above example, we lookup a port in a node. The :func:`Node.lookup_port`
59 method takes an *Interest* as an argument, but we can pass the interest
60 declaration table directly. Note also that such a method does not require
61 declaring the ``type`` of the interest, as it has :c:struct:`WpPort` as a
62 hardcoded default.
63
64 The type
65 ........
66
67 The type of an interest must be a valid GType, written as a string without the
68 "Wp" prefix and with the first letter optionally being lowercase. The type may
69 match any wireplumber object or interface.
70
71 Examples:
72
73 ============= ============
74 type string parsed as
75 ============= ============
76 node WpNode
77 Node WpNode
78 device WpDevice
79 plugin WpPlugin
80 siLink WpSiLink
81 SiLink WpSiLink
82 properties WpProperties
83 ============= ============
84
85 The Constraint
86 ..............
87
88 The *Constraint* is constructed also with a table, like *Interest* itself. This
89 table must have the following items in this very strict order:
90
91 - a subject string: a string that specifies the name of a property to match
92 - a verb string: a string that specifies the match operation
93 - an object, if the verb requires it
94
95 The verb may be any verb listed in :c:enum:`WpConstraintVerb`, using either
96 the nickname of the enum or the character value of it.
97
98 Allowed verbs:
99
100 ============ ========= =======================================
101 nickname character value
102 ============ ========= =======================================
103 "equals" "=" :c:enum:`WP_CONSTRAINT_VERB_EQUALS`
104 "not-equals" "!" :c:enum:`WP_CONSTRAINT_VERB_NOT_EQUALS`
105 "in-list" "c" :c:enum:`WP_CONSTRAINT_VERB_IN_LIST`
106 "in-range" "~" :c:enum:`WP_CONSTRAINT_VERB_IN_RANGE`
107 "matches" "#" :c:enum:`WP_CONSTRAINT_VERB_MATCHES`
108 "is-present" "+" :c:enum:`WP_CONSTRAINT_VERB_IS_PRESENT`
109 "is-absent" "-" :c:enum:`WP_CONSTRAINT_VERB_IS_ABSENT`
110 ============ ========= =======================================
111
112 The values that are expected for each verb are primarily documented in
113 :c:func:`wp_object_interest_add_constraint`. In Lua, though, native types are
114 expected instead of GVariant and then they are converted according to the rules
115 documented in the :ref:`GObject Integration <lua_gobject>` page.
116
117 Examples of constraints:
118
119 .. code-block:: lua
120
121 Constraint { "node.id", "equals", "42" }
122 Constraint { "node.id", "equals", 42 }
123 Constraint { "port.physical", "=", true }
124
125 Constraint { "audio.channel", "not-equals", "FL" }
126
127 Constraint { "node.name", "matches", "v4l2_input*" }
128 Constraint { "format.dsp", "#", "*mono audio*" }
129
130 -- matches either "default" or "settings" as a possible value for "metadata.name"
131 Constraint { "metadata.name", "in-list", "default", "settings" }
132
133 -- matches any priority.session between 0 and 1000, inclusive
134 Constraint { "priority.session", "in-range", 0, 1000 }
135
136 -- matches when the object has a "media.role" property
137 Constraint { "media.role", "is-present" }
138
139 -- matches when "media.role" is not present in the properties list
140 Constraint { "media.role", "is-absent" }
141
142 Constraint types
143 ................
144
145 PipeWire objects have multiple properties lists, therefore constraints also need
146 to have a way to specify on which property list they apply. The constraint type
147 may be any of the types listed in :c:enum:`WpConstraintType` and can be
148 specified with an additional field in the *Constraint* construction table,
149 called ``type``.
150
151 For instance:
152
153 .. code-block:: lua
154
155 Constraint { "node.id", "equals", "42", type = "pw-global" }
156 Constraint { "api.alsa.card.name", "matches", "*Intel*", type = "pw" }
157 Constraint { "bound-id", "=", 42, type = "gobject" }
158
159 Valid types are:
160
161 ========= ===============================================
162 type value
163 ========= ===============================================
164 pw-global :c:enum:`WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY`
165 pw :c:enum:`WP_CONSTRAINT_TYPE_PW_PROPERTY`
166 gobject :c:enum:`WP_CONSTRAINT_TYPE_G_PROPERTY`
167 ========= ===============================================
168
169 Methods
170 ~~~~~~~
171
172 .. function:: Interest.matches(self, obj)
173
174 Binds :c:func:`wp_object_interest_matches`
175
176 Checks if a specific object matches the interest. The object may be a GObject
177 or a table convertible to :c:struct:`WpProperties`, if the interest is for
178 properties.
179
180 This is rarely useful to use directly on objects, but it may be useful to
181 check if a specific table contains key-value pairs that match specific
182 constraints, using "properties" as the interest type and passing a table as
183 the object.
184
185 :param self: the interest
186 :param obj: an object to check for a match
187 :type obj: GObject or table
188 :returns: whether the object matches the interest
189 :rtype: boolean