multiplex: Improve documentation

src/reception_flow.cc

@@ -633,12 +633,11 @@ void uvgrtp::reception_flow::increase_buffer_size(ssize_t next_write_index)
 
 bool uvgrtp::reception_flow::map_handler_key(uint32_t key, std::shared_ptr<std::atomic<std::uint32_t>> remote_ssrc)
 {
-    bool ret = false;
     if (handler_mapping_.find(key) == handler_mapping_.end()) {
         handler_mapping_[key] = remote_ssrc;
-        ret = true;
+        return true;
     }
-    return ret;
+    return false;
 }
 
 int uvgrtp::reception_flow::clear_stream_from_flow(std::shared_ptr<std::atomic<std::uint32_t>> remote_ssrc, uint32_t handler_key)

src/reception_flow.hh

@@ -154,11 +154,23 @@ namespace uvgrtp {
             uvgrtp::frame::rtp_frame *pull_frame();
             uvgrtp::frame::rtp_frame *pull_frame(ssize_t timeout_ms);
 
+            /* Map a packet handler key to a REMOTE SSRC of a stream
+             *
+             * Return true if a handler with the given key exists in the reception_flow -> mapping succesful
+             * Return false if there is no handler with this key -> no mapping is done */
+            bool map_handler_key(uint32_t key, std::shared_ptr<std::atomic<std::uint32_t>> remote_ssrc);
+
+            /* Clear the packet handlers associated with this handler key from the reception_flow
+             * Also clear the hooks associated with this remote_ssrc
+             * 
+             * Return 1 if the hooks and handlers were cleared and there is no hooks or handlers left in
+             * this reception_flow -> the flow can be safely deleted if wanted
+             * Return 0 if the hooks and handlers were removed but there is still others left in this reception_flow */
+            int clear_stream_from_flow(std::shared_ptr<std::atomic<std::uint32_t>> remote_ssrc, uint32_t handler_key);
+
             /// \cond DO_NOT_DOCUMENT
             void set_buffer_size(const ssize_t& value);
             void set_payload_size(const size_t& value);
-            bool map_handler_key(uint32_t key, std::shared_ptr<std::atomic<std::uint32_t>> remote_ssrc);
-            int clear_stream_from_flow(std::shared_ptr<std::atomic<std::uint32_t>> remote_ssrc, uint32_t handler_key);
             /// \endcond
 
         private:

src/socketfactory.hh

@@ -15,7 +15,19 @@ namespace uvgrtp {
     class rtcp_reader;
 
     /* This class keeps track of all the sockets that uvgRTP is using. 
-     * the "out" parameter because at that point it already contains all needed information. */
+     * Each socket will have either a reception_flow or an rtcp_reader depending on what the socket
+     * is used for. It is possible to multiplex several media streams into a single socket, and the 
+     * reception_flow of the socket will distribute packets to the correct receiving stream based on the
+     * SSRCs on the packets. 
+     * *Attention* : If you multiplex multiple media streams into a single socket, you *must* set their 
+     * REMOTE SSRCs via the RCC_REMOTE_SSRC context flag.
+     * The reception_flow looks at the SOURCE SSRC on the received packet and then checks, which local
+     * stream is supposed to receive packets from this remote source.
+     * If you have a separate socket for every stream, this does not need to be taken into account
+     * This is also true for RTCP: the rtcp_reader will distribute received packets depending on the 
+     * SSRCs in the packets
+     */
+    // TODO: currently RTCP sockets get both a reception_flow and an rtcp_reader. This is not necessary
 
     class socketfactory {