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 nullptr 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),