FetchRemote: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(add legacy)
No edit summary
(3 intermediate revisions by the same user not shown)
Line 3: Line 3:
This function allows you to post and receive data from HTTP servers. The calls are asynchronous so you do not get an immediate result from the call, instead a callback function you specify is called when the download completes.
This function allows you to post and receive data from HTTP servers. The calls are asynchronous so you do not get an immediate result from the call, instead a callback function you specify is called when the download completes.


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.
If you are using fetchRemote to connect to a PHP script, you can use '''file_get_contents('php://input')''' to read the '''postData''' sent from this function.
{{Note|Client side function only works with the server the player is connected to unless the domain has been accepted with [[requestBrowserDomains]]}}
{{Note|Client side function only works with the server the player is connected to unless the domain has been accepted with [[requestBrowserDomains]]}}
{{ Warning| function won't trigger inside another fetchRemote function }}
{{ Warning| function won't trigger inside another fetchRemote function }}
{{ Warning| When using [[toJSON]] for submitting data, make sure to use '''string.sub(data, 2, -2)''' to remove the brackets as many APIs will not understand the request }}
{{ Warning| When using [[toJSON]] for submitting data, make sure to use '''string.sub(data, 2, -2)''' to remove the initial and final brackets, as many APIs will not understand the request }}


{{Legacy|legacy/fetchRemote}}
{{Legacy|legacy/fetchRemote}}


==Syntax==
<syntaxhighlight lang="lua">
bool fetchRemote ( string URL, [ string queueName = "default" ], [ int connectionAttempts = 10, int connectTimeout = 10000 ], function callbackFunction, [ string postData = "",  bool postIsBinary = false ], [ arguments... ] )
</syntaxhighlight>
===Required Arguments===
*'''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 server. The callback argument list should be:
**'''''responseData''''' - A string containing the remote response or "ERROR" if there was a problem
**'''''error''''' - A number containing the error number or zero if there was no error. A list of possible error values are:
{{Error_codes_for_callRemote_and_fetchRemote}}
<div style="padding-left:19px;">
*'''''arguments...''''' - The arguments that were passed into fetchRemote
</div>
===Optional Arguments===
{{New items|4.0153|1.5.3-9.11270|
*'''queueName:''' Name of the queue to use. Any name can be used. If not set, the queue name is "default". Requests in the same queue are processed in order, one at a time.
}}
*'''connectionAttempts:''' Number of times to retry if the remote host does not respond. ''In the case of a non-responding remote server, each connection attempt will timeout after 10 seconds. Therefore, the default setting of 10 connection attempts means it will be 100 seconds before your script gets a callback about the error. Reducing this value to 2 for example, will decrease that period to 20 seconds''
*'''connectTimeout:''' Number of milliseconds each connection attempt will take before timing out
*'''postData:''' A string specifying any data you want to send to the remote HTTP server.
*'''postIsBinary :''' A boolean specifying if the data is text, or binary.
*'''arguments:''' Any arguments you may want to pass to the callback.
{{New items|5.0154|1.5.4-9.11342|
==Syntax==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool fetchRemote ( string URL[, table options ], callback callbackFunction[, table callbackArguments ] )
bool fetchRemote ( string URL[, table options ], callback callbackFunction[, table callbackArguments ] )
</syntaxhighlight>  
</syntaxhighlight>


===Required Arguments===  
===Required Arguments===  
Line 66: Line 36:
**'''username:''' A string specifying the username for protected pages.
**'''username:''' A string specifying the username for protected pages.
**'''password:''' A string specifying the password for protected pages.
**'''password:''' A string specifying the password for protected pages.
{{New items|5.0154|1.5.4-9.11413|
**'''formFields:''' A table containing form items to submit. (for POST method only)  ''e.g.{ name&#61;"bob", email&#61;"[email protected]" }''
**'''formFields:''' A table containing form items to submit. (for POST method only)  ''e.g.{ name&#61;"bob", email&#61;"[email protected]" }''
}}
*'''arguments:''' A table containing arguments you may want to pass to the callback.
*'''arguments:''' A table containing arguments you may want to pass to the callback.
}}


===Returns===
===Returns===
{{New items|5.0154|1.5.7-9.20307|
Returns a '''''request''''' value which can be used with [[GetRemoteRequestInfo|getRemoteRequestInfo]] or [[AbortRemoteRequest|abortRemoteRequest]]
Returns a '''''request''''' value which can be used with [[GetRemoteRequestInfo|getRemoteRequestInfo]] or [[AbortRemoteRequest|abortRemoteRequest]]
}}


==Example==
==Example==
This example shows you how you can fetch an image from a web page, and transfer it to a particular client:
<section name="Server - Example 1" class="server" show="true">
<section name="Server" class="server" show="true">
Sending email via a web service (adopted from examples on https://documentation.mailgun.com/en/latest/user_manual.html)
<syntaxhighlight lang="lua">
 
function startImageDownload( playerToReceive )
    fetchRemote ( "http://www.example.com/image.jpg", myCallback, "", false, playerToReceive )
end
 
function myCallback( responseData, errorCode, playerToReceive )
    if errorCode == 0 then
        triggerClientEvent( playerToReceive, "onClientGotImage", resourceRoot, responseData )
    end
end
</syntaxhighlight>
</section>
<section name="Client" class="client" show="true">
<syntaxhighlight lang="lua">
addEvent( "onClientGotImage", true )
addEventHandler( "onClientGotImage", resourceRoot,
    function( pixels )
        if myTexture then
            destroyElement( myTexture )
        end
        myTexture = dxCreateTexture( pixels )
    end
)
 
addEventHandler("onClientRender", root,
    function()
        if myTexture then
            local w,h = dxGetMaterialSize( myTexture )
            dxDrawImage( 200, 100, w, h, myTexture )
        end
    end
)
</syntaxhighlight>
</section>
<br/>
{{New items|5.0154|1.5.4-9.11413|
Example sending email via a web service (adopted from examples on https://documentation.mailgun.com/en/latest/user_manual.html)
<section name="Server" class="server" show="true">
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
sendOptions = {
sendOptions = {
Line 145: Line 71:
</section>
</section>


Changing post content on IPS forum.
<section name="Server - Example 2" class="server" show="true">
<section name="Server" class="server" show="true">
Changing post content of an IPS forum thread via its API.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local apiKey = "12345678123456781234567812345678" -- key from ips admin panel
local apiKey = "12345678123456781234567812345678" -- key from ips admin panel
Line 165: Line 91:
</syntaxhighlight>
</syntaxhighlight>
</section>
</section>
}}
==Changelog==
{{ChangelogHeader}}
{{ChangelogItem|1.3.1-9.04605|Added connectionAttempts argument}}
{{ChangelogItem|1.3.2|Added client side}}
{{ChangelogItem|1.5.3-9.11270|Added queueName argument}}
{{ChangelogItem|1.5.4-9.11342|Added alternative syntax}}
{{ChangelogItem|1.5.4-9.11413|Added formFields}}


==See Also==
==See Also==
{{Resource_functions}}
{{Resource_functions}}

Revision as of 17:50, 7 November 2024

This function allows you to post and receive data from HTTP servers. The calls are asynchronous so you do not get an immediate result from the call, instead a callback function you specify is called when the download completes.

[[{{{image}}}|link=|]] Note: Client side function only works with the server the player is connected to unless the domain has been accepted with requestBrowserDomains
[[|link=|]] Warning: function won't trigger inside another fetchRemote function
[[|link=|]] Warning: When using toJSON for submitting data, make sure to use string.sub(data, 2, -2) to remove the initial and final brackets, as many APIs will not understand the request


Dialog-info.png This page describes the current implementation. For older versions check legacy version


Syntax

bool fetchRemote ( string URL[, table options ], callback callbackFunction[, table callbackArguments ] )

Required Arguments

  • URL: A full URL in the format http://hostname/path/file.ext. 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 server. The callback argument list should be:
    • responseData - A string containing the remote response
    • responseInfo - A table containing:
      • success - A boolean indicating if the request was successful.
      • statusCode - An integer status/error code
      • headers - A table containing the HTTP response headers
    • arguments... - The arguments that were passed into fetchRemote

Optional Arguments

  • options: A table containing any request options:
    • queueName: Name of the queue to use. Any name can be used. If not set, the queue name is "default". Requests in the same queue are processed in order, one at a time.
    • connectionAttempts: Number of times to retry if the remote host does not respond. (Defaults to 10)
    • connectTimeout: Number of milliseconds each connection attempt will take before timing out. (Defaults to 10000)
    • postData: A string specifying any data you want to send to the remote HTTP server.
    • postIsBinary : A boolean specifying if the data is text, or binary. (Defaults to false)
    • method: A string specifying the request method. (Defaults to GET or POST)
    • headers: A table containing HTTP request headers. e.g.{ Pragma="no-cache" }
    • maxRedirects: An integer limiting the number of HTTP redirections to automatically follow. (Defaults to 8)
    • username: A string specifying the username for protected pages.
    • password: A string specifying the password for protected pages.
    • formFields: A table containing form items to submit. (for POST method only) e.g.{ name="bob", email="[email protected]" }
  • arguments: A table containing arguments you may want to pass to the callback.

Returns

Returns a request value which can be used with getRemoteRequestInfo or abortRemoteRequest

Example

Click to collapse [-]
Server - Example 1

Sending email via a web service (adopted from examples on https://documentation.mailgun.com/en/latest/user_manual.html)

sendOptions = {
    queueName = "My Mailgun queue",
    connectionAttempts = 3,
    connectTimeout = 5000,
    formFields = {
        from="Excited User <[email protected]>",
        to="[email protected]",
        subject="Hello",
        text="Testing some Mailgun awesomness!",
    },
    username="api",
    password="key-3ax6xnjp29jd6fds4gc373sgvjxteol0",
}
fetchRemote( "https://api.mailgun.net/v3/samples.mailgun.org/messages", sendOptions, mailgunCompleteCallback )

function mailgunCompleteCallback(data, info)
    outputDebugString( "mailgunComplete"
            .. " success:" .. tostring(info.success)
            .. " statusCode:" .. tostring(info.statusCode)
            .. " data:" .. tostring(data)
            )
end
Click to collapse [-]
Server - Example 2

Changing post content of an IPS forum thread via its API.

local apiKey = "12345678123456781234567812345678" -- key from ips admin panel
local forumAddress = "https://yourForum.com"
function setPostContent(postID,content)
  local sendOptions = {
    queueName = "updatePost",
    connectionAttempts = 1,
    connectTimeout = 50,
    formFields = {
      post = content,
    },
  }
  fetchRemote( forumAddress.."/api/forums/posts/"..postID.."?key="..apiKey, sendOptions, function()end)
end

setPostContent(1, "this is a first post on this forum")

See Also