refactor(swarm)!: deprecate PollParameters where possible (#3153)

This patch deprecates 3 out of 4 functions on `PollParameters`:

- `local_peer_id`
- `listened_addresses`
- `external_addresses`

The addresses can be obtained by inspecting the `FromSwarm` event. To make this easier, we introduce two utility structs in `libp2p-swarm`:

- `ExternalAddresses`
- `ListenAddresses`

A node's `PeerId` is always known to the caller, thus we can require them to pass it in.

Related: #3124.

swarm/src/behaviour.rs

@@ -19,8 +19,13 @@
 // DEALINGS IN THE SOFTWARE.
 
 mod either;
+mod external_addresses;
+mod listen_addresses;
 pub mod toggle;
 
+pub use external_addresses::ExternalAddresses;
+pub use listen_addresses::ListenAddresses;
+
 use crate::dial_opts::DialOpts;
 use crate::handler::{ConnectionHandler, IntoConnectionHandler};
 use crate::{AddressRecord, AddressScore, DialError};
@@ -402,12 +407,24 @@ pub trait PollParameters {
     fn supported_protocols(&self) -> Self::SupportedProtocolsIter;
 
     /// Returns the list of the addresses we're listening on.
+    #[deprecated(
+        since = "0.42.0",
+        note = "Use `libp2p_swarm::ListenAddresses` instead."
+    )]
     fn listened_addresses(&self) -> Self::ListenedAddressesIter;
 
     /// Returns the list of the addresses nodes can use to reach us.
+    #[deprecated(
+        since = "0.42.0",
+        note = "Use `libp2p_swarm::ExternalAddresses` instead."
+    )]
     fn external_addresses(&self) -> Self::ExternalAddressesIter;
 
     /// Returns the peer id of the local node.
+    #[deprecated(
+        since = "0.42.0",
+        note = "Pass the node's `PeerId` into the behaviour instead."
+    )]
     fn local_peer_id(&self) -> &PeerId;
 }