TSPortDescriptorParse

Parse and listen on a proxy port descriptor.

Synopsis

#include <ts/ts.h>

type TSPortDescriptor

TSPortDescriptor TSPortDescriptorParse(const char *descriptor)

TSReturnCode TSPortDescriptorAccept(TSPortDescriptor descriptor, TSCont contp)

void TSPortDescriptorDestroy(TSPortDescriptor descriptor)

Description

TSPortDescriptorParse() parses the same descriptor syntax used by proxy.config.http.server_ports and returns an allocated, opaque TSPortDescriptor handle. Each successful call must be paired with exactly one call to TSPortDescriptorDestroy().

TSPortDescriptorAccept() copies the information it needs from descriptor and does not retain a pointer to it. The descriptor can therefore be destroyed immediately after TSPortDescriptorAccept() returns, regardless of whether the listener remains active.

A descriptor containing only an fd= option is not supported because this API requires an explicit listen endpoint. The quic option is also not supported by this API and must not be used; it does not create a QUIC listener.

For example, this function destroys the descriptor after opening the listener:

TSReturnCode
listen_on_descriptor(TSCont contp, const char *spec)
{
  TSPortDescriptor descriptor = TSPortDescriptorParse(spec);
  if (descriptor == nullptr) {
    return TS_ERROR;
  }

  TSReturnCode result = TSPortDescriptorAccept(descriptor, contp);
  TSPortDescriptorDestroy(descriptor);
  return result;
}

When a connection is accepted, contp receives TS_EVENT_NET_ACCEPT. The event data is a TSVConn for the accepted connection.

Return Values

TSPortDescriptorParse() returns a new descriptor handle when descriptor was parsed successfully. It returns nullptr for a null argument, invalid descriptor, or descriptor that cannot be used by TSPortDescriptorAccept().

TSPortDescriptorAccept() returns TS_SUCCESS when the listener was opened. It returns TS_ERROR for a null argument, a descriptor with an unusable listen endpoint, or an error opening the listener.

TSPortDescriptorDestroy() releases descriptor. Passing nullptr has no effect. Destroying a descriptor does not stop a listener previously opened from it.

See Also

TSAPI(3ts), TSNetAccept(3ts), records.yaml(5)