Difference between revisions of "FetchRemote"

From Multi Theft Auto: Wiki
m (Optional Arguments: Arrange in the same order as the function Arguments)
Line 23: Line 23:
  
 
===Optional Arguments===  
 
===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 6 seconds. Therefore, the default setting of 10 connection attempts means it will be 60 seconds before your script gets a callback about the error. Reducing this value to 2 for example, will decrease that period to 12 seconds''
 
*'''postData:''' A string specifying any data you want to send to the remote HTTP server.
 
*'''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.
 
*'''postIsBinary :''' A boolean specifying if the data is text, or binary.
 
*'''arguments:''' Any arguments you may want to pass to the callback.
 
*'''arguments:''' Any arguments you may want to pass to the callback.
*'''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 6 seconds. Therefore, the default setting of 10 connection attempts means it will be 60 seconds before your script gets a callback about the error. Reducing this value to 2 for example, will decrease that period to 12 seconds''
 
  
 
===Returns===
 
===Returns===

Revision as of 16:44, 24 August 2013

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.

[[{{{image}}}|link=]] Note: Client side function only works with the server the player is connected to

Syntax

bool fetchRemote ( string URL[, int connectionAttempts = 10 ], callback 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
    • errno - 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 6 seconds. Therefore, the default setting of 10 connection attempts means it will be 60 seconds before your script gets a callback about the error. Reducing this value to 2 for example, will decrease that period to 12 seconds
  • 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

Returns true if the arguments are correct, false otherwise.

Example

This example shows you how you can fetch an image from a web page, and transfer it to a particular client:

Click to collapse [-]
Server

function startImageDownload( playerToReceive )
    fetchRemote ( "http://www.example.com/image.jpg", myCallback, "", false, playerToReceive )
end

function myCallback( responseData, errno, playerToReceive )
    if errno == 0 then
        triggerClientEvent( playerToReceive, "onClientGotImage", resourceRoot, responseData )
    end
end
Click to collapse [-]
Client
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 supported server 1.3.0-9.03739
Minimum supported client 1.3.2

Note: Using this function 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

See Also