pipewire: document permissions needed for methods

src/pipewire/client.h

@@ -107,12 +107,16 @@ struct pw_client_methods {
 	 * \param id the global id to report the error on
 	 * \param res an errno style error code
 	 * \param message an error string
+	 *
+	 * This requires W and X permissions on the client.
 	 */
 	int (*error) (void *object, uint32_t id, int res, const char *message);
 	/**
 	 * Update client properties
 	 *
 	 * \param props new properties
+	 *
+	 * This requires W and X permissions on the client.
 	 */
 	int (*update_properties) (void *object, const struct spa_dict *props);
 
@@ -123,6 +127,8 @@ struct pw_client_methods {
 	 *
 	 * \param index the first index to query, 0 for first
 	 * \param num the maximum number of items to get
+	 *
+	 * This requires W and X permissions on the client.
 	 */
 	int (*get_permissions) (void *object, uint32_t index, uint32_t num);
 	/**
@@ -137,6 +143,8 @@ struct pw_client_methods {
 	 *
 	 * \param n_permissions number of permissions
 	 * \param permissions array of permissions
+	 *
+	 * This requires W and X permissions on the client.
 	 */
 	int (*update_permissions) (void *object, uint32_t n_permissions,
 			const struct pw_permission *permissions);

src/pipewire/core.h

@@ -225,6 +225,8 @@ struct pw_core_methods {
 	 * Start a conversation with the server. This will send
 	 * the core info and will destroy all resources for the client
 	 * (except the core and client resource).
+	 *
+	 * This requires X permissions on the core.
 	 */
 	int (*hello) (void *object, uint32_t version);
 	/**
@@ -237,6 +239,8 @@ struct pw_core_methods {
 	 * methods and the resulting events have been handled.
 	 *
 	 * \param seq the seq number passed to the done event
+	 *
+	 * This requires X permissions on the core.
 	 */
 	int (*sync) (void *object, uint32_t id, int seq);
 	/**
@@ -245,6 +249,8 @@ struct pw_core_methods {
 	 * Reply to the server ping event with the same seq.
 	 *
 	 * \param seq the seq number received in the ping event
+	 *
+	 * This requires X permissions on the core.
 	 */
 	int (*pong) (void *object, uint32_t id, int seq);
 	/**
@@ -259,9 +265,11 @@ struct pw_core_methods {
 	 * This method is usually also emitted on the resource object with
 	 * \a id.
 	 *
-         * \param id object where the error occurred
+         * \param id resource id where the error occurred
          * \param res error code
          * \param message error description
+	 *
+	 * This requires X permissions on the core.
 	 */
 	int (*error) (void *object, uint32_t id, int seq, int res, const char *message);
 	/**
@@ -271,6 +279,8 @@ struct pw_core_methods {
 	 * the global objects available from the PipeWire server
 	 * \param version the client version
 	 * \param user_data_size extra size
+	 *
+	 * This requires X permissions on the core.
 	 */
 	struct pw_registry * (*get_registry) (void *object, uint32_t version,
 			size_t user_data_size);
@@ -283,6 +293,8 @@ struct pw_core_methods {
 	 * \param version the version of the interface
 	 * \param props extra properties
 	 * \param user_data_size extra size
+	 *
+	 * This requires X permissions on the core.
 	 */
 	void * (*create_object) (void *object,
 			       const char *factory_name,
@@ -296,6 +308,8 @@ struct pw_core_methods {
 	 * Destroy the server resource for the given proxy.
 	 *
 	 * \param obj the proxy to destroy
+	 *
+	 * This requires X permissions on the core.
 	 */
 	int (*destroy) (void *object, void *proxy);
 };

src/pipewire/device.h

@@ -107,6 +107,8 @@ struct pw_device_methods {
 	 *
 	 * \param ids an array of param ids
 	 * \param n_ids the number of ids in \a ids
+	 *
+	 * This requires X permissions on the device.
 	 */
 	int (*subscribe_params) (void *object, uint32_t *ids, uint32_t n_ids);
 
@@ -121,6 +123,8 @@ struct pw_device_methods {
 	 * \param start the start index or 0 for the first param
 	 * \param num the maximum number of params to retrieve
 	 * \param filter a param filter or NULL
+	 *
+	 * This requires X permissions on the device.
 	 */
 	int (*enum_params) (void *object, int seq, uint32_t id, uint32_t start, uint32_t num,
 			    const struct spa_pod *filter);
@@ -130,6 +134,8 @@ struct pw_device_methods {
 	 * \param id the parameter id to set
 	 * \param flags extra parameter flags
 	 * \param param the parameter to set
+	 *
+	 * This requires W and X permissions on the device.
 	 */
 	int (*set_param) (void *object, uint32_t id, uint32_t flags,
 			  const struct spa_pod *param);

src/pipewire/extensions/metadata.h

@@ -58,12 +58,33 @@ struct pw_metadata_methods {
 			const struct pw_metadata_events *events,
 			void *data);
 
+	/**
+	 * Set a metadata property
+	 *
+	 * Automatically emit property events for the subject and key
+	 * when they are changed.
+	 *
+	 * \param subject the id of the global to associate the metadata
+	 *                with.
+	 * \param key the key of the metadata, NULL clears all metadata for
+	 *                the subject.
+	 * \param type the type of the metadata, this can be blank
+	 * \param value the metadata value. NULL clears the metadata.
+	 *
+	 * This requires X and W permissions on the metadata. It also
+	 * requires M permissions on the subject global.
+	 */
 	int (*set_property) (void *object,
 			uint32_t subject,
 			const char *key,
 			const char *type,
 			const char *value);
 
+	/**
+	 * Clear all metadata
+	 *
+	 * This requires X and W permissions on the metadata.
+	 */
 	int (*clear) (void *object);
 };
 

src/pipewire/extensions/session-manager/interfaces.h

@@ -97,6 +97,8 @@ struct pw_session_methods {
 	 *
 	 * \param ids an array of param ids
 	 * \param n_ids the number of ids in \a ids
+	 *
+	 * This requires X permissions.
 	 */
 	int (*subscribe_params) (void *object, uint32_t *ids, uint32_t n_ids);
 
@@ -111,6 +113,8 @@ struct pw_session_methods {
 	 * \param start the start index or 0 for the first param
 	 * \param num the maximum number of params to retrieve
 	 * \param filter a param filter or NULL
+	 *
+	 * This requires X permissions.
 	 */
 	int (*enum_params) (void *object, int seq,
 			uint32_t id, uint32_t start, uint32_t num,
@@ -122,6 +126,8 @@ struct pw_session_methods {
 	 * \param id the parameter id to set
 	 * \param flags extra parameter flags
 	 * \param param the parameter to set
+	 *
+	 * This requires X and W permissions.
 	 */
 	int (*set_param) (void *object, uint32_t id, uint32_t flags,
 			  const struct spa_pod *param);
@@ -199,6 +205,8 @@ struct pw_endpoint_methods {
 	 *
 	 * \param ids an array of param ids
 	 * \param n_ids the number of ids in \a ids
+	 *
+	 * This requires X permissions.
 	 */
 	int (*subscribe_params) (void *object, uint32_t *ids, uint32_t n_ids);
 
@@ -213,6 +221,8 @@ struct pw_endpoint_methods {
 	 * \param start the start index or 0 for the first param
 	 * \param num the maximum number of params to retrieve
 	 * \param filter a param filter or NULL
+	 *
+	 * This requires X permissions.
 	 */
 	int (*enum_params) (void *object, int seq,
 			uint32_t id, uint32_t start, uint32_t num,
@@ -224,10 +234,17 @@ struct pw_endpoint_methods {
 	 * \param id the parameter id to set
 	 * \param flags extra parameter flags
 	 * \param param the parameter to set
+	 *
+	 * This requires X and W permissions.
 	 */
 	int (*set_param) (void *object, uint32_t id, uint32_t flags,
 			  const struct spa_pod *param);
 
+	/**
+	 * Create a link
+	 *
+	 * This requires X permissions.
+	 */
 	int (*create_link) (void *object, const struct spa_dict *props);
 };
 
@@ -302,6 +319,8 @@ struct pw_endpoint_stream_methods {
 	 *
 	 * \param ids an array of param ids
 	 * \param n_ids the number of ids in \a ids
+	 *
+	 * This requires X permissions.
 	 */
 	int (*subscribe_params) (void *object, uint32_t *ids, uint32_t n_ids);
 
@@ -316,6 +335,8 @@ struct pw_endpoint_stream_methods {
 	 * \param start the start index or 0 for the first param
 	 * \param num the maximum number of params to retrieve
 	 * \param filter a param filter or NULL
+	 *
+	 * This requires X permissions.
 	 */
 	int (*enum_params) (void *object, int seq,
 			uint32_t id, uint32_t start, uint32_t num,
@@ -327,6 +348,8 @@ struct pw_endpoint_stream_methods {
 	 * \param id the parameter id to set
 	 * \param flags extra parameter flags
 	 * \param param the parameter to set
+	 *
+	 * This requires X and W permissions.
 	 */
 	int (*set_param) (void *object, uint32_t id, uint32_t flags,
 			  const struct spa_pod *param);
@@ -404,6 +427,8 @@ struct pw_endpoint_link_methods {
 	 *
 	 * \param ids an array of param ids
 	 * \param n_ids the number of ids in \a ids
+	 *
+	 * This requires X permissions.
 	 */
 	int (*subscribe_params) (void *object, uint32_t *ids, uint32_t n_ids);
 
@@ -418,6 +443,8 @@ struct pw_endpoint_link_methods {
 	 * \param start the start index or 0 for the first param
 	 * \param num the maximum number of params to retrieve
 	 * \param filter a param filter or NULL
+	 *
+	 * This requires X permissions.
 	 */
 	int (*enum_params) (void *object, int seq,
 			uint32_t id, uint32_t start, uint32_t num,
@@ -429,10 +456,17 @@ struct pw_endpoint_link_methods {
 	 * \param id the parameter id to set
 	 * \param flags extra parameter flags
 	 * \param param the parameter to set
+	 *
+	 * This requires X and W permissions.
 	 */
 	int (*set_param) (void *object, uint32_t id, uint32_t flags,
 			  const struct spa_pod *param);
 
+	/**
+	 * Request a state on the link.
+	 *
+	 * This requires X and W permissions.
+	 */
 	int (*request_state) (void *object, enum pw_endpoint_link_state state);
 };
 

src/pipewire/node.h

@@ -134,6 +134,8 @@ struct pw_node_methods {
 	 *
 	 * \param ids an array of param ids
 	 * \param n_ids the number of ids in \a ids
+	 *
+	 * This requires X permissions on the node.
 	 */
 	int (*subscribe_params) (void *object, uint32_t *ids, uint32_t n_ids);
 
@@ -148,6 +150,8 @@ struct pw_node_methods {
 	 * \param start the start index or 0 for the first param
 	 * \param num the maximum number of params to retrieve
 	 * \param filter a param filter or NULL
+	 *
+	 * This requires X permissions on the node.
 	 */
 	int (*enum_params) (void *object, int seq, uint32_t id,
 			uint32_t start, uint32_t num,
@@ -159,6 +163,8 @@ struct pw_node_methods {
 	 * \param id the parameter id to set
 	 * \param flags extra parameter flags
 	 * \param param the parameter to set
+	 *
+	 * This requires X and W permissions on the node.
 	 */
 	int (*set_param) (void *object, uint32_t id, uint32_t flags,
 			const struct spa_pod *param);
@@ -167,6 +173,8 @@ struct pw_node_methods {
 	 * Send a command to the node
 	 *
 	 * \param command the command to send
+	 *
+	 * This requires X and W permissions on the node.
 	 */
 	int (*send_command) (void *object, const struct spa_command *command);
 };

src/pipewire/port.h

@@ -117,6 +117,8 @@ struct pw_port_methods {
 	 *
 	 * \param ids an array of param ids
 	 * \param n_ids the number of ids in \a ids
+	 *
+	 * This requires X permissions on the port.
 	 */
 	int (*subscribe_params) (void *object, uint32_t *ids, uint32_t n_ids);
 
@@ -131,6 +133,8 @@ struct pw_port_methods {
 	 * \param start the start index or 0 for the first param
 	 * \param num the maximum number of params to retrieve
 	 * \param filter a param filter or NULL
+	 *
+	 * This requires X permissions on the port.
 	 */
 	int (*enum_params) (void *object, int seq,
 			uint32_t id, uint32_t start, uint32_t num,