| .. Licensed to the Apache Software Foundation (ASF) under one or more contributor license |
| agreements. See the NOTICE file distributed with this work for additional information regarding |
| copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance with the License. You may obtain a |
| copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software distributed under the License |
| is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express |
| or implied. See the License for the specific language governing permissions and limitations under |
| the License. |
| |
| .. include:: ../../common.defs |
| |
| .. _developer-header-files: |
| |
| Header Files |
| ************ |
| |
| There are four header directories, each containing header files for different purposes. Three of these |
| are available to plugins. |
| |
| "ts" |
| The C Plugin API. These call functions directly embedded in ``traffic_server`` and therefore have |
| no explicit linkage. |
| |
| "tscpp/api" |
| The C++ Plugin API. These call functions in the ``libtscppapi.so`` library to directly interact with |
| the running |TS| instance. |
| |
| "tscpp/util" |
| C++ utilities. These are standalone headers (although they may depend on other headers in the |
| same directory). These provide functionality that is used inside the |TS| core logic but has been |
| demonstrated to be useful for plugins as well [#]_. The functions are in the library |
| ``libtscpputil.so``, although many of the utilities are header only. This library is linked in to |
| the ``traffic_server`` and ``traffic_manager`` binaries and so linkage may not be needed for a plugin. |
| |
| This library is independent of the C++ API and can be used with or without that library. |
| |
| "tscore" |
| |TS| core header files. These can only be used inside |TS| itself because they either depend on internal |
| data structures either directly or operationally. This is linked in to the ``traffic_server`` and |
| ``traffic_manager`` binaries therefore has no explicit linkage when used in the core. |
| |
| Historical |
| ========== |
| |
| This was a major restructuring the source code layout. The primary goal of this was to unify the include paths |
| for the core and plugins for these headers, and to make C++ support code used in the core also available to plugins. |
| Previously plugins in the |TS| codebase used these headers because they could reach over and include them, but |
| third party plugins could not because the headers were not installed. |
| |
| "proxy/api/ts" was moved to "include/ts", along with a couple headers from "lib/ts". This consolidates the C plugin API. |
| |
| The C++ API headers were split from the source and moved to "include/tscpp/api". The source files |
| were moved to "src/tscpp/api". |
| |
| The contents of "lib/ts" were broken up and moved to different locations. The headers were moved to |
| "include/tscore" for core only headers, while headers to be made available to plugins were moved to |
| "include/tscpp/util". The corresponding source files were moved to "src/tscore" and "src/tscpp/util" |
| respectively. "libtsutil" was split in to "libtscore" for the core code and "libtscpputil" for shared |
| code. |
| |
| Appendix |
| ======== |
| |
| .. rubric:: Footnotes |
| |
| .. [#] |
| Primarily by use in the plugins in the |TS| code base. |