setup should take a SetupOptions

CHANGELOG.md

@@ -3,6 +3,8 @@
 *   BREAKING: remove deprecated `retina::client::Session<Playing>::teardown` and
     `retina::client::Demuxed::teardown`; made private some items already
     `#[doc(hidden)]`.
+*   BREAKING: `retina::client::Session<Described>::setup` takes a new
+    `SetupOptions` argument for future expansion.
 
 ## `v0.3.9` (2022-04-12)
 

benches/client.rs

@@ -8,7 +8,10 @@ use std::{io::ErrorKind, net::SocketAddr, num::NonZeroU32};
 use bytes::Bytes;
 use criterion::{criterion_group, criterion_main, Criterion, Throughput};
 use futures::StreamExt;
-use retina::{client::PlayOptions, codec::CodecItem};
+use retina::{
+    client::{PlayOptions, SetupOptions},
+    codec::CodecItem,
+};
 use std::convert::TryFrom;
 use tokio::io::AsyncWriteExt;
 use url::Url;
@@ -111,7 +114,7 @@ async fn read_to_eof(addr: SocketAddr) {
         retina::client::Session::describe(url, retina::client::SessionOptions::default())
             .await
             .unwrap();
-    session.setup(0).await.unwrap();
+    session.setup(0, SetupOptions::default()).await.unwrap();
     let session = session
         .play(PlayOptions::default())
         .await

examples/client/mp4.rs

@@ -22,7 +22,7 @@ use bytes::{Buf, BufMut, BytesMut};
 use futures::{Future, StreamExt};
 use log::{debug, info, warn};
 use retina::{
-    client::Transport,
+    client::{SetupOptions, Transport},
     codec::{AudioParameters, CodecItem, Parameters, VideoParameters},
 };
 
@@ -766,7 +766,7 @@ pub async fn run(opts: Opts) -> Result<(), Error> {
         None
     };
     if let Some(i) = video_stream_i {
-        session.setup(i).await?;
+        session.setup(i, SetupOptions::default()).await?;
     }
     let audio_stream = if !opts.no_audio {
         let s = session
@@ -795,7 +795,7 @@ pub async fn run(opts: Opts) -> Result<(), Error> {
         None
     };
     if let Some((i, _)) = audio_stream {
-        session.setup(i).await?;
+        session.setup(i, SetupOptions::default()).await?;
     }
     if video_stream_i.is_none() && audio_stream.is_none() {
         bail!("Exiting because no video or audio stream was selected; see info log messages above");

examples/client/onvif.rs

@@ -4,7 +4,7 @@
 use anyhow::{anyhow, Error};
 use futures::StreamExt;
 use log::{error, info};
-use retina::client::SessionGroup;
+use retina::client::{SessionGroup, SetupOptions};
 use retina::codec::CodecItem;
 use std::sync::Arc;
 
@@ -40,7 +40,9 @@ async fn run_inner(opts: Opts, session_group: Arc<SessionGroup>) -> Result<(), E
         .iter()
         .position(|s| matches!(s.parameters(), Some(retina::codec::Parameters::Message(..))))
         .ok_or_else(|| anyhow!("couldn't find onvif stream"))?;
-    session.setup(onvif_stream_i).await?;
+    session
+        .setup(onvif_stream_i, SetupOptions::default())
+        .await?;
     let mut session = session
         .play(retina::client::PlayOptions::default().ignore_zero_seq(true))
         .await?

src/client/mod.rs

@@ -562,6 +562,14 @@ impl SessionOptions {
     }
 }
 
+/// Per-stream options decided for `SETUP` time, for future expansion.
+///
+/// There's nothing here yet. Likely in the future this will allow configuring
+/// the output format for H.264 (Annex B or not).
+#[derive(Default)]
+#[non_exhaustive]
+pub struct SetupOptions {}
+
 /// Options which must be decided at `PLAY` time.
 ///
 /// These are mostly adjustments for non-compliant server implementations.
@@ -1296,7 +1304,8 @@ impl Session<Described> {
     /// inspect that first.
     ///
     /// Panics if `stream_i >= self.streams().len()`.
-    pub async fn setup(&mut self, stream_i: usize) -> Result<(), Error> {
+    pub async fn setup(&mut self, stream_i: usize, options: SetupOptions) -> Result<(), Error> {
+        let _ = options; // not yet used.
         let inner = &mut self.0.as_mut().project();
         let presentation = &mut inner.presentation;
         let options = &inner.options;
@@ -1313,8 +1322,8 @@ impl Session<Described> {
             .as_ref()
             .unwrap_or(&presentation.control)
             .clone();
-        let mut req = rtsp_types::Request::builder(Method::Setup, rtsp_types::Version::V1_0)
-            .request_uri(url);
+        let mut req =
+            rtsp_types::Request::builder(Method::Setup, rtsp_types::Version::V1_0).request_uri(url);
         match options.transport {
             Transport::Tcp => {
                 let proposed_channel_id = conn.channels.next_unassigned().ok_or_else(|| {
@@ -2402,7 +2411,7 @@ mod tests {
         // SETUP.
         tokio::join!(
             async {
-                session.setup(0).await.unwrap();
+                session.setup(0, SetupOptions::default()).await.unwrap();
             },
             req_response(
                 &mut server,
@@ -2512,7 +2521,7 @@ mod tests {
         // SETUP.
         tokio::join!(
             async {
-                session.setup(0).await.unwrap();
+                session.setup(0, SetupOptions::default()).await.unwrap();
             },
             req_response(
                 &mut server,
@@ -2664,7 +2673,7 @@ mod tests {
         // SETUP.
         tokio::join!(
             async {
-                session.setup(0).await.unwrap();
+                session.setup(0, SetupOptions::default()).await.unwrap();
             },
             req_response(
                 &mut server,