This is an automated email from the ASF dual-hosted git repository.
amc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 3fbd0d2 expands TSHostLookup documentation
3fbd0d2 is described below
commit 3fbd0d23f7bfaa2ab0ab58438936619a23b44700
Author: Derek Dagit <der...@oath.com>
AuthorDate: Tue Nov 14 20:43:49 2017 +0000
expands TSHostLookup documentation
---
doc/developer-guide/api/functions/TSHostLookup.en.rst | 6 ++++++
.../api/functions/TSHostLookupResultAddrGet.en.rst | 14 ++++++++++++++
doc/developer-guide/api/functions/TSTypes.en.rst | 2 ++
3 files changed, 22 insertions(+)
diff --git a/doc/developer-guide/api/functions/TSHostLookup.en.rst
b/doc/developer-guide/api/functions/TSHostLookup.en.rst
index 41cf405..dc350ad 100644
--- a/doc/developer-guide/api/functions/TSHostLookup.en.rst
+++ b/doc/developer-guide/api/functions/TSHostLookup.en.rst
@@ -30,3 +30,9 @@ Synopsis
Description
===========
+
+Attempts host name resolution for the given :arg:`hostname` with length
:arg:`namelen`. When a result is ready the handler of :arg:`contp` is called
with the :macro:`TS_EVENT_HOST_LOOKUP` event and a :type:`TSHostLookupResult`.
Use :func:`TSHostLookupResultAddrGet` to retrieve the resulting address from
the :type:`TSHostLookupResult`.
+
+A call to :func:`TSHostLookup` may be synchronous—in which case the handler
for :arg:`contp` will be called with the answer before the call to
:func:`TSHostLookup` returns—or the call to :func:`TSHostLookup` may be
asynchronous—in which case it returns immediately with a :type:`TSAction`, and
the handler :arg:`contp` will be called in the future. See
:doc:`../../plugins/actions/index.en` for guidance.
+
+In particular, :arg:`contp` must have been created with a :type:`TSMutex`; see
:func:`TSContCreate`
diff --git a/doc/developer-guide/api/functions/TSHostLookupResultAddrGet.en.rst
b/doc/developer-guide/api/functions/TSHostLookupResultAddrGet.en.rst
index d6e5759..daff4e8 100644
--- a/doc/developer-guide/api/functions/TSHostLookupResultAddrGet.en.rst
+++ b/doc/developer-guide/api/functions/TSHostLookupResultAddrGet.en.rst
@@ -30,3 +30,17 @@ Synopsis
Description
===========
+
+Retrieves the pointer to a ``sockaddr`` of a the given :arg:`lookup_result`
from a previous call to :func:`TSHostLookup`.
+
+For example:
+
+.. code-block:: c
+
+ int
+ handler(TSCont contp, TSEvent event, void *edata) {
+ if (event == TS_EVENT_HOST_LOOKUP) {
+ const sockaddr *addr =
TSHostLookupResultAddrGet(static_cast<TSHostLookupResult>(edata));
+ // TODO Add logic here.
+ }
+ }
diff --git a/doc/developer-guide/api/functions/TSTypes.en.rst
b/doc/developer-guide/api/functions/TSTypes.en.rst
index 2b07ea1..ae47cf0 100644
--- a/doc/developer-guide/api/functions/TSTypes.en.rst
+++ b/doc/developer-guide/api/functions/TSTypes.en.rst
@@ -58,6 +58,8 @@ more widely. Those are described on this page.
.. type:: TSHostLookupResult
+ A type representing the result of a call to :func:`TSHostLookup`. Use with
:func:`TSHostLookupResultAddrGet`.
+
.. type:: TSHRTime
"High Resolution Time"
--
To stop receiving notification emails like this one, please contact
['"commits@trafficserver.apache.org" <commits@trafficserver.apache.org>'].
