HaloNet Map Download Protocol

From HaloNet.Net
Revision as of 22:54, 18 June 2019 by Krewat (talk | contribs)
Jump to: navigation, search

Protocol description

A standard protocol for downloading maps from HaloNet.Net, which HAC2 will move to, and other mods are free to use as well.


HAC2 or various client or server mods should operate as follows.

Example URL to use to download a map:

http://maps1.halonet.net/halonet/locator.php?map=zmpsierra_1

Map name is supplied as the variable "map". This is NOT case sensitive. The default download format is .zip - if you wish to download .7z, the URL should contain a "format" variable set to either 7z or zip. Example:

http://maps.halonet.net/halonet/locator.php?format=7z&map=zmpsierra_1

If the "format" variable is not supplied, "zip" is the default.

A "noredirect" variable with a value of "1" can be supplied indicating that redirects are not allowed. In this case, a 404 error will be returned if the map is not local to the map server.

Example: http://maps.halonet.net/halonet/locator.php?format=7z&noredirect=1&map=zmpsierra_1

Map names should be "urlencoded" - https://www.w3schools.com/tags/ref_urlencode.asp - An example for Windows is to use InternetCanonicalizeUrlA: https://docs.microsoft.com/en-us/windows/desktop/api/wininet/nf-wininet-internetcanonicalizeurla


Fault Tolerance

The mod should set the WinHTTP timeouts down to 10 or even 5 seconds so users don't face long waits for downloads. HaloNet's map servers will respond to the initial open quickly. The mod programmer can decide if the download speed is too slow, and switch to the next map server in the list if they wish.

If a connection fails to maps1.halonet.net, you should retry to maps2.halonet.net, maps3.halonet.net, etc, until the name no longer resolves. The name resolution is only done in WinHttpSendRequest, and the error returned is ERROR_WINHTTP_NAME_NOT_RESOLVED.

A WinHttp example downloader can be provided on request. I hope to make one available on github.com at some point.


Return codes

If the return code is 302, this is a "redirect". The URL returned in the Location header will point to the location to download the map in question. If this fails, continue on to the next map server and retry.

Any return code other than 200 (success) indicates a failure of that particular map server, and every effort should be made to try the next map server.


It is up to the modification programmer to decide when to stop trying. A user can be told map downlods are failing, and to press a certain key to stop trying, while the mod continues to try the list of map servers. Or, it can stop when the list of map servers is exhausted.

Again, the "list" of map servers is just this: maps1.halonet.net, maps2.halonet.net, maps3.halonet.net, etc, until the name no longer resolves. It is again up to the modification programmer to decide what to do at that point.