TSUuidCreate
Traffic Server UUID construction APIs.
Synopsis
#include <ts/ts.h>
-
TSReturnCode TSUuidInitialize(TSUuid uuid, TSUuidVersion v)
-
TSReturnCode TSUuidCopy(TSUuid dest, const TSUuid src)
-
TSUuidVersion TSUuidVersionGet(const TSUuid uuid)
-
TSReturnCode TSUuidStringParse(TSUuid uuid, const char *uuid_str)
-
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),