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