tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

stream_list_priv.h (4280B)

      1 /*
      2 * stream_list_priv.h
      3 *
      4 * list of SRTP streams, keyed by SSRC
      5 *
      6 * Alba Mendez
      7 */
      8 /*
      9 *
     10 * Copyright (c) 2001-2017, Cisco Systems, Inc.
     11 * Copyright (c) 2022, Dolby Laboratories, Inc.
     12 * All rights reserved.
     13 *
     14 * Redistribution and use in source and binary forms, with or without
     15 * modification, are permitted provided that the following conditions
     16 * are met:
     17 *
     18 *   Redistributions of source code must retain the above copyright
     19 *   notice, this list of conditions and the following disclaimer.
     20 *
     21 *   Redistributions in binary form must reproduce the above
     22 *   copyright notice, this list of conditions and the following
     23 *   disclaimer in the documentation and/or other materials provided
     24 *   with the distribution.
     25 *
     26 *   Neither the name of the Cisco Systems, Inc. nor the names of its
     27 *   contributors may be used to endorse or promote products derived
     28 *   from this software without specific prior written permission.
     29 *
     30 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     31 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     32 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
     33 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
     34 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
     35 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     36 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     37 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     38 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     39 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
     40 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
     41 * OF THE POSSIBILITY OF SUCH DAMAGE.
     42 *
     43 */
     44 
     45 #ifndef SRTP_STREAM_LIST_PRIV_H
     46 #define SRTP_STREAM_LIST_PRIV_H
     47 
     48 #include "srtp_priv.h"
     49 
     50 #ifdef __cplusplus
     51 extern "C" {
     52 #endif
     53 
     54 /**
     55 * srtp_stream_list_t holds a list of srtp_stream_t, each identified
     56 * by their SSRC.
     57 *
     58 * the API was extracted to allow downstreams to override its
     59 * implementation by defining the `SRTP_NO_STREAM_LIST` preprocessor
     60 * directive, which removes the default implementation of these
     61 * functions. if this is done, the `next` & `prev` fields are free for
     62 * the implementation to use.
     63 *
     64 * this is still an internal interface; there is no stability
     65 * guarantee--downstreams should watch this file for changes in
     66 * signatures or semantics.
     67 */
     68 
     69 /**
     70 * allocate and initialize a stream list instance
     71 */
     72 srtp_err_status_t srtp_stream_list_alloc(srtp_stream_list_t *list_ptr);
     73 
     74 /**
     75 * deallocate a stream list instance
     76 *
     77 * the list must be empty or else an error is returned.
     78 */
     79 srtp_err_status_t srtp_stream_list_dealloc(srtp_stream_list_t list);
     80 
     81 /**
     82 * insert a stream into the list
     83 *
     84 * returns srtp_err_status_alloc_fail if insertion failed due to unavailable
     85 * capacity in the list. if operation succeeds, srtp_err_status_ok is returned
     86 *
     87 * if another stream with the same SSRC already exists in the list,
     88 * behavior is undefined. if the SSRC field is mutated while the
     89 * stream is inserted, further operations have undefined behavior
     90 */
     91 srtp_err_status_t srtp_stream_list_insert(srtp_stream_list_t list,
     92                                          srtp_stream_t stream);
     93 
     94 /*
     95 * look up the stream corresponding to the specified SSRC and return it.
     96 * if no such SSRC is found, NULL is returned.
     97 */
     98 srtp_stream_t srtp_stream_list_get(srtp_stream_list_t list, uint32_t ssrc);
     99 
    100 /**
    101 * remove the stream from the list.
    102 *
    103 * The stream to be removed is referenced "by value", i.e., by the pointer to be
    104 * removed from the list. This pointer is obtained using `srtp_stream_list_get`
    105 * or as callback parameter in `srtp_stream_list_for_each`.
    106 */
    107 void srtp_stream_list_remove(srtp_stream_list_t list, srtp_stream_t stream);
    108 
    109 /**
    110 * iterate through all stored streams. while iterating, it is allowed to delete
    111 * the current element; any other mutation to the list is undefined behavior.
    112 * returning non-zero from callback aborts the iteration.
    113 */
    114 void srtp_stream_list_for_each(srtp_stream_list_t list,
    115                               int (*callback)(srtp_stream_t, void *),
    116                               void *data);
    117 
    118 #ifdef __cplusplus
    119 }
    120 #endif
    121 
    122 #endif /* SRTP_STREAM_LIST_PRIV_H */