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.  This  produces  the  same
       string as the log tag %<cruuid> generates.

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 inititialized.
       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

       2018, dev@trafficserver.apache.org