HTTP Dll - Help

HTTP Dll - Help
Made by Matrebatre

This DLL allows you to use the HTTP protocol without having to worry about handling sockets. The DLL will handle all socket connections for you. To use the DLL, you have to be somewhat familiar with the HTTP protocol. At the bottom of this help file is a small explanation.

You can use this DLL to:
- Download files from the internet, simultaneously
- Read files from the internet (for example the output of a PHP script), simultaneously
- Submit things to a website (using either the GET or POST method), simultaneously
- ...

This DLL uses WinSock 2.0, and it uses a thread to handle the socket connections. It allows you to use up to 16 HTTP objects at the same time. So what is the advantage of using this DLL instead of normal sockets (like 39dll)? Well, GM's string handling functions are incredibly slow. Also, most socket DLLs are meant for creating online games, not for text-based protocols. Because of GM's limited string handling functions, it is rather difficult to perform some simple tasks, like getting the value of the Content-Length header. Also, in this DLL the socket connections are handled by a thread, so you can start a download and keep it running while the game is doing other things. The socket connections are also handled much more efficient, making the downloads run faster (as fast as downloading it with a web browser).

If you are not using the extension, you should call httpdll_init once before using the other functions.

Global functions:

http_initerror() - Returns whether an error has occurred during the initialization process. If this returns true, it means the computer doesn't support WinSock 2.0 and the DLL won't work.

http_startthread() - Starts the thread that handles socket connections. You can either start it at game start and let it run all the time, or you can start it only when you need it. The thread uses almost no processing time (less than 0.01% on my PC), so it won't really slow the game down if you keep it running all the time. Returns whether the thread is running after the function call. If it returns false, the thread could not be started and you should show an error message. I don't think this will ever happen, but I added it anyway.

http_stopthread() - Stops the thread.

http_handlesockets() - Handles all socket connections. If you are not using the thread, you should run this function every step (if there are any socket connections active). Please note downloads will be faster when using the thread.

http_create() - Creates a HTTP structure and returns the id.

http_destroy(http_id) - Destroys a HTTP structure. It will also close any active connections.

http_set_method(http_id,method) - Sets the method to send in the HTTP request. If you just want to download something, use 'GET' (normal downloading).

http_set_filename(http_id,filename) - Sets the filename to send in the HTTP request. The filename starts with a '/'. For example, the filename of 'http://www.domain.com/folder/file.zip' is '/folder/file.zip'. You can use http_url_get_filename to extract the filename from a URL.

http_set_headers_in(http_id,headers) - Sets the headers to send in the HTTP request. This is not required.

http_set_message_body_in(http_id,message_body) - Sets the message body to send in the HTTP request. This is not required.

http_load_message_body_in(http_id,filename) - Loads the message body to send in the HTTP request from a file. This enables you to send binary data. This is not required.

http_connect(http_id,hostname,port) - Connects to the server indicated by hostname on port port (a string) and sends the HTTP request. You can use http_url_get_hostname and http_url_get_port to extract the hostname and port from a URL. Returns whether successful. If the function returns true, this does not actually mean the connection was successful. It means the hostname was valid, but the server could still be offline. If the server is offline, the connection status will be set to 3

http_disconnect(http_id) - Disconnects the HTTP structure if it is connected. This is not required, connections will be closed automatically when you destroy the HTTP structure.

http_update(http_id) - Updates the contents of the HTTP structure. It will interpret the data sent by the server and store it, so you can read the contents with the following functions. Returns whether the contents could be updated. It will only return false if the connection was already closed. If it returns false, the contents will not have changed and it makes no sense to read them again from the dll.

http_get_conn_status(http_id) - Returns the status of the connection with the server:
0 = 'not connected'
1 = 'connected' (can also mean 'trying to connect')
2 = 'connection closed correctly'
3 = 'connection closed incorrectly' (an error occurred or http_disconnect was used)
To check if the download was successful, you should check if the connection status is 2.

http_get_action(http_id) - Returns the action that is currently being performed:
0 = 'waiting for statuscode'
1 = 'receiving headers'
2 = 'receiving message body'
To check if the download was successful, you should check if the action is 2.

http_get_statuscode(http_id) - Returns the HTTP statuscode received (as a string), for example '200', '400', ...

http_get_statuscode_text(http_id) - Returns the textual representation of the HTTP statuscode received, for example 'OK', 'Not found', ... Do not depend on this value, it can be different for each server.

http_get_headers(http_id) - Returns all headers received so far. Header lines are terminated by a CRLF (chr(13)+chr(10)).

http_get_header_value(http_id,headername) - Returns the value of the header with name headername. The header name is case-insensitive. It also supports multi-line headers (lines starting with a space or tab belong to the previous header). Tab characters are replaced with spaces, and multiple spaces are replaced with one space. You can use this to get for example the value of the Content-Length header. Please note that the server is not required to send this header, some dynamically-generated pages don't send them.

http_get_message_body_length(http_id) - Returns the length of the message body received so far. You could compare this to the value of Content-Length to show a loading progress bar.

