----- Original Message ----- > doc: convert TSTrafficServerVersionGet(3) to sphinx
Reminder: https://issues.apache.org/jira/browse/TS-1953 > http://git-wip-us.apache.org/repos/asf/trafficserver/blob/e0a2dd5d/doc/conf.py > ---------------------------------------------------------------------- > diff --git a/doc/conf.py b/doc/conf.py > index e2067b0..d7c9f2b 100644 > --- a/doc/conf.py > +++ b/doc/conf.py > @@ -223,6 +223,7 @@ man_pages = [ > ('reference/api/TSmalloc.en', 'TSmalloc', u'Traffic Server memory > allocation API', None, u'3ts'), > ('reference/api/TSPluginInit.en', 'TSPluginInit', u'Traffic > Server plugin loading and registration', None, u'3ts'), > ('reference/api/TSRemap.en', 'TSRemap', u'Traffic Server remap > plugin entry points ', None, u'3ts'), > + ('reference/api/TSTrafficServerVersionGet.en', > 'TSTrafficServerVersionGet', u'return Traffic Server version > information', None, u'3ts'), > > ('reference/commands/traffic_cop.en', 'traffic_cop', u'Traffic > Server watchdog', None, '8'), > ('reference/commands/traffic_line.en', 'traffic_line', u'Traffic > Server command line', None, '8'), > > http://git-wip-us.apache.org/repos/asf/trafficserver/blob/e0a2dd5d/doc/reference/api/TSTrafficServerVersionGet.en.rst > ---------------------------------------------------------------------- > diff --git a/doc/reference/api/TSTrafficServerVersionGet.en.rst > b/doc/reference/api/TSTrafficServerVersionGet.en.rst > new file mode 100644 > index 0000000..e450743 > --- /dev/null > +++ b/doc/reference/api/TSTrafficServerVersionGet.en.rst > @@ -0,0 +1,98 @@ > +.. 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. > + > +.. default-domain:: c > + > +========================= > +TSTrafficServerVersionGet > +========================= > + > +Synopsis > +======== > + > +`#include <ts/ts.h>` > + > +.. function:: const char * TSTrafficServerVersionGet(void) > +.. function:: int TSTrafficServerVersionGetMajor(void) > +.. function:: int TSTrafficServerVersionGetMinor(void) > +.. function:: int TSTrafficServerVersionGetPatch(void) > + > +Description > +=========== > + > +:func:`TSTrafficServerVersionGet` returns a pointer to a string of > characters > +that indicates the Traffic Server release version. This string must > not > +be modified. > + > +The other APIs return an integer version number. > + > +Example > +======= > + > +:: > + > + #include <stdio.h> > + #include <ts/ts.h> > + > + int > + check_ts_version() > + { > + const char *ts_version = TSTrafficServerVersionGet(); > + int result = 0; > + > + if (ts_version) { > + int major_ts_version = 0; > + int minor_ts_version = 0; > + int patch_ts_version = 0; > + > + if (sscanf(ts_version, "%d.%d.%d", &major_ts_version, > + &minor_ts_version, &patch_ts_version) != 3) { > + return 0; > + } > + > + /* We need at least Traffic Server 3.0 */ > + if (major_ts_version >= 3) { > + result = 1; > + } > + } no, seriously, we need to get rid of this boiler plate code. https://issues.apache.org/jira/browse/TS-1953 TSVersionGE(int major, int minor = -1, int patch = -1) { if ( !(TSTrafficServerVersionGetMajor >= major)) { return false; } else if (minor != -1) { if ( !(TSTrafficServerVersionGetMinor >= minor)) { return false; } else if (patch != -1 ) { if ( !(TSTrafficServerVersionGetPatch >= patch)) { return false; } } } return true; } This, and equivalent functions could be written as macros. > + > + return result; > + } > + > + void > + TSPluginInit (int argc, const char *argv[]) > + { > + TSPluginRegistrationInfo info; > + info.plugin_name = "hello-world"; > + info.vendor_name = "MyCompany"; > + info.support_email = "ts-api-supp...@mycompany.com"; > + > + if (TSPluginRegister(TS_SDK_VERSION_3_0 , &info) != > TS_SUCCESS) { > + TSError("Plugin registration failed. 0); > + } > + - if (!check_ts_version()) { + if (!TSVersionGE(3,0)) { > + TSError("Plugin requires Traffic Server 3.0 or later0); > + return; > + } > + > + TSDebug("debug-hello", "Hello World!0); > + } > + > +See also > +======== > + > +:manpage:`TSAPI(3ts)` > > -- Igor Galić Tel: +43 (0) 664 886 22 883 Mail: i.ga...@brainsware.org URL: http://brainsware.org/ GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
