Ubuntu Manpage: TSUuidCreate - traffic Server UUID construction APIs

Provided by: trafficserver-dev_9.1.3+ds-1_amd64

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!
            }
          }

COPYRIGHT