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

       2023, dev@trafficserver.apache.org