[trafficserver] branch master updated: Clarifies when API function should be called

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

dagit 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 f9adca0  Clarifies when API function should be called
f9adca0 is described below

commit f9adca0cdb64928b06a376f68ff2d42214a9bcb4
Author: Derek Dagit <de...@oath.com>
AuthorDate: Fri Apr 20 15:24:05 2018 -0500

    Clarifies when API function should be called
    
    From testing, the connection to the origin seems to be established
    before TS_HTTP_SEND_REQUEST_HDR_HOOK and after any other hooks.
    
    This means the address must be set prior to the above hook, and we may
    get the address only in or after the above hook.
    
    The change suggests a hook that will reliably work for setting the
    address.
---
 doc/developer-guide/api/functions/TSHttpTxnOutgoingAddrGet.en.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/developer-guide/api/functions/TSHttpTxnOutgoingAddrGet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnOutgoingAddrGet.en.rst
index cfbee11..c20ed29 100644
--- a/doc/developer-guide/api/functions/TSHttpTxnOutgoingAddrGet.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpTxnOutgoingAddrGet.en.rst
@@ -39,7 +39,9 @@ These functions concern the local IP address and port, that is the address and p
 of outbound connections (network connections *from* |TS| *to* another socket).
 
 The address and optional the port can be set with :func:`TSHttpTxnOutgoingAddrSet`. This must be
-done before the outbound connection is made, that is in the :macro:`TS_HTTP_SEND_REQUEST_HDR_HOOK` or earlier.
+done before the outbound connection is made, that is, earlier than the :macro:`TS_HTTP_SEND_REQUEST_HDR_HOOK`.
+A good choice is the :macro:`TS_HTTP_POST_REMAP_HOOK`, since it is a hook that is always called, and it
+is the latest hook that is called before the connection is made.
 The :arg:`addr` must be populated with the IP address and port to be used. If the port is not
 relevant it can be set to zero, which means use any available local port. This function returns
 :macro:`TS_SUCCESS` on success and :macro:`TS_ERROR` on failure.
@@ -47,8 +49,8 @@ relevant it can be set to zero, which means use any available local port. This f
 Even on a successful call to :func:`TSHttpTxnOutgoingAddrSet`, the local IP address may not match
 what was passing :arg:`addr` if :ts:cv:`session sharing <proxy.config.http.server_session_sharing.match>` is enabled.
 
-Conversely :func:`TSHttpTxnOutgoingAddrGet` retrieves the local address and must be called after
-:macro:`TS_HTTP_SEND_REQUEST_HDR_HOOK`, after the outbound connection has been established. It returns a
+Conversely :func:`TSHttpTxnOutgoingAddrGet` retrieves the local address and must be called in the
+:macro:`TS_HTTP_SEND_REQUEST_HDR_HOOK` or later, after the outbound connection has been established. It returns a
 pointer to a :code:`sockaddr` which contains the local IP address and port. If there is no valid
 outbound connection, :arg:`addr` will be :code:`NULL`. The returned pointer is a transient pointer
 and must not be referenced after the callback in which :func:`TSHttpTxnOutgoingAddrGet` was called.

-- 
To stop receiving notification emails like this one, please contact
dagit@apache.org.