NAME

       TSUrlPercentEncode - traffic Server URL percent encoding API

SYNOPSIS

          #include <ts/ts.h>

       TSReturnCode TSUrlPercentEncode(TSMBuffer bufp, TSMLoc offset, char *dst, size_t dst_size,
       size_t *length, const unsigned char *map)

       TSReturnCode  TSStringPercentEncode(const  char  *str,  int  str_len,  char  *dst,  size_t
       dst_size, size_t *length, const unsigned char *map)

       TSReturnCode  TSStringPercentDecode(const  char  *str,  size_t  str_len, char *dst, size_t
       dst_size, size_t *length)

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.

       TSUrlPercentEncode()  performs  percent-encoding of the URL object, storing the new string
       in the dst buffer. The length parameter will be set to the new (encoded) string length, or
       0 if the encoding failed.  TSStringPercentEncode() is similar but operates on a string. If
       the optional map parameter is provided (not NULL) , it should be a map  of  characters  to
       encode.

       TSStringPercentDecode()  perform percent-decoding of the string in the str buffer, writing
       to the dst buffer. The source and destination can be the same, in which case  the  decoded
       string  is  written on top of the source string. The decoded string is guaranteed to be no
       longer than the source string, but will include a terminating null which, if there are  no
       escapes,  makes  the  destination  one  longer than the source. In practice this means the
       destination length needs to be bumped up by one to account for  the  null,  and  a  string
       can't  be  decoded  in  place  if  it's not already null terminated with the length of the
       destination including the null, but the length of the source not including the null. E.g.

          static char const ORIGINAL[] = "A string without escapes, but null terminated";
          char * source = TSstrdup(ORIGINAL); // make it writeable.
          size_t length; // return value.
          // sizeof(ORIGINAL) includes the null, so don't include that in the input.
          static const size_t N_CHARS = sizeof(ORIGINAL) - 1;
          TSReturnCode result = TSStringPercentDecode(source, N_CHARS, source, N_CHARS + 1, &length);
          ink_assert(length == N_CHARS);

RETURN VALUES

       All these APIs returns a TSReturnCode,  indicating  success  (TS_SUCCESS)  or  failure  (‐
       TS_ERROR) of the operation.

SEE ALSO

       TSAPI(3ts), TSUrlCreate(3ts), TSUrlHostGet(3ts), TSUrlHostSet(3ts), TSUrlStringGet(3ts)

COPYRIGHT

       2023, dev@trafficserver.apache.org