1# API header files 2 3As a user of the WebRTC library, you may use headers and build files 4in the following directories: 5 6API directory | Including subdirectories? 7--------------|------------------------- 8`api` | Yes 9 10For now, you may also use headers and build files in the following 11legacy API directories—but see the 12[disclaimer](#legacy-disclaimer) below. 13 14Legacy API directory | Including subdirectories? 15-------------------------------------------|-------------------------- 16`common_audio/include` | No 17`media/base` | No 18`media/engine` | No 19`modules/audio_coding/include` | No 20`modules/audio_device/include` | No 21`modules/audio_processing/include` | No 22`modules/congestion_controller/include` | No 23`modules/include` | No 24`modules/rtp_rtcp/include` | No 25`modules/rtp_rtcp/source` | No 26`modules/utility/include` | No 27`modules/video_coding/codecs/h264/include` | No 28`modules/video_coding/codecs/vp8/include` | No 29`modules/video_coding/codecs/vp9/include` | No 30`modules/video_coding/include` | No 31`pc` | No 32`rtc_base` | No 33`system_wrappers/include` | No 34 35While the files, types, functions, macros, build targets, etc. in the 36API and legacy API directories will sometimes undergo incompatible 37changes, such changes will be announced in advance to 38[[email protected]][discuss-webrtc], and a migration 39path will be provided. 40 41[discuss-webrtc]: https://groups.google.com/forum/#!forum/discuss-webrtc 42 43In the directories not listed in the tables above, incompatible 44changes may happen at any time, and are not announced. 45 46## <a name="legacy-disclaimer"></a>The legacy API directories contain some things you shouldn’t use 47 48The legacy API directories, in addition to things that genuinely 49should be part of the API, also contain things that should *not* be 50part of the API. We are in the process of moving the good stuff to the 51`api` directory tree, and will remove directories from the legacy list 52once they no longer contain anything that should be in the API. 53 54In other words, if you find things in the legacy API directories that 55don’t seem like they belong in the WebRTC native API, 56don’t grow too attached to them. 57 58## All these worlds are yours—except Europa 59 60In the API headers, or in files included by the API headers, there are 61types, functions, namespaces, etc. that have `impl` or `internal` in 62their names (in various styles, such as `CamelCaseImpl`, 63`snake_case_impl`). They are not part of the API, and may change 64incompatibly at any time; do not use them. 65 66# Preprocessor macros 67 68The following preprocessor macros are read (but never set) by WebRTC; they allow 69you to enable or disable parts of WebRTC at compile time. 70 71Be sure to set them the same way in all translation units that include WebRTC 72code. 73 74## `WEBRTC_EXCLUDE_BUILT_IN_SSL_ROOT_CERTS` 75If you want to ship your own set of SSL certificates and inject them into WebRTC 76PeerConnections, you will probably want to avoid to compile and ship WebRTC's 77default set of SSL certificates. 78 79You can achieve this by defining the preprocessor macro 80`WEBRTC_EXCLUDE_BUILT_IN_SSL_ROOT_CERTS`. If you use GN, you can just set the GN 81argument `rtc_builtin_ssl_root_certificates` to false and GN will define the 82macro for you. 83 84## `WEBRTC_EXCLUDE_FIELD_TRIAL_DEFAULT` 85If you want to provide your own implementation of `webrtc::field_trial` functions 86(more info [here][field_trial_h]) you will have to exclude WebRTC's default 87implementation. 88 89You can achieve this by defining the preprocessor macro 90`WEBRTC_EXCLUDE_FIELD_TRIAL_DEFAULT`. If you use GN, you can just set the GN 91argument `rtc_exclude_field_trial_default` to true and GN will define the 92macro for you. 93 94[field_trial_h]: https://webrtc.googlesource.com/src/+/main/system_wrappers/include/field_trial.h 95 96## `WEBRTC_EXCLUDE_METRICS_DEFAULT` 97If you want to provide your own implementation of `webrtc::metrics` functions 98(more info [here][metrics_h]) you will have to exclude WebRTC's default 99implementation. 100 101You can achieve this by defining the preprocessor macro 102`WEBRTC_EXCLUDE_METRICS_DEFAULT`. If you use GN, you can just set the GN 103argument `rtc_exclude_metrics_default` to true and GN will define the 104macro for you. 105 106[metrics_h]: https://webrtc.googlesource.com/src/+/main/system_wrappers/include/metrics.h 107 108## `WEBRTC_EXCLUDE_TRANSIENT_SUPPRESSOR` 109The transient suppressor functionality in the audio processing module is not 110always used. If you wish to exclude it from the build in order to preserve 111binary size, then define the preprocessor macro 112`WEBRTC_EXCLUDE_TRANSIENT_SUPPRESSOR`. If you use GN, you can just set the GN 113argument `rtc_exclude_transient_suppressor` to true and GN will define the macro 114for you. 115