reserveNetwork allows a requestor to initiate the creation of a network
that requires the system to preallocate resources which can then be
advertised by the requestor on or off device in order to help create the
network.
For example, this API will be used to reserve a IP over L2cap server
network, which requires the system to first create a
BluetoothServerSocket and reserve a PSM (i.e. port). This information is
passed back to the requestor via onReserved() callback and subsequently
advertised via a BLE advertisement. The network is established as soon
as the client connects to the advertised PSM, which will trigger a call
to onAvailable(), just like a regular NetworkRequest.
onReserved() callbacks are exclusive to the reserveNetwork API and are
sent when an NetworkOffer is registered that matches the reservation ID
of an existing request. A reserved offer always follows the reservation
request as it is created in direct response. onReserved() can only be
called once. If for some reason the reservation gets cancelled by the
system (i.e. the NetworkOffer is retracted) or cannot be fulfilled,
onUnavailable() is called. It is up to the app to file a new
NetworkRequest when this happens.
An onReserved() callback is not queued, because
a) it cannot be called more than once for the same reservation,
b) it must always be the first callback, and
c) it only gets cancelled by onUnavailable().
This change does not handle NetworkOffer migrations, such as updating
the score, properly. This must be addressed before the feature can ship
as the yieldToBadWifi logic can update the score on all NetworkOffers.
API-Coverage-Bug: 372936361
Test: Very basic CSNetworkReservationTest; more to follow.
Change-Id: I9b349d469830bf28e006cf403c605574371db267
73eee542a1