| 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 |