FetchRemote: Difference between revisions
Jump to navigation
Jump to search
Fernando187 (talk | contribs) (Remove obsolete Requirements section) |
Fernando187 (talk | contribs) No edit summary |
||
(4 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. | ||
{{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}} | |||
{{ | |||
==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 63: | 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. | ||
**'''formFields:''' A table containing form items to submit. (for POST method only) ''e.g.{ name="bob", email="[email protected]" }'' | **'''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. | *'''arguments:''' A table containing arguments you may want to pass to the callback. | ||
===Returns=== | ===Returns=== | ||
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== | ||
<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"> | <syntaxhighlight lang="lua"> | ||
sendOptions = { | sendOptions = { | ||
Line 142: | Line 71: | ||
</section> | </section> | ||
<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 162: | Line 91: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
</section> | </section> | ||
==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.
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 1Sending 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 2Changing 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
- abortRemoteRequest
- call
- fetchRemote
- getResourceConfig
- getResourceDynamicElementRoot
- getResourceExportedFunctions
- getResourceFromName
- getResourceName
- getResourceRootElement
- getResourceState
- getThisResource
- getRemoteRequests
- getRemoteRequestInfo