.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "TSHTTPCONNECTWITHPLUGINID" "3ts" "Apr 16, 2024" "9.2" "Apache Traffic Server"
.SH 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
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This is a convenience function for \fI\%TSHttpConnectPlugin()\fP to provide
a simpler interface and backward compatibility for existing implementations.
When this function is used instead of \fITSHttpConnectPlugin\fP, default buffer
index and watermark values will be used when creating IOBuffers.
.UNINDENT
.UNINDENT
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#include <ts/ts.h>
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSVConn\fP TSHttpConnectWithPluginId(sockaddr const *addr, char const *tag, int64_t id) 
.UNINDENT
.SH DESCRIPTION
.sp
This call attempts to create an HTTP state machine and a virtual
connection to that state machine. This is more efficient than using
\fI\%TSNetConnect()\fP because it avoids using the operating system
stack via the loopback interface.
.INDENT 0.0
.TP
.B \fIaddr\fP
This is the network address of the target of the connection.
This includes the port which should be stored in the \fBsockaddr\fP
structure pointed at by \fIaddr\fP\&.
.TP
.B \fItag\fP
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 \fI\%pitag\fP\&. 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 \fBNULL\fP\&.
.TP
.B \fIid\fP
This is a numeric identifier that is passed through to the HTTP
state machine. It is accessible via the log field \fI\%piid\fP\&. This is intended as a connection identifier and should
be distinct for every call to \fI\%TSHttpConnectWithPluginId()\fP\&.
The easiest mechanism is to define a plugin global value and
increment it for each connection. The value \fB0\fP is
reserved to mean \(dqnot set\(dq and can be used as a default if this
functionality is not needed.
.UNINDENT
.sp
The virtual connection returned as the \fI\%TSVConn\fP 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.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
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.
.UNINDENT
.UNINDENT
.sp
The combination of \fItag\fP and \fIid\fP is intended to enable correlation
in log post processing. The \fItag\fP identifies the connection as related
to the plugin and the \fIid\fP can be used in conjunction with plugin
generated logs to correlate the log records.
.SH NOTES
.sp
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 \fIid\fP to
\fI\%TSHttpConnectWithPluginId()\fP\&. The \fItag\fP is selected
to be the NPN string for the client session protocol, e.g.
\(dqh2\(dq. 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.
.SH SEE ALSO
.sp
\fBTSHttpConnectPlugin(3ts)\fP,
\fBTSHttpConnect(3ts)\fP,
\fBTSNetConnect(3ts)\fP,
\fBTSAPI(3ts)\fP
.SH COPYRIGHT
2024, dev@trafficserver.apache.org
.\" Generated by docutils manpage writer.
.