EncodeString

2022-01-19T19:38:40Z

Incama: Added a small tip about the performance implications of aes128 vs tea

__NOTOC__
{{Shared function}}
{{New feature/item|3.0156|1.5.5|11849|
This function encodes a [[string]] using the specified algorithm. The counterpart of this function is [[decodeString]].
}}

{{Tip|If it doesn't matter which algorithm you use for the encoding, keep in mind that ''aes128'' uses hardware acceleration so it may outperform the ''tea'' algorithm on most processors.}}

==Syntax==
<syntaxhighlight lang="lua">
string encodeString ( string algorithm, string input, table options [, function callback ] )
</syntaxhighlight>

===Required Arguments===
*'''algorithm:''' The algorithm to use.
*'''input:''' The input to encode.
*'''options:''' A [[table]] with options and other necessary data for the algorithm, as detailed below.

===Options for each algorithm===
* ''tea'' ([https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm])
** '''key''': a key to encode 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 encode the input with (must be 16 characters long).
|20898}}

===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 for each algorithm===
* ''tea''
** '''encodedString''': the encoded string if successful, ''false'' otherwise. If a callback was provided, ''true'' is returned immediately, and the encoded string is passed as an argument to the callback.
{{New items|3.0159|1.5.8|
* ''aes128''
** '''encodedString''': the encoded string if successful, ''false'' otherwise. If a callback was provided, ''true'' is returned immediately, and the encoded string is passed as an argument to the callback.
** '''iv''' ([https://en.wikipedia.org/wiki/Initialization_vector Initialization vector]): this is a string generated by the encryption algorithm that is needed to decrypt the message by [[decodeString]]. If a callback was provided, ''true'' is returned immediately, and the ''iv'' is passed as an argument to the callback.
|20898}}

==Example==
Adds an ''/encode'' command in which you can provide an algorithm, key and data to encode. Below is the example provided as both server-side and client-side variations.

<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
addCommandHandler("encode",
function(player, _, algorithm, key, ...)
if algorithm and key then
local text = table.concat({...}, " ")
if type(text) == "string" and text ~= "" then
local encoded = encodeString(algorithm, text, { key = key })
if encoded then
outputChatBox("The result of " .. algorithm .. " encoding is: " .. encoded, player)
else
outputChatBox("Failed to encode. 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}}

Multi Theft Auto: Wiki - User contributions [en]

EncodeString