DecodeString: Difference between revisions

Latest revision as of 16:30, 20 February 2024

This function decodes an encoded string using the specified algorithm. The counterpart of this function is encodeString.

Syntax

string decodeString ( string algorithm, string input, [table options, function callback] )

Required Arguments

algorithm: The algorithm to use.
input: The input to decode.
options: A table with options and other necessary data for the algorithm, as detailed below.

Options for each algorithm

tea (Tiny Encryption Algorithm)
- key: a key to decode the input with.

aes128 (Advanced Encryption Standard in CTR mode)
- key: a key to decode the input with.
- iv: the initialization vector that was generated by encodeString for this combination of data and encryption algorithm.

rsa (Rivest-Shamir-Adleman in OAEP with SHA-1 mode)
- key: a private key to decode the input.

BETA: NEW FEATURE (BUILD: 1.6.1 r22408)

base64 (Base64 Encoding Algorithm)
- variant: a string that defines the encoding variant. (Currently only "URL" is available)

BETA: NEW FEATURE (BUILD: 1.6.1 r22408)

base32 (Base32 Encoding Algorithm)
- variant: a string that defines the encoding variant. (Currently only "Hex" is available)

Optional Arguments

callback: providing a callback will run this function asynchronously, the arguments to the callback are the same as the returned values below.

Returns

Returns the decoded string if successful, false otherwise. If a callback was provided, the decoded string is argument to the callback.

Example

Adds an /decode command in which you can provide an algorithm, key and data to decode.

Click to collapse [-]

Server

addCommandHandler("decode", 
    function(player, _, algorithm, key, ...)
        if algorithm and key then
            local text = table.concat({...}, " ")
            if type(text) == "string" and text ~= "" then
                local decoded = decodeString(algorithm, text, { key = key })
                if decoded then
                    outputChatBox("The result of " .. algorithm .. " decoding is: " .. decoded, player)
                else
                    outputChatBox("Failed to decode. Make sure that all arguments are valid.", player, 255, 0, 0)
                end
            else
                outputChatBox("Please specify text in the command.", player, 255, 0, 0)
            end
        else
            outputChatBox("Invalid algorithm and/or key.", player, 255, 0, 0)
        end
    end
)

@@ Line 1: / Line 1: @@
 __NOTOC__
 {{Shared function}}
-{{New feature/item|3.0160|1.6|11849|
+{{New feature/item|3.0156|1.5.5|11849|
-This function decodes a data string using a specified algorithm.
+This function decodes an encoded [[string]] using the specified algorithm. The counterpart of this function is [[encodeString]].
 }}
 ==Syntax==
 <syntaxhighlight lang="lua">
-string|false decodeString ( string algorithm, string input, table options )
+string decodeString ( string algorithm, string input, [table options, function callback] )
 </syntaxhighlight>
@@ Line 13: / Line 13: @@
 *'''algorithm:''' The algorithm to use.
 *'''input:''' The input to decode.
-*'''options :''' A table with options and other neccessary data for the algorithm, as detailed below
+*'''options:''' A [[table]] with options and other necessary data for the algorithm, as detailed below.
 ===Options for each algorithm===
-* ''tea'':
+* ''tea'' ([https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm])
-** ''key'' (string) A key to tea-decode the input with
+** '''key''': a key to decode the input with.
+{{Added feature/item|1.5.9|1.5.8|20898|
+* ''aes128'' ([https://en.wikipedia.org/wiki/Advanced_Encryption_Standard Advanced Encryption Standard] in CTR mode)
+** '''key''': a key to decode the input with.
+** '''iv''': the initialization vector that was generated by [[encodeString]] for this combination of data and encryption algorithm.
+}}
+{{Added feature/item|1.5.9|1.5.8|21055|
+* ''rsa'' ([https://en.wikipedia.org/wiki/RSA_(cryptosystem) Rivest-Shamir-Adleman] in OAEP with SHA-1 mode)
+** '''key''': a private key to decode the input.
+|21055}}
+{{Added feature/item|1.6.0|1.6.1|22408|
+* ''base64'' ([https://en.wikipedia.org/wiki/Base64 Base64 Encoding Algorithm])
+** '''variant''': a string that defines the encoding variant. (Currently only "URL" is available)
+|22408}}
+{{Added feature/item|1.6.0|1.6.1|22408|
+* ''base32'' ([https://en.wikipedia.org/wiki/Base32 Base32 Encoding Algorithm])
+** '''variant''': a string that defines the encoding variant. (Currently only "Hex" is available)
+|22408}}
+===Optional Arguments===
+*'''callback:''' providing a callback will run this function asynchronously, the arguments to the callback are the same as the returned values below.
 ===Returns===
-Returns the decoded string if successful, ''false'' otherwise.
+Returns the decoded string if successful, ''false'' otherwise. If a callback was provided, the decoded string is argument to the callback.
 ==Example==
-{{Needs Example}}
+Adds an ''/decode'' command in which you can provide an algorithm, key and data to decode.
+<section name="Server" class="server" show="true">
+<syntaxhighlight lang="lua">
+addCommandHandler("decode",
+    function(player, _, algorithm, key, ...)
+        if algorithm and key then
+            local text = table.concat({...}, " ")
+            if type(text) == "string" and text ~= "" then
+                local decoded = decodeString(algorithm, text, { key = key })
+                if decoded then
+                    outputChatBox("The result of " .. algorithm .. " decoding is: " .. decoded, player)
+                else
+                    outputChatBox("Failed to decode. Make sure that all arguments are valid.", player, 255, 0, 0)
+                end
+            else
+                outputChatBox("Please specify text in the command.", player, 255, 0, 0)
+            end
+        else
+            outputChatBox("Invalid algorithm and/or key.", player, 255, 0, 0)
+        end
+    end
+)
+</syntaxhighlight>
+</section>
 ==See Also==
 {{Utility functions}}