NAME

       TSUuidCreate - traffic Server UUID construction APIs

SYNOPSIS

          #include <ts/ts.h>

       TSUuid TSUuidCreate(void)

       TSReturnCode TSUuidInitialize(TSUuid uuid, TSUuidVersion v)

       void TSUuidDestroy(TSUuid uuid)

       TSReturnCode TSUuidCopy(TSUuid dest, const TSUuid src)

       const char *TSUuidStringGet(const TSUuid uuid)

       TSUuidVersion TSUuidVersionGet(const TSUuid uuid)

       TSReturnCode TSUuidStringParse(TSUuid uuid, const char *uuid_str)

       const TSUuid TSProcessUuidGet(void)

       TSReturnCode TSClientRequestUuidGet(TSHttpTxn txnp, char *uuid_str)

DESCRIPTION

       These  APIs  are  used  to  create,  manage,  and  use  UUIDs in a plugin, implementing part of RFC 4122.
       Currently, only the V4 variant of the specifications is implemented. In addition,  an  internal,  process
       unique UUID is provided, which can be used to uniquely identifying the running Traffic Server process.

       TSUuidCreate()  creates  a  new  TSUuid  object,  which  is  returned  and can be used by the other APIs.
       Similarly, a read-only global process UUID is returned from the function TSProcessUuidGet(). You must not
       attempt to modify any data as returned by either of these functions.

       TSUuidInitialize() initializes a TSUuid object, using the algorithm defined for  the  specified  version.
       Note  that only the V4 variants is currently supported. You can call TSUuidInitialize() repeatedly, which
       each generates a new UUID, but this will overwrite any existing  UUID  data  in  the  object.  This  also
       implies that any strings retrieved using TSUuidStringGet() are also modified accordingly.

       TSUuidDestroy()  destroys  (releases) an TSUuid object, and frees all memory associated with this object.
       This includes any strings as returned by e.g. TSUuidStringGet().

       TSUuidCopy() copies one TSUuid to another, making an exact duplicate. Note that both the source  and  the
       destination UUIDs must be created appropriately, and should not have been previously destroyed.

       TSUuidVersionGet()  returns  the  version number for the TSUuid. This will work properly for any RFC 4122
       initialized UUID object, e.g. if you parse a string with TSUuidStringParse() this will return the correct
       variant ID.

       TSUuidStringGet() returns a pointer to the internal string representation  of  the  TSUuid  object.  It's
       important  to  know  that there is no transfer of ownership of this string. If you need a copy of it, you
       are responsible of doing so yourself. In particular, using a  string  as  returned  by  TSUuidStringGet()
       after  you  have  called  TSUuidDestroy() on the corresponding TSUuid object is a serious error. The UUID
       object does not do any sort of reference counting on the string, and you must  absolutely  not  free  the
       memory as returned by this API.

       TSUuidStringParse()  can  be  used  to convert an existing TSUuid string to a Traffic Server UUID object.
       This will only succeed if the TSUuid string is a proper RFC 4122 UUID. The TSUuid argument passed to this
       function must be a properly TSUuidCreate() object, but it does not need to be previously initialized.

       Finally, TSClientRequestUuidGet() can be used to extract the client request uuid from a transaction.  The
       output  buffer must be of sufficient length, minimum of TS_CRUUID_STRING_LEN + 1 bytes. This produces the
       same string as the log tag %<cruuid> generates, and it will be NULL terminated.

RETURN VALUES

       The TSUuid type is an opaque pointer to an internal representation of the UUID  object.  Several  of  the
       functions returns a normal Traffic Server return status code, TSReturnCode. You should verify the success
       of those APIs, of course.

       The  TSUuidStringGet()  function  will  return  NULL  if  the  TSUuid object is not properly initialized.
       Likewise, TSUuidVersionGet() would then return TS_UUID_UNDEFINED.

       The TSUuidDestroy() function can not fail, and does not have a return  value,   but  you  are  of  course
       responsible for providing a valid TSUuid object.

EXAMPLES

          #include <ts/ts.h>

          TSUuid machine, uuid;

          machine = TSProcessUuidGet();
          printf("Machine UUID is %s\n", TSUuidStringGet(machine);

          if (uuid = TSUuidCreate()) {
            if (TS_SUCCESS == TSUuidInitialize(uuid, TS_UUID_V4) {
              printf("My UUID is %s\n", TSUuidStringGet(uuid));
            }
            TSUuidDestroy(uuid);
          }

          const char* str = "c71e2bab-90dc-4770-9535-c9304c3de38e";

          if (TS_SUCCESS == TSUuidStringParse(uuid, str)) {
            if (TS_UUID_V4 == TSUuidVersionGet(uuid)) {
              // Yes!
            }
          }

SEE ALSO

       TSAPI(3ts), TSUuid(3ts), TSReturnCode(3ts),

COPYRIGHT

       2024, dev@trafficserver.apache.org

9.2                                               Apr 01, 2024                                 TSUUIDCREATE(3ts)