Template:Modules/Sockets/Functions: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
(Replaced content with '* sockOpen * sockWrite * sockClose')
 
(6 intermediate revisions by one other user not shown)
Line 1: Line 1:
This function allows you to call functions that have been exported with HTTP access by other MTA servers. The calls are asynchronous so you do not get an immediate result from the call. You can also use this function to access any standard web page by specifying the URL.
* [[Modules/Sockets/sockOpen|sockOpen]]
 
* [[Modules/Sockets/sockWrite|sockWrite]]
Data is passed to the web page via HTTP POST as ''raw'' [[JSON]] data. The page should return JSON formated data in the page's body.
* [[Modules/Sockets/sockClose|sockClose]]
 
You can use the [[PHP SDK]] to create PHP pages that can be called by this function. See the PHP SDK page for an example.
 
In the case when the call fails, a string containing "ERROR" followed by an integer containing the error reason will be passed to the callback function. The reason for failure will be similar to errors found with websites - file not found, server not found and timeouts.
 
==Syntax==
<syntaxhighlight lang="lua">
bool callRemote ( string host, string resourceName, string functionName, callback callbackFunction, [ arguments... ] )
</syntaxhighlight>
'''OR'''
<syntaxhighlight lang="lua">
bool callRemote ( string URL, callback callbackFunction, [ arguments... ] )
</syntaxhighlight>
 
===Required Arguments===
*'''host:''' This is a host name - including the '''HTTP''' port - of the server you wish to connect to.
*'''resourceName:''' This is a name of the resource that contains the exported function you want to call.
*'''functionName:''' This is a string with the name of the function which you want to call.
*'''URL:''' A full URL in the format ''<nowiki>http://hostname/path/file.ext</nowiki>''. A port can be specified with a colon followed by a port number appended to the hostname.
*'''callbackFunction:''' This is the function that should receive the data returned from the remote function call. The argument list should match the format of the data returned. The callback function will be passed a string containing "ERROR" followed by an integer indicating the error code when an error occurs calling the function. A list of error codes can be found on the [http://curl.haxx.se/libcurl/c/libcurl-errors.html cURL website].
 
===Optional Arguments===
{{OptionalArg}}
*'''arguments:''' Any arguments you may want to pass to the function when it is called. Any number of arguments of can be specified, each being passed to the designated function. Most data types can be passed, including tables. The only values that cannot be passed are 'userdata' values such as xmlnodes - elements and resources can be passed though may be misinterpreted on other game servers (or cause warnings).
 
===Returns===
Returns ''true'' if the function has been called, ''false'' otherwise.
 
==Example==
This example shows you how you can call a PHP page from a lua script. It just adds two numbers passed to it by the script and outputs these in the chat box.
 
'''PHP:''' (for the page that LUA expects to be at ''<nowiki>http://www.example.com/page.php</nowiki>'')
<syntaxhighlight lang="lua">[php]
include( "mta_sdk.php" );
$input = mta::getInput();
mta::doReturn($input[0] + $input[1]);
</syntaxhighlight>
'''LUA:'''
<syntaxhighlight lang="lua">
-- result is called when the function returns
function result(sum)
    if sum ~= "ERROR" then
        outputChatBox(sum)
    end
end
function addNumbers(number1, number2)
    callRemote ( "http://www.example.com/page.php", result, number1, number2 )
end
addNumbers ( 123, 456 ) -- call the function
</syntaxhighlight>
 
<hr>
 
'''Example 2:''' This example shows how you can join up multiple servers so they can share chat messages.
 
'''Meta.xml'''
First, add ''outputChatBoxRemote'' as an HTTP exported function in your resource's meta.xml:
<syntaxhighlight lang="xml">
<export function="outputChatBoxRemote" http="true" />
</syntaxhighlight>
 
'''LUA:''' Next, add this to a server-side script in your resource:
<syntaxhighlight lang="lua">
function outputChatBoxRemote ( playerName, message, type, serverport )
    if serverport ~= getServerPort() then
        outputChatBox ( "From " .. playerName .. " on " .. serverport .. ": " .. message )
    end
end
 
function playerChatCallback()
end
 
function playerChat ( message, type )
    callRemote ( "play.mtabeta.com:33004", getResourceName(getThisResource()), "outputChatBoxRemote", playerChatCallback, getPlayerName(source), message, type, getServerPort() )
    callRemote ( "play.mtabeta.com:33005", getResourceName(getThisResource()), "outputChatBoxRemote", playerChatCallback, getPlayerName(source), message, type, getServerPort() )
    callRemote ( "play.mtabeta.com:33006", getResourceName(getThisResource()), "outputChatBoxRemote", playerChatCallback, getPlayerName(source), message, type, getServerPort() )
end
addEventHandler ( "onPlayerChat", getRootElement(), playerChat )
</syntaxhighlight>
 
'''ACL:'''
Then, modify the ACL on each sending server to allow access to callRemote:
<syntaxhighlight lang="xml">
<group name="OutRPCGroup">
    <acl name="OutRPC" />
    <object name="resource.examplechat" />
</group>
<acl name="OutRPC">
    <right name="function.callRemote" access="true" />
</acl>
</syntaxhighlight>
 
'''ACL #2:'''
Finally, modify the ACL on each receiving server to allow guest http communication with your resource:
<syntaxhighlight lang="xml">
<group name="InRPCGroup">
    <acl name="InRPC" />
    <object name="user.http_guest" />
</group>
<acl name="InRPC">
    <right name="general.http" access="true" />
    <right name="resource.examplechat" access="true" />
    <right name="resource.resourcebrowser" access="false" />
    <right name="resource.webstats" access="false" />
    <right name="resource.webmap" access="false" />
    <right name="resource.webadmin" access="false" />
    <right name="resource.scoreboard" access="false" />
    <right name="resource.runcode" access="false" />
    <right name="resource.resourcemanager" access="false" />
    <right name="resource.mapmanager" access="false" />
    <right name="resource.admin" access="false" />
    <right name="resource.elementbrowser" access="false" />
    <right name="resource.easytext" access="false" />
</acl>
</syntaxhighlight>
'''Important Note''': ''When enabling 'general.http' on an ACL which has a user with no password (i.e. user.* or user.guest or user.http_guest), it is essential that you explicitly block access to resources that contain exported http functions.''
 
==See Also==

Latest revision as of 14:16, 25 April 2010

Retrieved from "https://wiki.multitheftauto.com/wiki/Template:Modules/Sockets/Functions?oldid=23081"