http_get_message_body(http_id) - Returns the message body received so far. Do not use this for binary files, GM strings are not binary-safe.

http_save_message_body(http_id,filename) - Saves the message body received so far to the file indicated by filename. This can be used to download and save files. This function is binary-safe.

http_url_get_hostname(url) - Returns the hostname part of a URL. For example, the hostname of 'http://www.domain.com/folder/file.zip' is 'www.domain.com'.

http_url_get_port(url) - Returns the port part of a URL (as a string). For example, the port of 'http://www.domain.com:4000/folder/file.zip' is '4000'. If no port is given, it returns '80' (the default port for HTTP).

http_url_get_filename(url) - Returns the filename part of a URL. For example, the filename of 'http://www.domain.com/folder/file.zip' is '/folder/file.zip'.

http_urlencode(string,keepspecialchars) - URL-encodes a string. Keepspecialchars indicates to keep special characters, like '/', '.', '?'. It will replace all non-alphanumberic characters (except '-' and '_') with %xx, where xx is the hexadecimal value of the character. For example, spaces will be replaced with '%20', because 0x20 = 32 = ord(' ').
URLs should always be URL-encoded with keepspecialchars=true before being passed to http_url_get_hostname or http_url_get_filename. Variable names and values sent with the GET and POST methods should always be URL-encoded with keepspecialchars=false.

http_urldecode(string) - Decodes a URL-encoded string. This function does the exact opposite of http_urlencode with keepspecialchars=false. It will also replace '+' with spaces. You could use this to decode data sent by a script you made in PHP if use the PHP function urlencode() on the data you are sending.

About the HTTP protocol:

The HTTP protocol is fairly easy to understand. Basically it works like this:
- the client sends a request to the server: a request consists of an initial line, headers, an empty line and sometimes a message body
- the server sends the answer to the client: the answer has the same format as the respons
- the server closes the connection
Note that this DLL doesn't support sending multiple requests in a single connection.

A simple client request could look like this:


GET /folder/index.htm HTTP/1.0

Host: www.domain.com

Connection: close

[empty line here]

This request will return the contents of http://www.domain.com/folder/index.htm Explanation:
GET = http method
/folder/index.htm = filename
HTTP/1.0 = http version that should be used in the response (this DLL only supports 1.0)
Host: www.domain.com = a header
Connection: close = a header
[empty line here] = indicates the end of the header lines

The answer of the server could look like this:


HTTP/1.1 200 OK

Content-Length: 19

[empty line here]

This is a web page.

Explanation:
HTTP/1.1 = highest http version the server supports (almost always 1.1)
200 = http statuscode
OK = textual representation of the http statuscode
Content-Length: 19 = a header
[empty line here] = indicates the end of the header lines
This is a web page. = the contents of the requested file

When using this DLL, you don't really have to worry about this format. The DLL will handle everything for you. You just have to set the method and file (and possibly headers and message body) with the functions above.

Method:
The method indicates what the server has to do. The most used methods are GET (to download the file) and POST (to submit information and download the file). If you use POST, you can send information you want to submit in the message body. You should use this format:


name1=value1&name2=value2&name3=value3

You should encode the name and value using http_urlencode(string,false). You also have to add these headers:


Content-Type: application/x-www-form-urlencoded

Content-Length: [length of message body]

There are also some other methods, like HEAD (only send the statuscode and headers), but they are rarely used.

Hostname and filename:
The hostname indicates the server to connect to, and the filename indicates the file to be downloaded. For example, if you want to download http://www.domain.com/folder/index.htm, then www.domain.com is the hostname /folder/index.htm is the filename. You can use http_url_get_hostname and http_url_get_filename to extract the correct hostname and filename from a url.

Headers (in):
Headers allow you to send some extra information to the server. The DLL will automatically send these two headers:


Host: www.domain.com

Connection: close

The host header is used to specify the hostname used. This is required if one server is hosting multiple (sub)domains. The Connection header specifies what should be done when the download is finished. The DLL will automatically set this to 'close', meaning the connection will be closed after the transfer. This allows you to see if the download is complete by checking the connection status (it should be 2). You can send additional headers if you want, but this is not required. Some sites (like whatismyip.org) will require a User-Agent (name of the client program) header, but most sites won't.

Message body:
Some methods (like POST) allow you to specify a message body, so you can submit extra information to the server.

Http statuscode:
This code is used to check whether the request was successful. Statuscode 200 means the request was successful, all the other statuscodes indicate some kind of error. The full list of statuscodes can be found here. The statuscode also has a textual representation, this can be used to make the error more human-readable. Do not depend on this though, as it is not always the same for all servers. Use the number instead.

Headers:
These headers indicate the properties of the file downloaded. The most important one is probably the Content-Length header. This header indicates the size of the file being sent.

Message body:
This is the actual content of the webpage. You can read this in a string or save it as a file. If you are downloading a binary file (like a ZIP file or an image file) you should save it, because GM's strings are not binary-safe. If you need more information, visit this site.

Examples:

The example file contains two example scripts: one for reading a webpage and one for downloading a webpage.

Good luck using this dll!