NAME

       TSHttpConnectWithPluginId  -  allows  the  plugin  to initiate an http connection. This will tag the HTTP
       state machine with extra data that can be accessed by the logging interface. The connection is treated as
       an HTTP transaction as if it came from a client

       NOTE:
          This is a convenience function for TSHttpConnectPlugin() to provide a simpler interface  and  backward
          compatibility   for   existing   implementations.    When   this   function   is   used   instead   of
          TSHttpConnectPlugin, default buffer index and watermark values will be used when creating IOBuffers.

SYNOPSIS

          #include <ts/ts.h>

       TSVConn TSHttpConnectWithPluginId(sockaddr const *addr, char const *tag, int64_t id)

DESCRIPTION

       This call attempts to create an HTTP state machine and a virtual connection to that state  machine.  This
       is  more  efficient  than using TSNetConnect() because it avoids using the operating system stack via the
       loopback interface.

       addr   This is the network address of the target of the connection.  This includes the port which  should
              be stored in the sockaddr structure pointed at by addr.

       tag    This  is  a  tag that is passed through to the HTTP state machine.  It must be a persistent string
              that has a lifetime longer than the connection. It is accessible via the log field pitag. This  is
              intended  as a class or type identifier that is consistent across all connections for this plugin.
              In effect, the name of the plugin. This can be NULL.

       id     This is a numeric identifier that is passed through to the HTTP state machine.  It  is  accessible
              via  the  log  field  piid. This is intended as a connection identifier and should be distinct for
              every call to TSHttpConnectWithPluginId().  The easiest mechanism is to  define  a  plugin  global
              value  and  increment it for each connection. The value 0 is reserved to mean "not set" and can be
              used as a default if this functionality is not needed.

       The virtual connection returned as the TSVConn is API equivalent to a network virtual connection both  to
       the  plugin  and  to  internal  mechanisms. Data is read and written to the connection (and thence to the
       target system) by reading and writing on this virtual connection.

       NOTE:
          This function only opens the connection. To drive the transaction an actual HTTP request must be  sent
          and  the  HTTP  response handled. The transaction is handled as a standard HTTP transaction and all of
          the standard configuration options and plugins will operate on it.

       The combination of tag and id is  intended  to  enable  correlation  in  log  post  processing.  The  tag
       identifies  the  connection  as  related  to the plugin and the id can be used in conjunction with plugin
       generated logs to correlate the log records.

NOTES

       The H2 implementation uses this to correlate client sessions with H2 streams. Each client  connection  is
       assigned  a distinct numeric identifier. This is passed as the id to TSHttpConnectWithPluginId(). The tag
       is selected to be the NPN string for the client session protocol, e.g.  "h2".  Log  post  processing  can
       then  count  the  number  of connections for the various supported protocols and the number of H2 virtual
       streams for each real client connection to Traffic Server.

SEE ALSO

       TSHttpConnectPlugin(3ts), TSHttpConnect(3ts), TSNetConnect(3ts), TSAPI(3ts)

COPYRIGHT

       2024, dev@trafficserver.apache.org

9.2                                               Apr 01, 2024                    TSHTTPCONNECTWITHPLUGINID(3ts)