SA-MP Mobile

    +---------------------------------------------------------------------------------------------------------+

    File information
    ----------------

    vlang - Create & Manage server langauge(s) and server messages
    Build 2 - Beta (11/6/2020)

    Author: H2O
    Licensed under GNU GPLv3

    © 2018-2020 H2O Multiplayer. All rights reserved.
    Website: h2omultiplayer.com

    Table Structure
    ---------------

    The following tables has to exist in your database for vlang to work.
    If ever asked to provide a MySQL handle, use your gamemode's.

    * Languages
        + ID ( Language ID - Primary key - Auto increment - INT(11) )
        + LanguageName ( The name of created language - Unique key - TINYTEXT(25) )
    * Messages
        + ID ( Message - Primary - INT(11) )
        + LanguageId ( The language ID that this message is created for - INT(11) )
        + Identifier ( The identifier used to search for the message, short description - VARCHAR(255) )
        + Message ( The actual long message we want to send :) - VARCHAR(1024) )

    * is table, + is column

    Dependencies
    ------------

    * a_mysql - The MySQL Plugin (Recommended version: R41-2) - Originally made by BlueG and maintained later by maddinat0r
    * y_hooks - included in the YSI library [Useful for hooking functions/callbacks/natives] - Original Author: ******
    * y_va - also included in the YSI library [We use this to format our messages using arguments] - Original Author: ******
    * GVar - Made by Incognito - We will use this instead of using array to return data directly.
    * a_samp - Made by the SA-MP team

    Remarks
    -------

    * You need to define 'FILTERSCRIPT' in case this script is to be used in a filterscript and not a gamemode.
    * This include uses threaded MySQL queries, which do not run in the server's main thread.
    * As a result of the above remark, the following precautions should be considered:
        - Language creation and message loading isn't instant and depends on how fast the query is excuted.
        - Rest of code already processes without pausing till the query is executed.
        - That means you can't return a message straight after loading/creating it.
    * Language has to be created first before returning any message coming from it.
    * All the messages for a specific language get automatically loaded once the language itself is loaded.
    * Do not use vL_CreateMessage if the messages for specific language already exist, they will get loaded automatically.

    Configuration
    -------------

    * MAX_VLANGS - The system will be told to stop creating languages after it meets this value
    * MAX_VMESSAGES - The system will stop creating messages ahead of this value
    * (define before including) VLANG_PLAYER_FUNCS - Only if you wish to use the per-player language functions
    * (define before including) VLANG_ALIAS - Only if you wish to use function aliases (look down for info)

    Errors
    ------

    #define VL_ERROR_INVALID_HANDLE         (-2) // If the MySQL connection isn't valid
    #define VL_ERROR_OUT_OF_LIMIT           (-3) // If you exceeded the configuration limits
    #define VL_ERROR_UNABLE_TO_PROCEED      (-4) // If the function failed for some reason to do what is expected
    #define VL_ERROR_DUPLICATE              (-5) // If you try to create a message that ALREADY exists

    The include's debug messages can be useful to troubleshoot issues, not to mention you can create yours!

    Aliases
    -------

    Following aliases can be used if enabled in configuration:
    #define AddLanguage                 vL_CreateLanguage
    #define AddMessage                  vL_CreateMessage
    #define GetLanguagePrefixByName     vL_GetLanguage
    #define GetMessage                  vL_ReturnMessage

    Installation
    ------------

    1. Download and prepare all the dependencies
    2. Create all the tables in the table structure above
    3. Make sure your gamemode or filterscript have a MySQL connection handle
    4. Configure the include to fit your needs
    5. Populate your database with languages/messages data.
    6. Add your language and the messages should be loaded already.
    7. Use your message identifier and language name to simply return the message!

    Functions
    ---------

    Some functions are designed for internal usage, below are list of usable functions:

    - General Functions
         - vL_GetLanguage(const LangName[25])
            Returns: Language Id if the language name exists - or otherwise returns 0

        - vL_CreateLanguage(MySQL: Handle, const LangName[25])
            Parameters:
                - Handle: Your MySQL handle
                - LangName: Language name to create or load
            Returns:
                - An error value if something happened, check errors ^
                - 1 if there was no error
            Notes:
                - Any messages found in the database will AUTOMATICALLY get loaded!

        - vL_ReturnMessage(const LangName[25], const Identifier[255], va_args<>)
            Parameters:
                - LangName: The language (that should be existent) to return messages for
                - Identifier: The unique identifier for this message
                - (optional) va_args: Any arguments needed for your message (specifier args)
            Returns:
                - A null string if language is invalid, or the actual message if succesful (or identifier if message didn't exist!)

    - (if defined) Per player language functions
        - SetPlayerLanguage(playerid, const LangName[25])
            Description: Set a player's language (if exists ONLY) to the specified LangName value

        - GetPlayerLanguage(playerid)
            Description: Returns the player's language name that was assigned to them beforehand (null by default)

    Example Usage

    - Add on initialization
        vL_CreateLanguage(Database, "English");
        vL_CreateLanguage(Database, "Spanish");

    - Add somewhere else
        vL_CreateMessage(Database, "English", "COMMON_IDENT", "Testing...");
    	vL_CreateMessage(Database, "Spanish", "COMMON_IDENT", "Pruebas...");

    - Display somewhere else
        print(vL_ReturnMessage("English", "COMMON_IDENT"));
    	print(vL_ReturnMessage("Spanish", "COMMON_IDENT"));

    - Expected output
        Both messages should be displayed in the two languages

    It's worth to mention that if you create the messages once, they are stored in the database.
    That means you don't need to keep creating them every time, even if it won't hurt!

    +---------------------------------------------------------------------------------------------------------+