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

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
       conjuction 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

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

COPYRIGHT

       2018, dev@trafficserver.apache.org