http_get
-This function connects to the specified URL in order to retrieve information.
-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 HTTP Event in any instance that has one defined in its object events. You should also note that HTTP request parameters (the bits sometimes "tacked on" to the end of a URL when you submit a form on a web page) are perfectly acceptable when using this function, for example:
-http_get("http://www.example.com/logon?username={name}");
-will pass the string held in the variable name to the server as well as retrieve the data from that URL. So, essentially, any time a simple, short piece of data needs to be passed from the client to the server, this would be a reasonable choice as the function to use.
+This function sends a GET request to the specified URL in order to retrieve information.
+This is an asynchronous function, so 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 HTTP Event in any instance that has one defined in its object events.
Async Callback
This function will generate multiple "callbacks" which are picked up by any HTTP Events. These 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 whether there is data being returned or not. For example, if you have requested a file, the event will trigger multiple times as each packet of data is received so that you can show a progress bar, for example.
@@ -35,7 +34,7 @@
Syntax:
Syntax:
Returns:
Async Request ID (or -1 if something went wrong)
-
Extended Example:
-The http_get function can be called from any event, and since it's asynchronous the callback can be almost instantaneous or could take several seconds. Calling the function is simple and would look something like this:
-request_id = http_get("http://www.MacSweeneyGames.com/logon?username={name}");
+Example:
+The http_get function can be called from any event, and since it's asynchronous the callback can be almost instantaneous or could take several seconds. Calling the function is simple and looks something like this:
+request_id = http_get($"http://www.MacSweeneyGames.com/logon?username={name}");
The above code will pass the string held in the variable name to the given server as well as retrieve the data from that URL, triggering an Async Event which will contain the async_load DS map (the async_load map index will be stored in the variable request_id so you can check for the correct callback). The Async Event triggered would be the HTTP sub-event, and in that event you would have the following:
Async HTTP Event
-if (ds_map_find_value(async_load, "id") == request_id)
+
if (async_load[? "id"] == request_id)
{
var _status = async_load[? "status"];
var _r_str = (_status == 0) ? async_load[? "result"] : "null";
}
The above code first checks the ID of the async request, then assigns a value to _r_str depending on the "status" of the callback. If the value is equal to 0 (signalling success), the result from the callback is stored in a variable for future use, otherwise the variable is set to a default value (in this case "null").
+The above code first checks the ID of the async request, then assigns a value to _r_str depending on the "status" of the callback. If the value is equal to 0 (signalling the request completed), the result from the callback is stored in a variable for future use, otherwise the variable is set to a default value (in this case "null").
http_get_file
This function connects 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 HTTP Event in any instance that has one defined in their object events.
Async Callback
This event will generate a "callback" 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, i.e.: the event will trigger multiple times as each packet of data is received so that you can show a progress bar, for example.
@@ -33,7 +34,7 @@
Syntax:
Syntax:
Returns:
Async Request ID (or -1 if something went wrong)
-
Extended Example:
+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:
request_id = 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:
+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's "id" will be stored in the variable request_id 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:
Async HTTP Event
-if (ds_map_find_value(async_load, "id") == request_id)
+
if (async_load[? "id"] == request_id)
{
- var _status = ds_map_find_value(async_load, "status");
+ var _status = async_load[? "status"];
if (_status == 0)
{
- var _path = ds_map_find_value(async_load, "result");
+ var _path = async_load[? "result"];
var _files = zip_unzip(path, "/NewContent/");
if (_files > 0)
{
@@ -64,7 +65,7 @@
Extended Example:
}}
} -
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.
+The above code will first check the "id" of the request, then check the status of the request. If the value is equal to 0 (signalling completed), the result 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.
http_post_string
-In computing, a post request is used when the client needs to send data to the server as part of the retrieval request, such as when uploading a file or submitting a completed form, and the same is true of this function in GameMaker. In contrast to the http_get request method where only a URL is sent to the server, http_post_string also includes a string that is sent to the server and may result in the creation of a new resource on the server, the update of an existing one, or both.
-It should be noted that HTTP request parameters (the bits sometimes "tacked on" to the end of a URL when you submit a form on a web page) are perfectly acceptable when using this function too.
+This function posts a string using the HTTP POST method.
+In computing, a post request is used when the client needs to send data to the server as part of the retrieval request, such as when uploading a file or submitting a completed form, and the same is true of this function in GameMaker. In contrast to the http_get request method where only a URL is sent to the server, http_post_string also includes a string that is sent to the server and may result in the creation of a new resource on the server, the update of an existing one, or both.
Async Callback
This event will generate a "callback" 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 whether there is data being returned or not. For example, if you have requested a file, the event will trigger multiple times as each packet of data is received so that you can show a progress bar, for example.
@@ -34,7 +35,7 @@
Syntax:
Syntax:
Returns:
Async Request ID (or -1 if something went wrong)
-
Extended Example:
+Example:
The http_post_string 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:
var _str = $"name={player_name}&score={player_score}";
request_id = http_post_string("http://www.angusgames.com/game?game_id={global.game_id}", _str);
The above code sends a retrieval request to the specified URL with the given parameters as well as sending the additional data (player name and score in URL-encoded form) stored in the variable _str. This will trigger all defined asynchronous Http Events if a callback is received, and you can check the "id" returned against that stored in the variable request_id to make sure that you run the correct code should you have used various http_post_string functions. The following example code shows how this would be done:
Async HTTP Event
var _r_str = "null";
- if (ds_map_find_value(async_load, "id") == request_id)
+ if (async_load[? "id"] == request_id)
{
- if (ds_map_find_value(async_load, "status") == 0)
+ if (async_load[? "status"] == 0)
{
- _r_str = ds_map_find_value(async_load, "result");
+ _r_str = async_load[? "result"];
}
}
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 stored in a variable for future use, otherwise the variable will simply hold a default value (in this case "null").
+The above code will first check the ID of the request, then check the status of the callback. If the value is equal to 0 (signalling completed) the result from the callback will then be stored in a variable for future use, otherwise the variable will simply hold a default value (in this case "null").
http_request
-This function creates an HTTP request and sends it.
-An HTTP request can be used for many things like (for example) authentication via HTTP headers if you use RESTful APIs.
-The function requires the full IP address of the server to request from as well as the type of request to make: "GET", "HEAD", "POST", "PUT", "DELETE", "TRACE", "OPTIONS" or "CONNECT". You'll also need to supply a DS Map of key/value pairs (as strings, where the key is the header field and the value is the required data for the header). The final argument is an optional data string that you can add to the request, and if it's not needed then it can be either 0 or an empty string "". Note that you can also send a buffer (see the section on Buffers for more details), in which case the last argument would be the handle to the buffer to send.
-The function returns an Async Request ID which can be used to identify its callback, as described below.
-Usage Notes
+This function creates a generic HTTP request and sends it.
+A HTTP request can be used for many things like (for example) authentication via HTTP headers if you use RESTful APIs.
+The function requires:
-
-
- HTTP headers normally follow the format "key:value", but since GameMaker creates these pairs for you from the DS map there is no need to include the colon ":" in your map key or value strings. -
- When using a buffer for the body argument, if the buffer seek position is at the start (0) then no body is sent and the buffer is filled with the response from the HTTP call, but if the buffer seek position is non-zero, then the buffer string content is sent as the body. +
- The URL to request. See URLs +
- The request method: "GET", "HEAD", "POST", "PUT", "DELETE", "TRACE", "OPTIONS" or "CONNECT". +
- A DS Map of key/value pairs containing the HTTP headers "key:value" (as strings, where the key is the header field and the value is the required data for the header). Note that key and value strings shouldn't include the colon ":". +
- An optional request body, which can be:
+
-
+
- A data String (can be an empty string "" for an empty body) +
- A Buffer (for binary data). If the seek position is at the start (0), no body is sent and the buffer is filled with the response from the HTTP call. If the seek position is non-zero, the entire buffer contents (up to buffer_set_used_size) are sent as the body. +
The function returns an Async Request ID which can be used to identify its callback, as described below.
+Async Callback
-This event will generate a "callback" which is picked up by any Async HTTP Events, in which case it will generate a DS Map that is exclusive to this event and is stored in the special variable async_load. This DS map has the following two keys related to the request function:
+This function will generate "callbacks" which are picked up by any Async HTTP Events, in which case it will generate a DS Map that is exclusive to this event and is stored in the special variable async_load. This DS map has the following two keys related to the request function:
-
-
- id: The ID which was returned from the function. If you fire off a series of http_* requests then you need to know which one you are getting the reply to, and so you would use this value to compare to the value you stored when you originally sent the request to find the right one. -
- response_headers: If this has a value greater than or equal to 0, it holds a DS map that contains the HTTP headers returned with the response to the HTTP request. +
- "id": The ID which was returned from the function. If you fire off a series of http_* requests then you need to know which one you are getting the reply to, and so you would use this value to compare to the value you stored when you originally sent the request to find the right one. +
- "response_headers": If this has a value greater than or equal to 0, it holds a DS map that contains the HTTP headers returned with the response to the HTTP request.
Syntax:
@@ -44,7 +50,7 @@Syntax:
Syntax:
Example:
var _data="utf8=%E2%9C%93&authenticity_token=kPmS14DcYcuKgMFZUsN3XFfj3mhs%3D&product%5Bname%5D=CatchTheHaggis&product%5Bproduct_id%5D=http_test&commit=Create+Product";request_id = http_request("http://225.0.0.97:3000/products", "POST", _headers, _data);
ds_map_destroy(_headers); -
The above code creates a DS map with the relevant HTTP headers for the function, then creates a data string for use as this is a POST request. Finally the function is called, with its ID value being stored in the instance variable request_id for checking in the HTTP asynchronous event.
+The above code creates a DS map with the relevant HTTP headers for the request, then creates a data string for use as this is a POST request. Finally, the function is called, with its ID value being stored in the instance variable request_id for checking in the HTTP asynchronous event.
HTTP
-
The HTTP Event is one that is triggered by the callback from one of the http_*() functions, like http_post_string. It actually generates a DS Map that is exclusive to this event and is stored in the special variable async_load (please see the individual functions for code examples that explain the use of this event in further detail). This DS map has the following general structure:
-
-
- "id": The ID which was returned from the command. If you fire off a series of http_* requests then you need to know which one you are getting the reply to, and so you would use this value to compare to the value you stored when you originally sent the request to find the right one. -
- "status": Holds a value of less than 0 for an error, 0 for success and 1 if content is being downloaded. -
- "result": The data received (string only), or the path to the file downloaded if you have used http_get_file. You may only get this key if the status is 0, but that is platform-dependent. -
- "url": The complete URL you requested. -
- "http_status": The raw HTTP status code (if available). This returns the standard web status code for most browsers, e.g.: 304 for "Not Modified", 204 for "No Content", etc. -
The above shows what you get when you use the http_post_string function, but each of the http_* functions may return a slightly different map, so please refer to the manual entry for each function to find out the precise data that is returned for it.
-As async_load creates a DS map, these functions are particularly useful when coupled with the json_encode and json_decode functions.
-There could also be additional data supplied by this map if you have requested files for downloading. In this case, the "status" will have a value of 1 and the DS map will hold these extra keys:
--
-
- "contentLength": This is the size of file that the web server has said you should expect to receive (may be -1 if the server does not return this data). -
- "sizeDownloaded": The size of the data that has already been downloaded. -
Note that the event will not be triggered for every single data packet that is received, but will rather update at any time during the download within the main game loop. Also note that currently this functionality is only available for regular Windows target platforms.
++
The Async HTTP Event is triggered by the callback from one of the http_*() functions, like http_post_string. It isn't triggered for every single data packet that is received, but rather updates within the main game loop during the download.
A DS Map that is exclusive to this event and is stored in the special variable async_load can be accessed in this event (please see the individual functions for code examples that explain the use of this event in further detail).
+