EncodeString: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
mNo edit summary
(Specify that the AES-128 cipher exposed by this function uses CTR mode)
(12 intermediate revisions by 7 users not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
{{Shared function}}
{{Shared function}}
{{New feature/item|3.0160|1.6|11849|
{{New feature/item|3.0156|1.5.5|11849|
This function encodes a string using a specified algorithm.
This function encodes a [[string]] using the specified algorithm. The counterpart of this function is [[decodeString]].
}}
}}


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


Line 13: Line 13:
*'''algorithm:''' The algorithm to use.
*'''algorithm:''' The algorithm to use.
*'''input:''' The input to encode.
*'''input:''' The input to encode.
*'''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===
===Options for each algorithm===
* ''tea'':
* ''tea'' ([https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm])
** ''key'' (string) A key to tea-encode the input with
** '''key''': a key to encode the input with.
{{New items|3.0159|1.5.8|
* ''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}}


===Returns===
===Optional Arguments===
Returns the encoded string if successful, ''false'' otherwise.
{{New items|3.0158|1.5.7|
*'''callback:''' providing a callback will run this function asynchronously, the arguments to the callback are the same as the returned values below.
|20394}}
===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==
==Example==  
{{Needs 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==
==See Also==
{{Utility functions}}
{{Utility functions}}

Revision as of 15:17, 22 August 2021

This function encodes a string using the specified algorithm. The counterpart of this function is decodeString.

Syntax

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

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

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.
  • 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 (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.

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.

Click to collapse [-]
Server
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
)

See Also