NAME

       TSUrlStringGet - traffic Server URL string representations API

SYNOPSIS

          #include <ts/ts.h>

       char *TSUrlStringGet(TSMBuffer bufp, TSMLoc offset, int *length)

       char *TSHttpTxnEffectiveUrlStringGet(TSHttpTxn txn, int *length)

       TSReturnCode  TSHttpHdrEffectiveUrlBufGet(TSMBuffer  hdr_buf,  TSMLoc  hdr_loc, char *buf,
       int64_t size, int64_t *length)

       int TSUrlLengthGet(TSMBuffer bufp, TSMLoc offset)

       void TSUrlPrint(TSMBuffer bufp, TSMLoc offset, TSIOBuffer iobufp)

DESCRIPTION

       The URL data structure is a parsed version of a standard internet URL. The Traffic  Server
       URL  API  provides  access  to  URL  data stored in marshal buffers. The URL functions can
       create, copy, retrieve or delete entire URLs, and retrieve or modify parts of  URLs,  such
       as their host, port or scheme information.

       TSUrlStringGet()  constructs  a  string representation of the URL located at offset within
       the marshal buffer bufp.   (However  bufp  is  actually  superfluous  and  may  be  null.)
       TSUrlStringGet()  stores the length of the allocated string in the parameter length.  This
       is the same length that TSUrlLengthGet() returns. The returned string is  allocated  by  a
       call  to  TSmalloc()  and  must  be freed by a call to TSfree(). If length is NULL then no
       attempt is made to de-reference it. The returned string is not guaranteed to have  a  null
       terminator - length must be used to correctly display the string.

       TSHttpTxnEffectiveUrlStringGet() is similar to TSUrlStringGet(). The two differences are:

       • The  source  is transaction txn and the URL is retrieved from the client request in that
         transaction.

       • If the client request URL has a host, that URL is returned, Otherwise,  if  there  is  a
         "Host" field the value of that field is used as the host in the returned URL.

       This  function  is  useful  to  guarantee  a URL that is as complete as possible given the
       specific request.

       TSHttpHdrEffectiveUrlBufGet() returns the effective URL for any HTTP request (not just the
       client  request).   If the request has a Host header field (and the URL does not contain a
       host specifier), the host specifier the header provides is inserted  into  the  URL.   The
       host  and scheme in the returned URL will be normalized to lower case letters (to make URL
       comparisons simple and fast).  This prints the effective URL for the header  specified  by
       hdr_buf  and  hdr_loc  to  the buffer starting at buf. If the effective URL is longer than
       size, nothing is written to buf.  Note that this is not  considered  an  error  case,  the
       function  will  still  return TS_SUCCESS.  It is the responsibility of the caller to check
       this result to determine if output was generated.  The full length of the  URL  is  always
       returned in *length when the function returns TS_SUCCESS.

       The typical usage would be

          TSMBuffer hdr_buf;
          TSMLoc hdr_loc;
          TSHttpTxnServerReqGet(txn, &hdr_buf, &hdr_loc);
          int64_t length;
          char store[2048];
          char *buf = store;
          TSHttpHdrEffectiveUrlBufGet(hdr_buf, hdr_loc, buf, sizeof(store), &length);
          if (length > sizeof(store)) {
            buf = static_cast<char *>(malloc(length));
            TSHttpHdrEffectiveUrlBufGet(hdr_buf, hdr_loc, buf, length, &length);
          }

       TSUrlLengthGet()  calculates  the  length  of the URL located at offset within the marshal
       buffer bufp as if it were returned as a string. This length will be the same as the length
       returned by TSUrlStringGet().

       TSUrlPrint()  formats  a URL stored in an TSMBuffer to an TSIOBuffer. Capacity is added as
       needed to the iobufp to print the entire URL.

SEE ALSO

       TSAPI(3ts),   TSmalloc(3ts),   TSUrlCreate(3ts),   TSUrlHostGet(3ts),   TSUrlHostSet(3ts),
       TSUrlPercentEncode(3ts)

COPYRIGHT

       2022, dev@trafficserver.apache.org