FetchRemote: Difference between revisions
.WhiteBlue (talk | contribs) m (Changed string "errno" to "error".) |
m ("error" is a reserved keyword.) |
||
(3 intermediate revisions by 2 users not shown) | |||
Line 10: | Line 10: | ||
==Syntax== | ==Syntax== | ||
<syntaxhighlight lang="lua"> | <syntaxhighlight lang="lua"> | ||
bool fetchRemote ( string URL[ | bool fetchRemote ( string URL, [ string queueName = "default" ], [ int connectionAttempts = 10, int connectTimeout = 10000 ], function callbackFunction, [ string postData = "", bool postIsBinary = false ], [ arguments... ] ) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Line 82: | Line 82: | ||
end | end | ||
function myCallback( responseData, | function myCallback( responseData, errorCode, playerToReceive ) | ||
if | if errorCode == 0 then | ||
triggerClientEvent( playerToReceive, "onClientGotImage", resourceRoot, responseData ) | triggerClientEvent( playerToReceive, "onClientGotImage", resourceRoot, responseData ) | ||
end | end | ||
Line 113: | Line 113: | ||
<br/> | <br/> | ||
{{New items|5.0154|1.5.4-9.11413| | {{New items|5.0154|1.5.4-9.11413| | ||
Example sending email via a web service (adopted from examples on https://documentation.mailgun.com/user_manual.html) | 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"> | <section name="Server" class="server" show="true"> | ||
<syntaxhighlight lang="lua"> | <syntaxhighlight lang="lua"> |
Latest revision as of 18:10, 30 December 2021
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 |
Warning: function won't trigger inside another fetchRemote function |
Syntax
bool fetchRemote ( string URL, [ string queueName = "default" ], [ int connectionAttempts = 10, int connectTimeout = 10000 ], function callbackFunction, [ string postData = "", bool postIsBinary = false ], [ arguments... ] )
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 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:
- 1-89: See cURL website or its mirror at cURL errors
- 400-599: See HTTP status codes
- 1002: Download aborted
- 1003: Failed to initialize
- 1004: Unable to parse url
- 1005: Unable to resolve host name
- 1006: Destination IP not allowed
- 1007: File error
- arguments... - The arguments that were passed into fetchRemote
Optional Arguments
- 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.
Returns
Example
This example shows you how you can fetch an image from a web page, and transfer it to a particular client:
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
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 )
Requirements
Minimum server version | 1.3.0-9.03739 |
---|---|
Minimum client version | 1.3.2 |
Note: Using this feature requires the resource to have the above minimum version declared in the meta.xml <min_mta_version> section. e.g. <min_mta_version server="1.3.0-9.03739" client="1.3.2" />
Changelog
Version | Description |
---|
1.3.1-9.04605 | Added connectionAttempts argument |
1.3.2 | Added client side |
1.5.3-9.11270 | Added queueName argument |
1.5.4-9.11342 | Added alternative syntax |
1.5.4-9.11413 | Added formFields |
See Also
- addResourceConfig
- addResourceMap
- callRemote
- copyResource
- createResource
- deleteResource
- getResourceACLRequests
- getResourceInfo
- getResourceLastStartTime
- getResourceLoadFailureReason
- getResourceLoadTime
- getResourceMapRootElement
- getResourceOrganizationalPath
- getResources
- isResourceArchived
- isResourceProtected
- refreshResources
- removeResourceFile
- renameResource
- restartResource
- setResourceInfo
- startResource
- stopResource
- updateResourceACLRequest
Shared
- call
- fetchRemote
- getResourceConfig
- getResourceDynamicElementRoot
- getResourceExportedFunctions
- getResourceFromName
- getResourceName
- getResourceRootElement
- getResourceState
- getThisResource
- getRemoteRequests
- getRemoteRequestInfo
- abortRemoteRequest