Difference between revisions of "HaloNet Map Download Protocol"
| Line 9: | Line 9: | ||
Example URL to use to download a Custom Edition map: | Example URL to use to download a Custom Edition map: | ||
| − | http://maps1.halonet.net/halonet/locator.php?map= | + | http://maps1.halonet.net/halonet/locator.php?map=zmm_battle_grounds |
Map name is supplied as the variable "map". This is NOT case sensitive. CE maps are downloaded by default. To specify a PC (Combat Evolved) map, use the "type" variable to specify "ce" or "pc". Alternatively, "halor" (PC) or "halom" can be used, as these are in the "product type" string most applications search for on startup. | Map name is supplied as the variable "map". This is NOT case sensitive. CE maps are downloaded by default. To specify a PC (Combat Evolved) map, use the "type" variable to specify "ce" or "pc". Alternatively, "halor" (PC) or "halom" can be used, as these are in the "product type" string most applications search for on startup. | ||
| Line 15: | Line 15: | ||
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: | 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://maps1.halonet.net/halonet/locator.php?format=7z&map= | + | http://maps1.halonet.net/halonet/locator.php?format=7z&map=zmm_battle_grounds |
If the "format" variable is not supplied, "zip" is the default. | If the "format" variable is not supplied, "zip" is the default. | ||
| Line 21: | Line 21: | ||
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. | 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://maps1.halonet.net/halonet/locator.php?format=7z&noredirect=1&map= | + | Example: http://maps1.halonet.net/halonet/locator.php?format=7z&noredirect=1&map=zmm_battle_grounds |
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 | 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 | ||
Revision as of 15:40, 22 June 2019
Protocol description
A standard protocol for downloading maps from HaloNet.Net, which HAC2 will move to, and other applications are free to use as well. "Application" describes a client or server-side modification, such as HAC2, HSE®, SAPP+LUA, Chimera, etc.
HAC2 and various client or server applications should operate as follows. Note that the default HTTP port is used, port 80.
Example URL to use to download a Custom Edition map:
http://maps1.halonet.net/halonet/locator.php?map=zmm_battle_grounds
Map name is supplied as the variable "map". This is NOT case sensitive. CE maps are downloaded by default. To specify a PC (Combat Evolved) map, use the "type" variable to specify "ce" or "pc". Alternatively, "halor" (PC) or "halom" can be used, as these are in the "product type" string most applications search for on startup.
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://maps1.halonet.net/halonet/locator.php?format=7z&map=zmm_battle_grounds
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://maps1.halonet.net/halonet/locator.php?format=7z&noredirect=1&map=zmm_battle_grounds
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
An example of a PC map download in 7z format:
http://maps1.halonet.net/halonet/locator.php?format=7z&type=pc&map=zmpsierra_1
Supported variables:
- map = specify the map name, preferably urlencoded
- format = download format, zip or 7z supported
- type = Game product type, ce or halom (Custom Edition), pc or halor (Combat Evolved)
- noredirect = 1 - Return 404 instead of 302 for a redirect.
Fault Tolerance
The application should set the WinHTTP timeouts down to 10 or even 5 seconds so users don't face long waits for downloads. This can be done using the WinHttpSetTimeouts function. HaloNet's map servers should respond to the initial open quickly. The application can decide if the download speed is too slow, and switch to the next map server in the list if desired.
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.
Multiple servers can be queried at the same time, or downloaded from at the same time. The fastest responder or first to download can be used. This may actually slow down downloads if a player's Internet connection is slow to begin with, so the application should provide a way to enable or disable that option.
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. This may be used to pull a map server out of the rotation, so every effort should be made to support this functionality.
Any return code other than 200 (success) or 302 (redirect) 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 application to decide when to stop trying. A user can be told map downloads are failing, and to press a certain key to stop trying, while the application 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 application to decide what to do at that point.
If a map server fails to respond, the application is free to ignore this map server until a certain timeout passes, or for the entire session. For example, if maps1.halonet.net does not respond, later map download attempts can ignore this map server until the player restarts the game, or after 10 minutes have passed.
