update upstream-2021-08-15

doc/messaging_api.txt

@@ -0,0 +1,49 @@
+Message API reference
+
+The message API allows any object within pulseaudio to register a message
+handler. A message handler is a function that can be called by clients using
+PA_COMMAND_SEND_OBJECT_MESSAGE. A message consists at least of an object path
+and a message command, both specified as strings. Additional parameters can
+be specified using a single string in JSON format, but are not mandatory.
+
+The message handler returns an error number as defined in def.h and also returns
+a string in the "response" variable. Non-empty response will be in JSON format.
+
+The reference further down lists available messages, their parameters
+and return values.
+
+Reference:
+
+Object path: /core
+Message: list-handlers
+Parameters: None
+Return value: JSON array of handler description objects
+    [{"name":"Handler name","description":"Description"} ...]
+
+Object path: /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez
+Message: list-codecs
+Parameters: None
+Return value: JSON array of codec description objects
+    [{"name":"codec1","description":"Codec 1"} ...]
+
+Object path: /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez
+Message: get-codec
+Parameters: None
+Return value: "codec name"
+
+Object path: /card/bluez_card.XX_XX_XX_XX_XX_XX/bluez
+Message: switch-codec
+Parameters: "codec name"
+Return value: none
+
+Description: Set if card profile selection should be sticky instead of being automated
+Object path: /card/<card_name>
+Message: set-profile-sticky
+Parameters: JSON "true" or "false"
+Return value: none
+
+Description: Get if card profile selection should be sticky instead of being automated
+Object path: /card/<card_name>
+Message: get-profile-sticky
+Parameters: None
+Return value: JSON "true" or "false"