| <!-- go/cmark --> |
| <!--* freshness: {owner: 'hta' reviewed: '2021-01-01'} *--> |
| |
| # API header files |
| |
| As a user of the WebRTC library, you may use headers and build files |
| in the following directories: |
| |
| API directory | Including subdirectories? |
| --------------|------------------------- |
| `api` | Yes |
| |
| For now, you may also use headers and build files in the following |
| legacy API directories—but see the |
| [disclaimer](#legacy-disclaimer) below. |
| |
| Legacy API directory | Including subdirectories? |
| -------------------------------------------|-------------------------- |
| `common_audio/include` | No |
| `media/base` | No |
| `media/engine` | No |
| `modules/audio_coding/include` | No |
| `modules/audio_device/include` | No |
| `modules/audio_processing/include` | No |
| `modules/congestion_controller/include` | No |
| `modules/include` | No |
| `modules/rtp_rtcp/include` | No |
| `modules/rtp_rtcp/source` | No |
| `modules/utility/include` | No |
| `modules/video_coding/codecs/h264/include` | No |
| `modules/video_coding/codecs/vp8/include` | No |
| `modules/video_coding/codecs/vp9/include` | No |
| `modules/video_coding/include` | No |
| `pc` | No |
| `rtc_base` | No |
| `system_wrappers/include` | No |
| |
| While the files, types, functions, macros, build targets, etc. in the |
| API and legacy API directories will sometimes undergo incompatible |
| changes, such changes will be announced in advance to |
| [discuss-webrtc@googlegroups.com][discuss-webrtc], and a migration |
| path will be provided. |
| |
| [discuss-webrtc]: https://groups.google.com/forum/#!forum/discuss-webrtc |
| |
| In the directories not listed in the tables above, incompatible |
| changes may happen at any time, and are not announced. |
| |
| ## <a name="legacy-disclaimer"></a>The legacy API directories contain some things you shouldn’t use |
| |
| The legacy API directories, in addition to things that genuinely |
| should be part of the API, also contain things that should *not* be |
| part of the API. We are in the process of moving the good stuff to the |
| `api` directory tree, and will remove directories from the legacy list |
| once they no longer contain anything that should be in the API. |
| |
| In other words, if you find things in the legacy API directories that |
| don’t seem like they belong in the WebRTC native API, |
| don’t grow too attached to them. |
| |
| ## All these worlds are yours—except Europa |
| |
| In the API headers, or in files included by the API headers, there are |
| types, functions, namespaces, etc. that have `impl` or `internal` in |
| their names (in various styles, such as `CamelCaseImpl`, |
| `snake_case_impl`). They are not part of the API, and may change |
| incompatibly at any time; do not use them. |
| |
| # Preprocessor macros |
| |
| The following preprocessor macros are read (but never set) by WebRTC; they allow |
| you to enable or disable parts of WebRTC at compile time. |
| |
| Be sure to set them the same way in all translation units that include WebRTC |
| code. |
| |
| ## `WEBRTC_EXCLUDE_BUILT_IN_SSL_ROOT_CERTS` |
| If you want to ship your own set of SSL certificates and inject them into WebRTC |
| PeerConnections, you will probably want to avoid to compile and ship WebRTC's |
| default set of SSL certificates. |
| |
| You can achieve this by defining the preprocessor macro |
| `WEBRTC_EXCLUDE_BUILT_IN_SSL_ROOT_CERTS`. If you use GN, you can just set the GN |
| argument `rtc_builtin_ssl_root_certificates` to false and GN will define the |
| macro for you. |
| |
| ## `WEBRTC_EXCLUDE_METRICS_DEFAULT` |
| If you want to provide your own implementation of `webrtc::metrics` functions |
| (more info [here][metrics_h]) you will have to exclude WebRTC's default |
| implementation. |
| |
| You can achieve this by defining the preprocessor macro |
| `WEBRTC_EXCLUDE_METRICS_DEFAULT`. If you use GN, you can just set the GN |
| argument `rtc_exclude_metrics_default` to true and GN will define the |
| macro for you. |
| |
| [metrics_h]: https://webrtc.googlesource.com/src/+/main/system_wrappers/include/metrics.h |
| |
