From f4f2fc7c3d76eb3dc5a91c5eefb36c10597d6cb7 Mon Sep 17 00:00:00 2001 From: peterbell10 Date: Fri, 25 Aug 2017 13:43:18 +0100 Subject: Add cUUID class (#3871) --- Server/Plugins/APIDump/APIDesc.lua | 156 +++++++++++++++++++++++++++++++++---- 1 file changed, 142 insertions(+), 14 deletions(-) (limited to 'Server/Plugins/APIDump/APIDesc.lua') diff --git a/Server/Plugins/APIDump/APIDesc.lua b/Server/Plugins/APIDump/APIDesc.lua index df2d93785..d7dc83043 100644 --- a/Server/Plugins/APIDump/APIDesc.lua +++ b/Server/Plugins/APIDump/APIDesc.lua @@ -1463,7 +1463,7 @@ end { { Name = "UUID", - Type = "string", + Type = "cUUID", }, }, Returns = @@ -1472,7 +1472,7 @@ end Type = "boolean", }, }, - Notes = "Returns true if the UUID is generated by online auth, false if it is an offline-generated UUID. We use Version-3 UUIDs for offline UUIDs, online UUIDs are Version-4, thus we can tell them apart. Accepts both 32-char and 36-char UUIDs (with and without dashes). If the string given is not a valid UUID, returns false.", + Notes = "Returns true if the UUID is generated by online auth, false if it is an offline-generated UUID. We use Version-3 UUIDs for offline UUIDs, online UUIDs are Version-4, thus we can tell them apart. Accepts both 32-char and 36-char UUIDs (with and without dashes).", }, Kick = { @@ -8485,10 +8485,9 @@ a_Player:OpenWindow(Window);

All the functions are static, call them using the cMojangAPI:Function() convention.

- Mojang uses two formats for UUIDs, short and dashed. Cuberite works with short UUIDs internally, but - will convert to dashed UUIDs where needed - in the protocol login for example. The MakeUUIDShort() - and MakeUUIDDashed() functions are provided for plugins to use for conversion between the two - formats.

+ Mojang uses two formats for UUIDs, short and dashed. Cuberite will accept either format for any + functions taking a UUID. The MakeUUIDShort() and MakeUUIDDashed() functions are provided for plugins + to use for conversion between the two formats.

This class will cache values returned by the API service. The cache will hold the values for 7 days by default, after that, they will no longer be available. This is in order to not let the server get @@ -8509,10 +8508,10 @@ a_Player:OpenWindow(Window); }, { Name = "UUID", - Type = "string", + Type = "cUUID", }, }, - Notes = "Adds the specified PlayerName-to-UUID mapping into the cache, with current timestamp. Accepts both short or dashed UUIDs. ", + Notes = "Adds the specified PlayerName-to-UUID mapping into the cache, with current timestamp.", }, GetPlayerNameFromUUID = { @@ -8521,7 +8520,7 @@ a_Player:OpenWindow(Window); { { Name = "UUID", - Type = "string", + Type = "cUUID", }, { Name = "UseOnlyCached", @@ -8592,7 +8591,7 @@ a_Player:OpenWindow(Window); { { Name = "UUID", - Type = "string", + Type = "cUUID", }, }, Returns = @@ -8602,7 +8601,7 @@ a_Player:OpenWindow(Window); Type = "string", }, }, - Notes = "Converts the UUID to a dashed format (\"01234567-8901-2345-6789-012345678901\"). Accepts both dashed or short UUIDs. Logs a warning and returns an empty string if UUID format not recognized.", + Notes = "Converts the UUID to a dashed format (\"01234567-8901-2345-6789-012345678901\"). An alias for cUUID:ToLongString()", }, MakeUUIDShort = { @@ -8611,7 +8610,7 @@ a_Player:OpenWindow(Window); { { Name = "UUID", - Type = "string", + Type = "cUUID", }, }, Returns = @@ -8621,7 +8620,7 @@ a_Player:OpenWindow(Window); Type = "string", }, }, - Notes = "Converts the UUID to a short format (without dashes, \"01234567890123456789012345678901\"). Accepts both dashed or short UUIDs. Logs a warning and returns an empty string if UUID format not recognized.", + Notes = "Converts the UUID to a short format (without dashes, \"01234567890123456789012345678901\"). An alias for cUUID:ToShortString()", }, }, }, @@ -11181,7 +11180,7 @@ a_Player:OpenWindow(Window); { { Name = "PlayerUUID", - Type = "string", + Type = "cUUID", }, { Name = "CallbackFunction", @@ -12441,6 +12440,135 @@ end }, }, }, + cUUID = + { + Desc = [[ + Class representing a Universally Unique Identifier. + Note that all Cuberite's API functions that take a cUUID parameter will also + accept a string in its place, as long as that string can be converted to a cUUID + (using the {{#FromString_1|cUUID:FromString}} function). + ]], + Functions = + { + constructor = + { + Returns = + { + { + Type = "cUUID", + }, + }, + Notes = "Constructs a nil-valued UUID (all zeros)", + }, + Compare = + { + Params = + { + { + Name = "Other", + Type = "cUUID", + }, + }, + Returns = + { + { + Type = "number", + }, + }, + Notes = [[ + Compares this UUID with the specified Other UUID, Returns: + 0 when equal to Other, + < 0 when less than Other, + > 0 when greater than Other + ]], + }, + IsNil = + { + Returns = + { + { + Type = "boolean", + }, + }, + Notes = "Returns true if this contains the \"nil\" UUID with all bits set to 0", + }, + FromString = + { + Params = + { + { + Name = "StringUUID", + Type = "string", + }, + }, + Returns = + { + { + Type = "boolean", + }, + }, + Notes = "Tries to interpret the string as a short or long form UUID and assign from it. On error, returns false and does not set the value.", + }, + ToShortString = + { + Returns = + { + { + Type = "string", + }, + }, + Notes = "Converts the UUID to a short form string (i.e without dashes).", + }, + ToLongString = + { + Returns = + { + { + Type = "string", + }, + }, + Notes = "Converts the UUID to a long form string (i.e with dashes).", + }, + Version = + { + Returns = + { + { + Type = "number", + }, + }, + Notes = "Returns the version number of the UUID.", + }, + Variant = + { + Returns = + { + { + Type = "number", + }, + }, + Notes = "Returns the variant number of the UUID", + }, + GenerateVersion3 = + { + IsStatic = true, + Params = + { + { + Name = "Name", + Type = "string", + }, + }, + Returns = + { + { + Type = "cUUID", + }, + }, + Notes = "Generates a version 3, variant 1 UUID based on the md5 hash of Name." + }, + }, + }, cWebPlugin = { Desc = "", -- cgit v1.2.3