http_get_file

With this function, you can connect to the specified URL in order to retrieve information in the form of a file. As this is an asynchronous function, GameMaker will not block while waiting for a reply, but will keep on running unless it gets callback information. This information will be in the form of a string and will trigger an Async Event in any instance that has one defined in their object properties.

NOTE You should be aware that due to XSS protection in browsers, requests to and attempts to load resources from across domains are blocked and may appear to return blank results. Please see the part on Cross Domain Issues for further details.

This event will generate a "call back" which is picked up by any HTTP Events, in which case it will generate a DS Map (more commonly known as a "dictionary") that is exclusive to this event and is stored in the special variable async_load. This DS map will contain different values depending on the data being returned, ie: the event will trigger multiple times as each packet of data is received so that you can show a progress bar, for example. The general structure for the DS map will be as follows:

If there are multiple packets being returned to your game, the callback "status" key will return 1, in which case the DS map will have the following additional keys:

 

Syntax:

http_get_file(url, local_target);

Argument Type Description
url String The web address of the server that you wish to get file from
local_target String The local storage path to save the file to

 

Returns:

Async Request ID

 

Extended Example:

The http_get_file() function can be called from any event, and since it is asynchronous the callback can be almost instantaneous or could take several seconds. Calling the function is simple and would look something like this:

file = http_get_file("http://www.macsweeneygames.com/downloads/upgrade.zip", "\Downloads\Upgrade.zip");

The above code will request a file from the given URL and set it to be downloaded to the local storage area (as specified in the HTML5 Game Options), in a directory "Downloads" with the given file name (this does not have to be the same as the source file name, but should use the same file extension). The async_load map index will be stored in the variable "file" so you can check for the correct callback in the Asynchronous Event, and if the save directory does not exist, it will be created. The Asynchronous Event triggered would be the HTTP sub-event, and in that event you would have something like the following:

if ds_map_find_value(async_load, "id") == file
{
    var status = ds_map_find_value(async_load, "status");
    if status == 0
    {
        var path = ds_map_find_value(async_load, "result");
        var files = zip_unzip(path, "/NewContent/");
        if files > 0
        {
            global.ExtraContent = true;
        }
    }
}

The above code will first check the "id" of the ds_map that has been created, then check the status of the callback. If the value is equal to 0 (signalling success) the result from the callback will then be used along with the zip_unzip() function to unzip the downloaded file to the given directory. If the unzip succeeds a global variable is set to true.