Template:Modules/Sockets/Functions: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
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.
This function creates a socket.
 
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.
 
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==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool callRemote ( string host, string resourceName, string functionName, callback callbackFunction, [ arguments... ] )
userdata sockOpen ( string host, int port )
</syntaxhighlight>
</syntaxhighlight>
'''OR'''
<syntaxhighlight lang="lua">
bool callRemote ( string URL, callback callbackFunction, [ arguments... ] )
</syntaxhighlight>  


===Required Arguments===  
===Required Arguments===  
*'''host:''' This is a host name - including the '''HTTP''' port - of the server you wish to connect to.
*'''host:''' This is a host name e.g. "www.google.com"
*'''resourceName:''' This is a name of the resource that contains the exported function you want to call.
*'''Port:''' This is the port on which to connect e.g. 80
*'''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===
Returns ''true'' if the function has been called, ''false'' otherwise.
Returns 'userdata' if the correct arguments were given ''false'' otherwise.


==Example==
==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.
This example shows you how you can connect to irc.


'''PHP:''' (for the page that LUA expects to be at ''<nowiki>http://www.example.com/page.php</nowiki>'')
'''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">
<syntaxhighlight lang="lua">
function outputChatBoxRemote ( playerName, message, type, serverport )
local socket = sockOpen("irc.gtanet.com",80)
    if serverport ~= getServerPort() then
        outputChatBox ( "From " .. playerName .. " on " .. serverport .. ": " .. message )
    end
end


function playerChatCallback()
addEventHandler("onSockOpened",getRootElement(),
end
  function (sock)
 
      if sock == socket then
function playerChat ( message, type )
        sockWrite(socket,"USER IRCbot botname * :Gamesnert & MCvarial")
    callRemote ( "play.mtabeta.com:33004", getResourceName(getThisResource()), "outputChatBoxRemote", playerChatCallback, getPlayerName(source), message, type, getServerPort() )
        sockWrite(socket,"NICK botname")
    callRemote ( "play.mtabeta.com:33005", getResourceName(getThisResource()), "outputChatBoxRemote", playerChatCallback, getPlayerName(source), message, type, getServerPort() )
      end
    callRemote ( "play.mtabeta.com:33006", getResourceName(getThisResource()), "outputChatBoxRemote", playerChatCallback, getPlayerName(source), message, type, getServerPort() )
  end
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>
</syntaxhighlight>


'''ACL #2:'''
'''Important Note''': ''Sockets are asynchronous this means if sockOpen() return true it doesn't mean it's already created!''
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==
==See Also==

Revision as of 13:12, 25 April 2010

This function creates a socket.

Syntax

userdata sockOpen ( string host, int port )

Required Arguments

  • host: This is a host name e.g. "www.google.com"
  • Port: This is the port on which to connect e.g. 80

Returns

Returns 'userdata' if the correct arguments were given false otherwise.

Example

This example shows you how you can connect to irc.

PHP: (for the page that LUA expects to be at http://www.example.com/page.php) 

local socket = sockOpen("irc.gtanet.com",80)

addEventHandler("onSockOpened",getRootElement(),
   function (sock)
      if sock == socket then
         sockWrite(socket,"USER IRCbot botname * :Gamesnert & MCvarial")
         sockWrite(socket,"NICK botname")
      end
   end
)

Important Note: Sockets are asynchronous this means if sockOpen() return true it doesn't mean it's already created!

See Also

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