Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Sidorakh/http.gml

A simple http wrapper for GameMaker Studio 2
https://github.com/Sidorakh/http.gml

gamemaker gamemaker-studio-2 gamemakerstudio2 http

Last synced: 10 days ago
JSON representation

A simple http wrapper for GameMaker Studio 2

Awesome Lists containing this project

README 

        



# http.gml v2.0

A complete rewrite of http.gml. It's much nicer now. 



# Documentation is now located at [docs.sidorakh.net/http.gml](https://docs.sidorakh.net/http.gml)

Trust me, it's better that way



The old documentation is below for posterity



----



## http(url, method, body, options, callback, [error], [progress])

A wrapper for `http_request`, returns the HTTP request ID. The callbacks passed in are called at appropriate times. 

| Parameter | Type | Description |

|--|--|--|

| url | String | A valid URL |

| method | String | A valid HTTP Request Method |

| body | String/FormData | An HTTP request body, either a string or FormData |

| options | Struct\ | A struct setting various options in the request (further docs below) |

| callback | function | A function to be called if the HTTP request succeeds |

| error | function | (Optional) A function to be called if the HTTP request fails |

| progress | function | (Optional) A function to be called when the HTTP request is still in progress |



### options \

| Property | Type | Description |

|--|--|--|

| headers | Real (ds_map) | A ds_map index of headers to be sent with the HTTP reequest. If not provided, a map is created |

| keep_header_map | Boolean | Whether or not to keep the header map (useful if the headers are reused and don't need to change often) |

| get_file | Boolean | Whether or not to store the response in a `buffer`, which can be accessed in `options.buffer` in the progress callback, and `result` in the error and success callbacks) |

| filename | String | The file to output to when using `http_get_file` |

| keep_form_data | Boolean | Whether or not to clean up/destroy the FormData object included in a HTTP request. Ignored if no FormData object is passed in as body |

| buffer | Real (Buffer) | A buffer containing the HTTP response if the `get_file` flag is set |

| keep_buffer | Boolean | Whether or not to automatically delete the buffer generated by the `get_file` flag (default: `false`) |

| response_headers | Real (ds_map) | Response headers for the request, if available |



### callback(http_status, result, [options])

A function to be called when the HTTP request is successful

| Parameter | Type | Description |

|--|--|--|

| http_status | Real | HTTP status code |

| result | String | Real | HTTP response body |

| options | Struct\ | The `options` object passed into the `http` function (optional) | 



### error(http_status, result, [options])

A function to be called when the HTTP request is unsuccessful

| Parameter | Type | Description |

|--|--|--|

| http_status | Real | HTTP status code |

| result | String | Real | HTTP response body |

| options | Struct\ | The `options` object passed into the `http` function (optional) | 



### progress(content_length, size_downloaded, [options])

A function that is called when an HTTP request is still in progress (and has not completed or failed)

| Parameter | Type | Description |

|--|--|--|

| content_length | Real | Total response size |

| size_dwnloaded | String | Data downloaded |

| options | Struct\ | The `options` object passed into the `http` function (optional) | 



## FormData

A struct that implements FormData as best I can to the spec set out in [rfc2045](https://datatracker.ietf.org/doc/html/rfc2045). 



### add_file(name, file, options)

Adds a file field to the FormData object

| Parameter| Type | Description |

|--|--|--|

| name | String | Field name |

| file | String | Path to file to load into FormData |

| options | Struct\ | Options related to file |



### add_data(name, data)

Adds a data field to the FormData object

| Parameter | Type | Description |

|--|--|--|

| name | String | Field name |

| data | String | Field Data |



### form_body

Returns the `multipart/form-data` encoded body and the boundary, ready for use in the `HTTP` function

Returns: [Buffer, String]



### cleanup

Cleans up any buffers created and stored in the FormData object that were not flagged with `keep_buffer`, except the results of the `form_body` function



### options\

| Property | Type | Description |

|--|--|--|

| file_is_buffer | Boolean | Whether or not the File passed in to `add_file` is a Buffer instead of a file/path |

| keep_buffer | Boolean | When using `file_is_buffer`, this controls whether or not the buffer is kept after the FormData object runs its `cleanup()` function |

| filename | String | Filename to use for the uploaded file (in the form field). If blank, will use the filename in the `file` argument, or the string `"unknown"` if a buffer was specified |

| mimetype | String | The mimetype to mark the file as. This is sniffed from the filename if there's a [filetype registered with the IANA](https://www.iana.org/assignments/media-types/media-types.xhtml) in the `get_mime_from_extension()` function |



## Example Usage

### Basic GET request

```js

// Using the amazing yes/no API - https://yesno.wtf

http("https://yesno.wtf/api","GET","",{},function(status,result){

	result = json_parse(result);

	show_message(result.answer);

})

```

### Uploading a file (multipart/form-data)



```js

var form = new FormData();

form.add_file("file","codes.json");

form.add_data("foo","bar");

var headers = ds_map_create();

headers[? "X-App-Id"] = "ABC123"

http("https://enn3xyub5vujm.x.pipedream.net/", "POST", form, {headers:headers}, function(http_status,result){

	show_message(result);

},function(http_status,result){

	show_message("Error - " + result);

});

```



### Downloading a photo of a cat



```js

http("https://i.imgur.com/R42xZ1p.jpg","GET","",{get_file:true},

	function(status,result){

		buffer_save(result,"out.jpg");

		// We have a cat, maaaaan!

	}

);



```