[trafficserver] branch master updated: expands TSHostLookup documentation

[am...@apache.org]

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 <de...@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" <co...@trafficserver.apache.org>'].