-- WinHTTP wrapper
-- WinHTTP is Unicode only
-- WinHTTP wrapper
-- WinHTTP is Unicode only
Following global functions are defined:
adds one or more HTTP request headers to the HTTP request handle.
Params:A HINTERNET handle returned by a call to the WinHttpOpenRequest function.
Headers to append to the request. Each header except the last must be
terminated by a carriage return/line feed (CR/LF).
integer value that contains the flags used to modify the semantics of this
function. Can be one or more of the following flags.
Value Meaning
WINHTTP_ADDREQ_FLAG_ADD Adds the header if it does not exist.
Used with WINHTTP_ADDREQ_FLAG_REPLACE.
WINHTTP_ADDREQ_FLAG_ADD_IF_NEW Adds the header only if it does not
already exist; otherwise, an error is
returned.
WINHTTP_ADDREQ_FLAG_COALESCE Merges headers of the same name.
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA Merges headers of the same
name using a comma. For example, adding
"Accept: text/*" followed by "Accept:
audio/*" with this flag results in a
single header "Accept: text/*, audio/
*". This causes the first header found
to be merged. The calling application
must to ensure a cohesive scheme with
respect to merged and separate headers.
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON Merges headers of the same
name using a semicolon.
WINHTTP_ADDREQ_FLAG_REPLACE Replaces or removes a header. If the
header value is empty and the header is
found, it is removed. If the value is
not empty, it is replaced.
The WinHttpAddRequestHeaders function adds one or more HTTP request headers
to the HTTP request handle.
Remarks
Headers are transferred across redirects. This can be a security issue.
To avoid having headers transferred when a redirect occurs, use the
WINHTTP_STATUS_CALLBACK callback to correct the specific headers when a
redirect occurs.
Even when WinHTTP is used in asynchronous mode (that is, when
WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function operates
synchronously. The return value indicates success or failure. To get
extended error information, call GetLastError.
The WinHttpAddRequestHeaders function appends additional free-format
headers to the HTTP request handle and is intended for use by
sophisticated clients that require detailed control over the exact
request sent to the HTTP server.
The name and value of request headers added with this function are
validated. Headers must be well formed. For more information about valid
HTTP headers, see RFC 2616. If an invalid header is used, this function
fails and GetLastError returns ERROR_INVALID_PARAMETER. The invalid
header is not added.
If you are sending a Date: request header, you can use the
WinHttpTimeFromSystemTime function to create structure for the header.
For basic WinHttpAddRequestHeaders, the application can pass in multiple
headers in a single buffer.
An application can also use WinHttpSendRequest to add additional headers
to the HTTP request handle before sending a request.
Returns TRUE if successful, or FALSE otherwise. For extended error
information, call GetLastError. Among the error codes returned are the
following.
Error Code Description
ERROR_WINHTTP_INCORRECT_HANDLE_STATE The requested operation cannot be
performed because the handle
supplied is not in the correct
state.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE The type of handle supplied is
incorrect for this operation.
ERROR_WINHTTP_INTERNAL_ERROR An internal error has occurred.
ERROR_NOT_ENOUGH_MEMORY Not enough memory was available to
complete the requested operation.
determines whether the current platform is supported
Description:The WinHttpCheckPlatform function determines whether the current
platform is supported by this version of Microsoft Windows HTTP Services
(WinHTTP).
Remarks
This function is useful if your application uses Microsoft Windows HTTP
Services (WinHTTP), but also supports platforms that WinHTTP does not.
Even when WinHTTP is used in asynchronous mode (that is, when
WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function operates
synchronously. The return value indicates success or failure. To get
extended error information, call GetLastError.
WinHTTP version 5.1 is an operating-system component of Windows 2000
with Service Pack 3 (SP3) and later (except Datacenter Server), Windows
XP with Service Pack 1 (SP1) and later, and Windows Server 2003. In
Windows Server 2003, WinHTTP is a system side-by-side assembly.
The return value is TRUE if the platform is supported by Microsoft
Windows HTTP Services (WinHTTP), or FALSE otherwise.
Closes a single HINTERNET handle.
Params:Valid HINTERNET handle to be closed.
Remarks
Even when WinHTTP is used in asynchronous mode (that is, when
WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function operates
synchronously. The return value indicates success or failure. To get
extended error information, call GetLastError.
If there is a status callback registered for the handle being closed and
the handle was created with a non-NULL context value, a
WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING callback is made. This is the
last callback made from the handle and indicates that the handle is
being destroyed.
An application can terminate an in-progress synchronous or asynchronous
request by closing the HINTERNET request handle using
WinHttpCloseHandle. For asynchronous requests, keep the following points
in mind:
- After an application calls WinHttpCloseHandle on a WinHTTP handle, it
cannot call any other WinHTTP API functions using that handle from any
thread.
- Even after a call to WinHttpCloseHandle returns, the application must
still be prepared to receive callbacks for the closed handle, because
WinHTTP can tear down the handle asynchronously. If the asynchronous
request was not able to complete successfully, the callback receives a
WINHTTP_CALLBACK_STATUS_REQUEST_ERROR notification.
- If an application associates a context data structure or object with
the handle, it should maintain that binding until the callback function
receives a WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING notification. This is
the last callback notification WinHTTP sends prior to deleting a handle
object from memory. In order to receive the
WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING callback notification, the
application must enable the WINHTTP_CALLBACK_FLAG_HANDLES flag in the
WinHttpSetStatusCallback call.
- Before calling WinHttpCloseHandle, an application can call
WinHttpSetStatusCallback to indicate that no more callbacks should be
made:
WinHttpSetStatusCallback( hRequest, NULL, 0, 0 );
It might seem that the context data structure could then be freed
immediately rather than having to wait for a
WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING notification, but this is not the
case: WinHTTP does not synchronize WinHttpSetStatusCallback with
callbacks originating in worker threads. As a result, a callback could
already be in progress from another thread, and the application could
receive a callback notification even after having NULLed-out the
callback function pointer and deleted the handle's context data
structure. Because of this potential race condition, be conservative in
freeing the context structure until after having received the
WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING notification.
An application should never call WinHttpCloseHandle on a synchronous
request. This can create a race condition. See HINTERNET Handles in
WinHTTP for more information.
Returns TRUE if the handle is successfully closed, or FALSE otherwise.
To get extended error information, call GetLastError. Among the error
codes returned are the following.
Error Codes Description
ERROR_WINHTTP_SHUTDOWN The WinHTTP function support is being shut
down or unloaded.
ERROR_WINHTTP_INTERNAL_ERROR An internal error has occurred.
ERROR_NOT_ENOUGH_MEMORY Not enough memory was available to complete
the requested operation. (Windows error
code)
Specifies the initial target server of an HTTP request and returns an
HINTERNET connection handle to an HTTP session for that initial target.
Valid HINTERNET WinHTTP session handle returned by a previous call to
WinHttpOpen.
Host name of an HTTP server. Alternately, the string can contain the IP address
of the site in ASCII, for example, 10.0.1.45. Note that WinHttp does not accept
international host names without converting them first to Punycode. For more
information, see Handling Internationalized Domain Names (IDNs).
TCP/IP port on the server to which a connection is made. This parameter can
be any valid TCP/IP port number, or one of the following values.
Value Meaning
INTERNET_DEFAULT_HTTP_PORT Uses the default port for HTTP servers (port
80).
INTERNET_DEFAULT_HTTPS_PORT Uses the default port for HTTPS servers (port
443). Selecting this port doesn't automatically
establish a secure connection. You must still
specify the use of secure transaction
semantics by using the WINHTTP_FLAG_SECURE flag
with WinHttpOpenRequest.
INTERNET_DEFAULT_PORT Uses port 80 for HTTP and port 443 for Secure
Hypertext Transfer Protocol (HTTPS).
Remarks
Even when WinHTTP is used in asynchronous mode (that is, when
WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function operates
synchronously. The return value indicates success or failure. To get
extended error information, call GetLastError.
After the calling application has finished using the HINTERNET handle
returned by WinHttpConnect, it must be closed using the
WinHttpCloseHandle function.
WinHttpConnect specifies the target HTTP server, however a response can
come from another server if the request was redirected. You can
determine the URL of the server sending the response by calling
WinHttpQueryOption with the WINHTTP_OPTION_URL flag.
Returns a valid connection handle to the HTTP session if the connection is
successful, or NULL otherwise. To retrieve extended error information,
call GetLastError. Among the error codes returned are the following:
Error Codes Description
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE The type of handle supplied is
incorrect for this operation.
ERROR_WINHTTP_INTERNAL_ERROR An internal error has occurred.
ERROR_WINHTTP_INVALID_URL The URL is invalid.
ERROR_WINHTTP_OPERATION_CANCELLED The operation was canceled, usually
because the handle on which the
request was operating was closed
before the operation completed.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME The URL scheme could not be
recognized, or is not supported.
ERROR_WINHTTP_SHUTDOWN The WinHTTP function support is being
shut down or unloaded.
ERROR_NOT_ENOUGH_MEMORY Not enough memory was available to
complete the requested operation.
(Windows error code)
Separates a URL into its component parts such as host name and path.
Params:Canonical URL to separate. WinHttpCrackUrl does not check this URL for
validity or correct format before attempting to crack it.
The flags that control the operation. This parameter can be one of the
following values.
Value Meaning
ICU_DECODE Converts characters that are "escape encoded" (%xx) to
their non-escaped form. This does not decode other
encodings, such as UTF-8. This feature can be used only
if the user provides buffers in the URL_COMPONENTS
structure to copy the components into.
ICU_ESCAPE Escapes certain characters to their escape sequences
(%xx). Characters to be escaped are non-ASCII characters
or those ASCII characters that must be escaped to be
represented in an HTTP request. This feature can be used
only if the user provides buffers in the URL_COMPONENTS
structure to copy the components into.
ICU_REJECT_USERPWD Rejects URLs as input that contains either a username,
or a password, or both. If the function fails because of
an invalid URL, subsequent calls to GetLastError will
return ERROR_WINHTTP_INVALID_URL.
Pointer to a URL_COMPONENTS structure that receives the URL components.
Remarks
Even when WinHTTP is used in asynchronous mode (that is, when
WINHTTP_FLAG_ASYNC has been set in WinHttpOpen), this function operates
synchronously. The return value indicates success or failure. To get extended
error information, call GetLastError.
The required components are indicated by members of the URL_COMPONENTS
structure. Each component has a pointer to the value and has a member that
stores the length of the stored value. If both the value and the length for a
component are equal to zero, that component is not returned. If the pointer
to the value of the component is not NULL and the value of its corresponding
length member is nonzero, the address of the first character of the
corresponding component in the pwszUrl string is stored in the pointer, and
the length of the component is stored in the length member.
If the pointer contains the address of the user-supplied buffer, the length
member must contain the size of the buffer. The WinHttpCrackUrl function
copies the component into the buffer, and the length member is set to the
length of the copied component, minus 1 for the trailing string terminator.
If a user-supplied buffer is not large enough, WinHttpCrackUrl returns FALSE,
and GetLastError returns ERROR_INSUFFICIENT_BUFFER.
For WinHttpCrackUrl to work properly, the size of the URL_COMPONENTS
structure must be stored in the dwStructSize member of that structure.
If the Internet protocol of the URL passed in for pwszUrl is not HTTP or
HTTPS, then WinHttpCrackUrl returns FALSE and GetLastError indicates
ERROR_WINHTTP_UNRECOGNIZED_SCHEME.
WinHttpCrackUrl does not check the validity or format of a URL before
attempting to crack it. As a result, if a string such as
""http://server?Bad=URL"" is passed in, the function returns incorrect
results.
Returns Pointer to a URL_COMPONENTS structure if the function succeeds, or
FALSE otherwise. To get extended error information, call GetLastError.
Among the error codes returned are the following.
Error Codes Description
ERROR_WINHTTP_INTERNAL_ERROR An internal error has occurred.
ERROR_WINHTTP_INVALID_URL The URL is invalid.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME The URL scheme could not be recognized,
or is not supported.
ERROR_NOT_ENOUGH_MEMORY Not enough memory was available to
complete the requested operation.
Creates a URL from component parts such as the host name and path.
Params:finds the URL for the Proxy Auto-Configuration (PAC) file.
Params:This function reports the URL of the PAC file, but it does not download the file.
retrieves the default WinHTTP proxy configuration from the registry.
Params:retrieves the Internet Explorer proxy configuration for the current user.
Params:retrieves the proxy data for the specified URL.
Params:initializes, for an application, the use of WinHTTP functions and returns a WinHTTP-session handle.
Params:creates an HTTP request handle.
Params:returns the authorization schemes that are supported by the server.
Params:returns the amount of data, in bytes, available to be read with WinHttpReadData.
Params:A valid HINTERNET handle returned by WinHttpOpenRequest.
number of bytes of data that are available to read immediately by a
subsequent call to WinHttpReadData.
If no data is available and the end of the file has not been reached, one of
two things happens:
* If the session is synchronous, the request waits until data becomes
available.
* If the session is asynchronous, the function returns TRUE, and when data
becomes available, calls the callback function with
WINHTTP_STATUS_CALLBACK_DATA_AVAILABLE and indicates the number of bytes
immediately available to read by calling WinHttpReadData.
retrieve HTTP headers
Params:Valid HINTERNET handle returned by WinHttpOpenRequest. Wait until
WinHttpSendRequest has completed before calling this function.
returns HTTP Status code
Params:Valid HINTERNET handle returned by WinHttpOpenRequest. Wait until
WinHttpSendRequest has completed before calling this function.
queries an Internet option on the specified handle.
Params:reads data from a handle opened by the WinHttpOpenRequest function.
Params:waits to receive the response to an HTTP request initiated by WinHttpSendRequest.
Params:sends the specified request to the HTTP server.
Params:Valid HINTERNET handle returned by WinHttpOpenRequest. Wait until
WinHttpSendRequest has completed before calling this function.
either a sequence or WINHTTP_NO_ADDITIONAL_HEADERS
either a sequence or WINHTTP_NO_REQUEST_DATA
bResults = WinHttpSendRequest(hRequest,
WINHTTP_NO_ADDITIONAL_HEADERS,
WINHTTP_NO_REQUEST_DATA,
0)
bResults = WinHttpSendRequest(hRequest,
"content-type:application/x-www-form-urlencoded",
credentials,
0)
passes the required authorization credentials to the server.
Params:sets the default WinHTTP proxy configuration in the registry.
Params:sets an Internet option.
Params:sets up a callback function that WinHTTP can call as progress is made during an operation.
Params:sets time-outs involved with HTTP transactions.
Params:formats a date and time according to the HTTP version 1.0 specification.
Params:takes an HTTP time/date string and converts it to a SYSTEMTIME sequence.
Params:HTTP time/date string
sequence of integers
{wYear, wMonth, wDayOfWeek, wDay, wHour, wMinute, wSecond, wMilliseconds}
wYear
The year. The valid values for this member are 1601 through 30827.
wMonth
The month. The valid values for this member are 1 through 12.
wDayOfWeek
The day of the week. This member can be one of the following values.
Value Meaning
0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday
wDay
The day of the month. The valid values for this member are 1 through 31.
wHour
The hour. The valid values for this member are 0 through 23.
wMinute
The minute. The valid values for this member are 0 through 59.
wSecond
The second. The valid values for this member are 0 through 59.
wMilliseconds
The millisecond. The valid values for this member are 0 through 999.
writes request data to an HTTP server
Params:Valid HINTERNET handle returned by WinHttpOpenRequest. Wait until
WinHttpSendRequest has completed before calling this function.
data to be sent to the server
Returns TRUE if successful, or FALSE otherwise.
extract cookies from sequence of headers
Params:sequence of headers
sequence of options {name, value}
raw : raw cookie line from header if 1 (true), only cookie name andvalue if 0 (false). defaults to 0.
option raw defaults to no (only cookie name and value returned)
only last header is considered in case of redirection
sequence
list of cookies found in last header
Headers = WinHttpQueryHeaders( hRequest )
if sequence(Buffer) then
cookies = WinHttpExtractCookies(Headers, {{"raw", 1}})
analyze_object(cookies, "cookies", {})
cookies = WinHttpExtractCookies(Headers, {})
analyze_object(cookies, "cookies", {{"output", f_debug}})
end if
extract CSRF token from HTML content
Params:HTML content
sequence
* CRSF token
Buffer = ""
dwSize = WinHttpQueryDataAvailable(hRequest)
while dwSize do
Buffer &= WinHttpReadData(hRequest, dwSize)
dwSize = WinHttpQueryDataAvailable(hRequest)
end while
token = WinHttpExtractCsrfToken(Buffer)