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);
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.
Finally,
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.
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¶
2015, dev@trafficserver.apache.org