Type now can assume the value "folder" so it is no longer necessary to
have Folder property, FolderType in introduced to provide the folder type
that before was on the Type itself.
In addition to this add proper documentation what properties are optional
and under what condition they are available.
This interface adds support for browsing and searching in the player's
storage using AVRCP 1.4/1.5.
Some remarks about the design:
- Exposing UIDCounter and UIDs was considered, but the spec seems to have
missed to define the player's id persistency. There are also the fact that
UIDCounter alone does not guarantee persistency across sessions and do not
provide what exact items have changed, so in the end exposing these
details will bring almost no value.
- Indexing or caching the whole media library is not recommended, Bluetooth
is too slow for that and even vendors such as Apple do not recommend doing
it, so the only items keep in cache are the current listed ones.
- Addressed vs Browsed player is done implicitly when accessed, this was done
to simplify the API and avoid confusions between applications and players.
This adds methods such as Play, Pause directly in MediaPlayer1, in
addition to that Track is now turn into a property to take advantage of
ObjectManager and document the interface as experimental.
Document the reported errors for Acquire() and TryAcquire(). For the
later, make sure a specific error in guaranteed for the typical scenario
of audio not streaming.
Split the Acquire() method in two parts so that the optional acquires,
formerly represented as a "?" flag in the accesstype parameter of
Acquire(), are now implemented in TryAcquire().
There is no known use-case making use of these access types and
therefore the Media API can be simplified.
From now on, the transport will always be acquired with read and write
access rights.
Acquiring a transport is needed in two different situations: either
we are initiating the audio stream locally, or the remote side initiated
it and thus we are just reacting. In the second case, we would expect
the stream is already available, and otherwise the operation should
fail. This means the media API needs to be extended in order to make
this difference.
This issue is specially relevant in the case of SCO, because the current
approach is racy. With HFP, for example (say BlueZ has the HS role), the
following race condition could be met:
1. Phone has an incoming call and thus starts in-band ringing.
2. SCO connection is accepted and stablished by BlueZ.
3. Gateway interface state is changed to Playing.
4. Exactly afterwards, the user routes the audio to the phone, to have
a private conversation. So the SCO link is closed.
5. In parallel, PulseAudio sees the transition to Playing, and acquires
the transport.
6. BlueZ receives an Acquire() request, but SCO is down. So it tries to
reconnect the SCO link.
The last step is an undesired behavior (the audio is routed back to the
car). BlueZ should be smart enough to know that the SCO connection
shouldn't be reestablished, but this is only possible if the endpoint
provides additional information in the media API.
Note that the API change introduced by this patch is backward
compatible, meaning that older versions of BlueZ will just ignore the
flag. So clients are encouraged to use it without necessarily adding a
dependency to newer versions of BlueZ.
Extend the Media API to expose the transport state in D-Bus, as a
property of the transport. This way the clients do not have to find
out which is the corresponding profile-specific interface for the
transport.
Additionally, this state along with the automatic release of transports
will allow clients to avoid the "optional release" or "accept remote
release" race condition. For example, with HSP/HFP profiles, the problem
is the following:
1. User suspends SCO in the remote end.
2. BlueZ signals the Playing->Connected state change in D-Bus.
3. Exactly afterwards, the user resumes SCO in the remote end.
4. In parallel, PulseAudio sees the aforementioned transition to
Connected, and thus releases the transport.
5. BlueZ receives a Release() request while SCO is up. So the audio
stream will be suspended.
The last step is an undesired behavior since the user explicitly wanted
to route the audio stream through Bluetooth.
The issue is difficult to reproduce but it can easily be solved by
exposing the transport state in D-Bus.
If we use the same hash table to set the new metadata, we have 2
undesired behaviors:
1) New track may contain fields from previous track if it didn't set all
the fields
2) If we fail on parsing the signal, we will still change some of the
fields
This should make Acquire blocking friendly since the client no longer has
to call GetProperties to discover how much it can write/read when using
the acquired file descriptor.
This makes simpler to application which are handling many endpoints
without a context data. It also may be useful in future in case we
allow multiple transports per endpoint.
