Sign In
Create Account
Last active: Dec 24 2015 02:21 AMHTTPRequest - A function for submitting http(s) requests to the web and handling the responses.
Version: 2.49 - Tested compatible with AHK v1.0.48.05 and AHK v1.1.00.00 (Unicode); Presumed compatible with later versions, ANSI, and x64.
Download HTTPRequest.ahk or Download HTTPRequest.zip
Overview: I wrote HTTPRequest specifically to service client-authenticated web APIs (like Amazon and eBay), which it does to my satisfaction. It can also upload data and download resources (e.g: HTML, images, etc...) from the internet, optionally saving them as a file on disk. The core of HTTPRequest is WinINet.dll, which comes with Internet Explorer.
The Basics: HTTPRequest has 4 parameters, the second and third are BYREF and used for both input and output. HTTPRequest returns either the number of bytes downloaded OR the length of the text downloaded, depending on how it treats the downloaded data.
; This is the order of HTTPRequest's parameters BytesDownloaded := HTTPRequest( URL, In_POST__Out_Data, In_Out_HEADERS, Options )[*:1h5kyocc]1). URL (required) - The URL of the internet resource you wish to access.
[*:1h5kyocc]2). In_POST__Out_Data (optional) - A variable. Before the function is called, this variable should hold any data you wish to upload. If you don't wish to upload data, make this variable blank (empty). A simple way to do this is to assign an empty string to it. After the function completes successfully, this variable holds the response data.
HTTPRequest does not convert uploaded text to utf-8 automatically. If you use unicode AHK, see the "charset" option below.
[*:1h5kyocc]3). In_Out_HEADERS (recommended) - A variable. Prior to calling the function, put a (`n) newline delimited list of custom request headers into this variable (or make it blank, if you don't need to supply any extra headers). After the function completes, this variable holds the HTTP response headers and/or messages about any errors the function encountered. Do not ignore this parameter, it often contains very useful debugging info.
[*:1h5kyocc]4). Options (optional) - A newline delimited list of keywords that modify how HTTPRequest works.
Headers: are a collection of information about the client/server, the request/response, and about the data being transferred. Even if parameter 3 is empty, HTTPRequest still submits request headers. There are a few request headers you should take special note of: [*:1h5kyocc]Content-Length: 12345 - HTTPRequest will add the "Content-Length" header to the request headers if it detects data to upload. If HTTPRequest can't determine the content length automatically (e.g: you are uploading non-text data), you must provide the "Content-Length" header with the total number of bytes you wish to upload. NOTE for UNICODE AHK: if you are uploading text, the number of bytes in text is twice the length of the text.
[*:1h5kyocc]Content-Type: application/x-www-form-urlencoded - If the "Content-Length" is greater than zero, HTTPRequest will add the "Content-Type" header unless you already provided it. HTTPRequest's default values for this header are "application/octet-stream" when uploading from a file and the file's extension is neither "txt" nor "xml"; "text/xml" when the string "<?xml" appears near the beginning of the data; or "application/x-www-form-urlencoded" in all other cases.
[*:1h5kyocc]Content-MD5: - Some web APIs require this header because they need to verify the integrity of the uploaded data. HTTPRequest can fill in the value automatically if you leave it blank (i.e: supply the header name and colon without the value like "Content-MD5:"). Also, if this appears in the response headers, HTTPRequest will add a "Computed-MD5" pseudo-header for your convenience.
[*:1h5kyocc]User-Agent: MyScriptName/1.0 (Language=AutoHotkey/1.0.48.05; Platform=WIN_XP) - HTTPRequest will add the "User-Agent" header to every request. By default, your script name, AHK version, and OS are used. If this is unacceptable to you, provide your own "User-Agent" header.
Options: modify how HTTPRequest behaves. Text in blue is only a syntax example. [*:1h5kyocc]AutoProxy - This option tells HTTPRequest to use Internet Exlporer's proxy configuration. If your Internet Explorer is not configured to use a proxy, this option has no effect.
[*:1h5kyocc]Binary - Normally, after downloading text, HTTPRequest will try to convert its codepage to the script's codepage, which is essential if you're using unicode AHK. The "binary" option tells HTTPRequest NOT to do the conversion (i.e: HTTPRequest will treat the downloaded data as raw binary data).
[*:1h5kyocc]Callback: Function_Name [, Third Parameter Value] - Tells HTTPRequest to call "Function_Name()" at regular intervals during the data transfer. "Function_Name()" must NOT require more than 3 parameters. When HTTPRequest calls the function, the first parameter's value ranges from -1 to +1, where values less than 0 indicate an upload in progress and values greater than 0 indicate a download. The second parameter's value is the number of bytes anticipated in the transfer (i.e: the value of the "Content-Length" header). The third parameter's value is whatever you put as "Third Parameter Value". The callback function may return the string "CANCEL" to tell HTTPRequest to cancel the transaction.
[*:1h5kyocc]Charset: utf-8 - Tells HTTPRequest to convert the text in "In_POST__Out_Data" from the script's codepage to the character set specified. HTTPRequest contains a lookup table with the supported charset names, which was copied from http://msdn.microsof...6(v=vs.85).aspx.
[*:1h5kyocc]Codepage: 65001 - The more 'technical' counterpart to the "charset" option, where the number on the right indicates the desired codepage number.
[*:1h5kyocc]+NO_COOKIES - Tells WinINet to NOT automatically handle cookies (by default, WinINet uses Internet Explorer's cookie pool). This is required if you want your script to manage cookies with HTTPRequest. If your request headers contain any "Cookie" headers, this option is applied automatically.
[*:1h5kyocc]+NO_AUTO_REDIRECT - Internet flags may be added or removed from a partiular request by putting a plus (+) or minus (-) sign in front of the flag's name, respectively (with or without the preceding "INTERNET_FLAG_"). Some flags are added automatically, depending on whether the connection uses SSL.
[*:1h5kyocc]+IGNORE_UNKNOWN_CA - Security flags may be added or removed from a partiular request by putting a plus (+) or minus (-) sign in front of the flag's name, respectively (use the full name with "SECURITY_FLAG_" in front when the flag name would otherwise be ambiguous).
[*:1h5kyocc]Method: POST - Tells HTTPRequest to use the indicated verb for the request. Typically, HTTPRequest uses "POST" if it is uploading data or "GET" otherwise. Use this option for web API functions that require a different verb. Supported verbs are GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE.
[*:1h5kyocc]Proxy: <!-- m -->http://www.exampleproxy.com:1234<!-- m --> - Tells HTTPRequest to use a proxy for the request.
To use a debugging proxy (like Fiddler), add this option to HTTPRequest:
Proxy: localhost:8888 (be sure to supply the correct port number).[*:1h5kyocc]ProxyBypass: <!-- m -->http://www.autohotkey.com<!-- m --> - Tells HTTPRequest NOT to use a proxy to access [www.autohotkey.com]. This has no effect unless HTTPRequest has been told to use a proxy via the "proxy" option.
[*:1h5kyocc]Resume: C:\My Partially Downloaded File.jpg - Tells HTTPRequest to continue downloading the specified file. It is up to you to make sure that the URL points to the same resource as the one used to download the file in the first place. When the download succeeds, "In_POST__Out_Data" is made blank.
[*:1h5kyocc]SaveAs: C:\Some File.htm - Tells HTTPRequest to save the data downloaded to your hard disk. This option simulates UrlDownloadToFile. When the download succeeds, "In_POST__Out_Data" is made blank. You may use FileRead to read the data into memory later.
[*:1h5kyocc]Upload: C:\My Awesome Pic.png - Tells HTTPRequest to use "C:\My Awesome Pic.png" as the source of data to upload. Please consult your webservice's documentation for any other conditions for uploading data. When using this option, I highly recommend supplying the appropriate "Content-Type" header.
Finally, this is a work in progress and features may be added/removed. Old versions will not remain available and I don't keep a change log. If you have questions, comments, bug reports, or requests for features, post them in this thread.
Special thanks to everyone who helped spot bugs and suggest new features. Extra special thanks to derRaphael, whose work on httpQuery inspired me to start this project.
Back to top
. Also, HTTPS support is awesome, couldn't get it to work with any other methods.
![[img]](http://i.imgur.com/498Rq.jpg){kind=link}