README
¶
winhttp
winhttp is a library used to interact with the Windows winhttp API.
It is designed take in a http.Request and return a http.Response from the go http standard library.
This library returns a custom Client that mimics the http.Client so that it can be a drop in replacement for the http.Client.
This package's custom client also takes an http.Transport structure in the Transport field to configure how the winhttp client is used.
Logging
This package uses the log/slog package for logging.
To retrieve the log output, create a new logger and call the slog.SetDefault() function.
All logging calls in this package are only for the DEBUG logging level which are not output by default.
Example
There is an example implementation in the example directory. Run the example code with:
PS C:\> go run .\examples\main.go
{"time":"2024-02-04T10:00:19.6010954-08:00","level":"INFO","msg":"building the HTTP request"}
{"time":"2024-02-04T10:00:19.60164-08:00","level":"INFO","msg":"building the HTTP client"}
{"time":"2024-02-04T10:00:19.60164-08:00","level":"INFO","msg":"sending the HTTP request","method":"GET","url":"https://httpbin.org/get"}
{"time":"2024-02-04T10:00:19.7671138-08:00","level":"INFO","msg":"recieved HTTP response","response":{"Status":"200 OK","StatusCode":200,"Proto":"HTTP/1.1","ProtoMajor":1,"ProtoMinor":1,"Header":{"Access-Control-Allow-Credentials":["true"],"Access-Control-Allow-Origin":["*"],"Connection":["keep-alive"],"Content-Length":["364"],"Content-Type":["application/json"],"Date":["Sun, 04 Feb 2024 18:00:19 GMT"],"Server":["gunicorn/19.9.0"]},"Body":{"Reader":{}},"ContentLength":364,"TransferEncoding":null,"Close":false,"Uncompressed":false,"Trailer":null,"Request":null,"TLS":null}}
{"time":"2024-02-04T10:00:19.7683439-08:00","level":"INFO","msg":"received HTTP payload data","data length":364}
{"time":"2024-02-04T10:00:19.7683439-08:00","level":"INFO","msg":"program finished running succesfully"}
The program's command line flags are:
-data string
data to send with the request
-debug
enable debug output
-method string
the HTTP METHOD for the request (default "GET")
-trace
enable SourceKey for debug output
-url string
the full URL for the request (default "https://httpbin.org/get")
Documentation
¶
Overview ¶
Package winhttp provides an HTTP client using the Windows WinHttp API
Package winhttp provides an HTTP client using the Windows WinHttp API ¶
Package winhttp provides an HTTP client using the Windows WinHttp API
Index ¶
- Constants
- func WinHttpAddRequestHeaders(hRequest windows.Handle, headers string, modifiers uint32) error
- func WinHttpCloseHandle(hInternet windows.Handle)
- func WinHttpConnect(hSession windows.Handle, serverName string, serverPort uint32) (windows.Handle, error)
- func WinHttpOpen(userAgent string, accessType int, proxy string, proxyBypass string, ...) (windows.Handle, error)
- func WinHttpOpenRequest(hConnect windows.Handle, method string, path string, version string, ...) (windows.Handle, error)
- func WinHttpQueryDataAvailable(hRequest windows.Handle) (uint32, error)
- func WinHttpQueryHeaders(hRequest windows.Handle, infoLevel uint32, header string, index uint32) ([]byte, error)
- func WinHttpReadData(hRequest windows.Handle, size uint32) ([]byte, error)
- func WinHttpReceiveResponse(hRequest windows.Handle) error
- func WinHttpSendRequest(hRequest windows.Handle, headers string, headersLength uint32, ...) error
- func WinHttpSetOption(hInternet windows.Handle, option uint32, buffer []byte) error
- type Client
Constants ¶
const ( // WinHTTP!WinHttpOpen dwAccessType // https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpopen WINHTTP_ACCESS_TYPE_DEFAULT_PROXY = 0 WINHTTP_ACCESS_TYPE_NO_PROXY = 1 WINHTTP_ACCESS_TYPE_NAMED_PROXY = 3 WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY = 4 // WinHTTP pszProxyW WINHTTP_NO_PROXY_NAME = 0 // WinHTTP pszProxyBypassW WINHTTP_NO_PROXY_BYPASS = 0 // WinHTTP dwFlags WINHTTP_FLAG_NONE = 0x00000000 WINHTTP_FLAG_ASYNC = 0x10000000 WINHTTP_FLAG_SECURE_DEFAULTS = 0x30000000 WINHTTP_FLAG_SECURE = 0x00800000 WINHTTP_FLAG_ESCAPE_PERCENT = 0x00000004 WINHTTP_FLAG_NULL_CODEPAGE = 0x00000008 WINHTTP_FLAG_ESCAPE_DISABLE = 0x00000040 WINHTTP_FLAG_ESCAPE_DISABLE_QUERY = 0x00000080 WINHTTP_FLAG_BYPASS_PROXY_CACHE = 0x00000100 WINHTTP_FLAG_REFRESH = WINHTTP_FLAG_BYPASS_PROXY_CACHE WINHTTP_FLAG_AUTOMATIC_CHUNKING = 0x00000200 // INTERNET_PORT https://learn.microsoft.com/en-us/windows/win32/winhttp/internet-port INTERNET_DEFAULT_PORT = 0 INTERNET_DEFAULT_HTTP_PORT = 80 INTERNET_DEFAULT_HTTPS_PORT = 443 WINHTTP_NO_ADDITIONAL_HEADERS = "" // HTTP Query Flags WINHTTP_QUERY_MIME_VERSION = 0 WINHTTP_QUERY_CONTENT_TYPE = 1 WINHTTP_QUERY_CONTENT_TRANSFER_ENCODING = 2 WINHTTP_QUERY_CONTENT_ID = 3 WINHTTP_QUERY_CONTENT_DESCRIPTION = 4 WINHTTP_QUERY_CONTENT_LENGTH = 5 WINHTTP_QUERY_CONTENT_LANGUAGE = 6 WINHTTP_QUERY_ALLOW = 7 WINHTTP_QUERY_PUBLIC = 8 WINHTTP_QUERY_DATE = 9 WINHTTP_QUERY_EXPIRES = 10 WINHTTP_QUERY_LAST_MODIFIED = 11 WINHTTP_QUERY_MESSAGE_ID = 12 WINHTTP_QUERY_URI = 13 WINHTTP_QUERY_DERIVED_FROM = 14 WINHTTP_QUERY_COST = 15 WINHTTP_QUERY_LINK = 16 WINHTTP_QUERY_PRAGMA = 17 WINHTTP_QUERY_VERSION = 18 WINHTTP_QUERY_STATUS_CODE = 19 WINHTTP_QUERY_STATUS_TEXT = 20 WINHTTP_QUERY_RAW_HEADERS = 21 WINHTTP_QUERY_RAW_HEADERS_CRLF = 22 WINHTTP_QUERY_CONNECTION = 23 WINHTTP_QUERY_ACCEPT = 24 WINHTTP_QUERY_ACCEPT_CHARSET = 25 WINHTTP_QUERY_ACCEPT_ENCODING = 26 WINHTTP_QUERY_ACCEPT_LANGUAGE = 27 WINHTTP_QUERY_AUTHORIZATION = 28 WINHTTP_QUERY_CONTENT_ENCODING = 29 WINHTTP_QUERY_FORWARDED = 30 WINHTTP_QUERY_FROM = 31 WINHTTP_QUERY_IF_MODIFIED_SINCE = 32 WINHTTP_QUERY_LOCATION = 33 WINHTTP_QUERY_ORIG_URI = 34 WINHTTP_QUERY_REFERER = 35 WINHTTP_QUERY_RETRY_AFTER = 36 WINHTTP_QUERY_SERVER = 37 WINHTTP_QUERY_TITLE = 38 WINHTTP_QUERY_USER_AGENT = 39 WINHTTP_QUERY_WWW_AUTHENTICATE = 40 WINHTTP_QUERY_PROXY_AUTHENTICATE = 41 WINHTTP_QUERY_ACCEPT_RANGES = 42 WINHTTP_QUERY_SET_COOKIE = 43 WINHTTP_QUERY_COOKIE = 44 WINHTTP_QUERY_REQUEST_METHOD = 45 WINHTTP_QUERY_REFRESH = 46 WINHTTP_QUERY_CONTENT_DISPOSITION = 47 WINHTTP_QUERY_AGE = 48 WINHTTP_QUERY_CACHE_CONTROL = 49 WINHTTP_QUERY_CONTENT_BASE = 50 WINHTTP_QUERY_CONTENT_LOCATION = 51 WINHTTP_QUERY_CONTENT_MD5 = 52 WINHTTP_QUERY_CONTENT_RANGE = 53 WINHTTP_QUERY_ETAG = 54 WINHTTP_QUERY_HOST = 55 WINHTTP_QUERY_IF_MATCH = 56 WINHTTP_QUERY_IF_NONE_MATCH = 57 WINHTTP_QUERY_IF_RANGE = 58 WINHTTP_QUERY_IF_UNMODIFIED_SINCE = 59 WINHTTP_QUERY_MAX_FORWARDS = 60 WINHTTP_QUERY_PROXY_AUTHORIZATION = 61 WINHTTP_QUERY_RANGE = 62 WINHTTP_QUERY_TRANSFER_ENCODING = 63 WINHTTP_QUERY_UPGRADE = 64 WINHTTP_QUERY_VARY = 65 WINHTTP_QUERY_VIA = 66 WINHTTP_QUERY_WARNING = 67 WINHTTP_QUERY_EXPECT = 68 WINHTTP_QUERY_PROXY_CONNECTION = 69 WINHTTP_QUERY_UNLESS_MODIFIED_SINCE = 70 WINHTTP_QUERY_PROXY_SUPPORT = 75 WINHTTP_QUERY_AUTHENTICATION_INFO = 76 WINHTTP_QUERY_PASSPORT_URLS = 77 WINHTTP_QUERY_PASSPORT_CONFIG = 78 WINHTTP_QUERY_MAX = 78 WINHTTP_QUERY_CUSTOM = 65535 WINHTTP_QUERY_FLAG_REQUEST_HEADERS = 0x80000000 WINHTTP_QUERY_FLAG_SYSTEMTIME = 0x40000000 WINHTTP_QUERY_FLAG_NUMBER = 0x20000000 WINHTTP_NO_OUTPUT_BUFFER = 0 WINHTTP_NO_REFERER = "" WINHTTP_DEFAULT_ACCEPT_TYPES = "" WINHTTP_NO_REQUEST_DATA = 0 WINHTTP_HEADER_NAME_BY_INDEX = "" WINHTTP_NO_HEADER_INDEX = 0 // flags for WinHttp{Set/Query}Options WINHTTP_FIRST_OPTION = WINHTTP_OPTION_CALLBACK WINHTTP_OPTION_CALLBACK = 1 WINHTTP_OPTION_RESOLVE_TIMEOUT = 2 WINHTTP_OPTION_CONNECT_TIMEOUT = 3 WINHTTP_OPTION_CONNECT_RETRIES = 4 WINHTTP_OPTION_SEND_TIMEOUT = 5 WINHTTP_OPTION_RECEIVE_TIMEOUT = 6 WINHTTP_OPTION_RECEIVE_RESPONSE_TIMEOUT = 7 WINHTTP_OPTION_HANDLE_TYPE = 9 WINHTTP_OPTION_READ_BUFFER_SIZE = 12 WINHTTP_OPTION_WRITE_BUFFER_SIZE = 13 WINHTTP_OPTION_PARENT_HANDLE = 21 WINHTTP_OPTION_EXTENDED_ERROR = 24 WINHTTP_OPTION_SECURITY_FLAGS = 31 WINHTTP_OPTION_SECURITY_CERTIFICATE_STRUCT = 32 WINHTTP_OPTION_URL = 34 WINHTTP_OPTION_SECURITY_KEY_BITNESS = 36 WINHTTP_OPTION_PROXY = 38 WINHTTP_OPTION_PROXY_RESULT_ENTRY = 39 WINHTTP_OPTION_USER_AGENT = 41 WINHTTP_OPTION_CONTEXT_VALUE = 45 WINHTTP_OPTION_CLIENT_CERT_CONTEXT = 47 WINHTTP_OPTION_REQUEST_PRIORITY = 58 WINHTTP_OPTION_HTTP_VERSION = 59 WINHTTP_OPTION_DISABLE_FEATURE = 63 WINHTTP_OPTION_CODEPAGE = 68 WINHTTP_OPTION_MAX_CONNS_PER_SERVER = 73 WINHTTP_OPTION_MAX_CONNS_PER_1_0_SERVER = 74 WINHTTP_OPTION_AUTOLOGON_POLICY = 77 WINHTTP_OPTION_SERVER_CERT_CONTEXT = 78 WINHTTP_OPTION_ENABLE_FEATURE = 79 WINHTTP_OPTION_WORKER_THREAD_COUNT = 80 WINHTTP_OPTION_PASSPORT_COBRANDING_TEXT = 81 WINHTTP_OPTION_PASSPORT_COBRANDING_URL = 82 WINHTTP_OPTION_CONFIGURE_PASSPORT_AUTH = 83 WINHTTP_OPTION_SECURE_PROTOCOLS = 84 WINHTTP_OPTION_ENABLETRACING = 85 WINHTTP_OPTION_PASSPORT_SIGN_OUT = 86 WINHTTP_OPTION_PASSPORT_RETURN_URL = 87 WINHTTP_OPTION_REDIRECT_POLICY = 88 WINHTTP_OPTION_MAX_HTTP_AUTOMATIC_REDIRECTS = 89 WINHTTP_OPTION_MAX_HTTP_STATUS_CONTINUE = 90 WINHTTP_OPTION_MAX_RESPONSE_HEADER_SIZE = 91 WINHTTP_OPTION_MAX_RESPONSE_DRAIN_SIZE = 92 WINHTTP_OPTION_CONNECTION_INFO = 93 WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST = 94 WINHTTP_OPTION_SPN = 96 WINHTTP_OPTION_GLOBAL_PROXY_CREDS = 97 WINHTTP_OPTION_GLOBAL_SERVER_CREDS = 98 WINHTTP_OPTION_UNLOAD_NOTIFY_EVENT = 99 WINHTTP_OPTION_REJECT_USERPWD_IN_URL = 100 WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS = 101 WINHTTP_OPTION_RECEIVE_PROXY_CONNECT_RESPONSE = 103 WINHTTP_OPTION_IS_PROXY_CONNECT_RESPONSE = 104 WINHTTP_OPTION_SERVER_SPN_USED = 106 WINHTTP_OPTION_PROXY_SPN_USED = 107 WINHTTP_OPTION_SERVER_CBT = 108 WINHTTP_OPTION_UNSAFE_HEADER_PARSING = 110 WINHTTP_OPTION_ASSURED_NON_BLOCKING_CALLBACKS = 111 WINHTTP_OPTION_UPGRADE_TO_WEB_SOCKET = 114 WINHTTP_OPTION_WEB_SOCKET_CLOSE_TIMEOUT = 115 WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL = 116 WINHTTP_OPTION_DECOMPRESSION = 118 WINHTTP_OPTION_WEB_SOCKET_RECEIVE_BUFFER_SIZE = 122 WINHTTP_OPTION_WEB_SOCKET_SEND_BUFFER_SIZE = 123 WINHTTP_OPTION_TCP_PRIORITY_HINT = 128 WINHTTP_OPTION_CONNECTION_FILTER = 131 WINHTTP_OPTION_ENABLE_HTTP_PROTOCOL = 133 WINHTTP_OPTION_HTTP_PROTOCOL_USED = 134 WINHTTP_OPTION_KDC_PROXY_SETTINGS = 136 WINHTTP_OPTION_ENCODE_EXTRA = 138 WINHTTP_OPTION_DISABLE_STREAM_QUEUE = 139 WINHTTP_OPTION_IPV6_FAST_FALLBACK = 140 WINHTTP_OPTION_CONNECTION_STATS_V0 = 141 WINHTTP_OPTION_REQUEST_TIMES = 142 WINHTTP_OPTION_EXPIRE_CONNECTION = 143 WINHTTP_OPTION_DISABLE_SECURE_PROTOCOL_FALLBACK = 144 WINHTTP_OPTION_HTTP_PROTOCOL_REQUIRED = 145 WINHTTP_OPTION_REQUEST_STATS = 146 WINHTTP_OPTION_SERVER_CERT_CHAIN_CONTEXT = 147 WINHTTP_LAST_OPTION = WINHTTP_OPTION_SERVER_CERT_CHAIN_CONTEXT WINHTTP_OPTION_USERNAME = 0x1000 WINHTTP_OPTION_PASSWORD = 0x1001 WINHTTP_OPTION_PROXY_USERNAME = 0x1002 WINHTTP_OPTION_PROXY_PASSWORD = 0x1003 SECURITY_FLAG_IGNORE_UNKNOWN_CA = 0x00000100 SECURITY_FLAG_IGNORE_CERT_DATE_INVALID = 0x00002000 SECURITY_FLAG_IGNORE_CERT_CN_INVALID = 0x00001000 SECURITY_FLAG_IGNORE_CERT_WRONG_USAGE = 0x00000200 SECURITY_FLAG_SECURE = 0x00000001 SECURITY_FLAG_STRENGTH_WEAK = 0x10000000 SECURITY_FLAG_STRENGTH_MEDIUM = 0x40000000 SECURITY_FLAG_STRENGTH_STRONG = 0x20000000 WINHTTP_PROTOCOL_FLAG_HTTP1 = 0x0 WINHTTP_PROTOCOL_FLAG_HTTP2 = 0x1 WINHTTP_PROTOCOL_FLAG_HTTP3 = 0x2 WINHTTP_FLAG_SECURE_PROTOCOL_SSL2 = 0x00000008 WINHTTP_FLAG_SECURE_PROTOCOL_SSL3 = 0x00000020 WINHTTP_FLAG_SECURE_PROTOCOL_TLS1 = 0x00000080 WINHTTP_FLAG_SECURE_PROTOCOL_TLS1_1 = 0x00000200 WINHTTP_FLAG_SECURE_PROTOCOL_TLS1_2 = 0x00000800 WINHTTP_FLAG_SECURE_PROTOCOL_TLS1_3 = 0x00002000 WINHTTP_FLAG_SECURE_PROTOCOL_ALL = WINHTTP_FLAG_SECURE_PROTOCOL_SSL2 | WINHTTP_FLAG_SECURE_PROTOCOL_SSL3 | WINHTTP_FLAG_SECURE_PROTOCOL_TLS1 WINHTTP_ADDREQ_FLAG_ADD_IF_NEW = 0x10000000 WINHTTP_ADDREQ_FLAG_ADD = 0x20000000 WINHTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA = 0x40000000 WINHTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON = 0x01000000 WINHTTP_ADDREQ_FLAG_COALESCE = WINHTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA WINHTTP_ADDREQ_FLAG_REPLACE = 0x80000000 )
Variables ¶
This section is empty.
Functions ¶
func WinHttpAddRequestHeaders ¶
WinHttpAddRequestHeaders adds one or more HTTP request headers to the HTTP request handle.
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpaddrequestheaders
hRequest is a valid HINTERNET request handle returned by WinHttpOpenRequest.
headers a string that contains the headers to add to the request. Each header except the last must be terminated by a carriage return/line feed (CR/LF).
modifiers the flags used to modify the semantics of this function. Can be one or more of the following flags: 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.
func WinHttpCloseHandle ¶
WinHttpCloseHandle closes a single HINTERNET handle
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpclosehandle
hInternet is a valid HINTERNET handle (see HINTERNET Handles in WinHTTP) to be closed. https://learn.microsoft.com/en-us/windows/win32/winhttp/hinternet-handles-in-winhttp
func WinHttpConnect ¶
func WinHttpConnect(hSession windows.Handle, serverName string, serverPort uint32) (windows.Handle, error)
WinHttpConnect specifies the initial target server of an HTTP request and returns an HINTERNET connection handle to an HTTP session for that initial target.
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpconnect
hSession is a valid HINTERNET WinHTTP session handle returned by a previous call to WinHttpOpen.
serverName is a string that contains the 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
serverPort is an unsigned integer that specifies the 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: INTERNET_DEFAULT_HTTP_PORT - INTERNET_DEFAULT_HTTP_PORT INTERNET_DEFAULT_HTTPS_PORT - Uses the default port for HTTPS servers (port 443). Selecting this port does not 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).
func WinHttpOpen ¶
func WinHttpOpen(userAgent string, accessType int, proxy string, proxyBypass string, flags uint32) (windows.Handle, error)
WinHttpOpen initializes, for an application, the use of WinHTTP functions and returns a WinHTTP-session handle.
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpopen
userAgent is a string that contains the name of the application or entity calling the WinHTTP functions. This name is used as the user agent in the HTTP protocol.
accessType is the type of access required. This can be one of the following values:
WINHTTP_ACCESS_TYPE_NO_PROXY - Resolves all host names directly without a proxy WINHTTP_ACCESS_TYPE_DEFAULT_PROXY - Important Use of this option is deprecated on Windows 8.1 and newer. Use WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY instead. WINHTTP_ACCESS_TYPE_NAMED_PROXY - Passes requests to the proxy unless a proxy bypass list is supplied and the name to be resolved bypasses the proxy. In this case, this function uses the values passed for pwszProxyName and pwszProxyBypass. WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY - Uses system and per-user proxy settings (including the Internet Explorer proxy configuration) to determine which proxy/proxies to use. Automatically attempts to handle failover between multiple proxies, different proxy configurations per interface, and authentication. Supported in Windows 8.1 and newer.
proxy is a string variable that contains the name of the proxy server to use when proxy access is specified by setting
dwAccessType to WINHTTP_ACCESS_TYPE_NAMED_PROXY. The WinHTTP functions recognize only CERN type proxies for HTTP. If dwAccessType is not set to WINHTTP_ACCESS_TYPE_NAMED_PROXY, this parameter must be set to WINHTTP_NO_PROXY_NAME.
proxyBypass is a string variable that contains an optional semicolon delimited list of host names or IP addresses, or both,
that should not be routed through the proxy when dwAccessType is set to WINHTTP_ACCESS_TYPE_NAMED_PROXY. The list can contain wildcard characters. Do not use an empty string, because the WinHttpOpen function uses it as the proxy bypass list. If this parameter specifies the "<local>" macro in the list as the only entry, this function bypasses any host name that does not contain a period. If dwAccessType is not set to WINHTTP_ACCESS_TYPE_NAMED_PROXY, this parameter must be set to WINHTTP_NO_PROXY_BYPASS.
flags contains the flags that indicate various options affecting the behavior of this function.
This parameter can have the following value: WINHTTP_FLAG_ASYNC - Use the WinHTTP functions asynchronously. By default, all WinHTTP functions that use the returned HINTERNET handle are performed synchronously. When this flag is set, the caller needs to specify a callback function through WinHttpSetStatusCallback. WINHTTP_FLAG_SECURE_DEFAULTS - When this flag is set, WinHttp will require use of TLS 1.2 or newer. If the caller attempts to enable older TLS versions by setting WINHTTP_OPTION_SECURE_PROTOCOLS, it will fail with ERROR_ACCESS_DENIED. Additionally, TLS fallback will be disabled. Note that setting this flag also sets flag WINHTTP_FLAG_ASYNC.
func WinHttpOpenRequest ¶
func WinHttpOpenRequest(hConnect windows.Handle, method string, path string, version string, referrer string, accessTypes []string, flags uint32) (windows.Handle, error)
WinHttpOpenRequest creates an HTTP request handle
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpopenrequest
hConnect is a connection handle to an HTTP session returned by WinHttpConnect
method is a string that contains the HTTP verb to use in the request. If this parameter is empty, the function uses GET as the HTTP verb
path is a string that contains the name of the target resource of the specified HTTP verb. This is generally a file name, an executable module, or a search specifier.
version is a string that contains the HTTP version. If this parameter is empty, the function uses HTTP/1.1.
referrer a string that specifies the URL of the document from which the URL in the request pwszObjectName was obtained.
If this parameter is set to WINHTTP_NO_REFERER, no referring document is specified
acceptTypes an array of strings that specifies media types accepted by the client.
If this parameter is set to WINHTTP_DEFAULT_ACCEPT_TYPES, no types are accepted by the client. Typically, servers handle a lack of accepted types as indication that the client accepts only documents of type "text/*"; that is, only text documents—no pictures or other binary files. For a list of valid media types, see Media Types defined by IANA at http://www.iana.org/assignments/media-types/
flags contains the Internet flag values. This can be one or more of the following values:
WINHTTP_FLAG_BYPASS_PROXY_CACHE - This flag provides the same behavior as WINHTTP_FLAG_REFRESH. WINHTTP_FLAG_ESCAPE_DISABLE - Unsafe characters in the URL passed in for pwszObjectName are not converted to escape sequences. WINHTTP_FLAG_ESCAPE_DISABLE_QUERY - Unsafe characters in the query component of the URL passed in for pwszObjectName are not converted to escape sequences. WINHTTP_FLAG_ESCAPE_PERCENT - The string passed in for pwszObjectName is converted from an LPCWSTR to an LPSTR. All unsafe characters are converted to an escape sequence including the percent symbol. By default, all unsafe characters except the percent symbol are converted to an escape sequence. WINHTTP_FLAG_NULL_CODEPAGE - The string passed in for pwszObjectName is assumed to consist of valid ANSI characters represented by WCHAR. No check are done for unsafe characters. Windows 7: This option is obsolete. WINHTTP_FLAG_REFRESH - Indicates that the request should be forwarded to the originating server rather than sending a cached version of a resource from a proxy server. When this flag is used, a "Pragma: no-cache" header is added to the request handle. When creating an HTTP/1.1 request header, a "Cache-Control: no-cache" is also added. WINHTTP_FLAG_SECURE - Uses secure transaction semantics. This translates to using Secure Sockets Layer (SSL)/Transport Layer Security (TLS).
func WinHttpQueryDataAvailable ¶
WinHttpQueryDataAvailable returns the amount of data, in bytes, available to be read with WinHttpReadData.
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpquerydataavailable
hRequest a valid HINTERNET handle returned by WinHttpOpenRequest. WinHttpReceiveResponse must have been called for this handle and have completed before WinHttpQueryDataAvailable is called.
func WinHttpQueryHeaders ¶
func WinHttpQueryHeaders(hRequest windows.Handle, infoLevel uint32, header string, index uint32) ([]byte, error)
WinHttpQueryHeaders retrieves header information associated with an HTTP request.
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpqueryheaders
hRequest is an HINTERNET request handle returned by WinHttpOpenRequest.
WinHttpReceiveResponse must have been called for this handle and have completed before WinHttpQueryHeaders is called.
infoLevel specifies a combination of attribute and modifier flags listed on the Query Info Flags page. These attribute and modifier flags indicate that the information is being requested and how it is to be formatted. https://learn.microsoft.com/en-us/windows/win32/winhttp/query-info-flags
header a string that contains the header name. If the flag in dwInfoLevel is not WINHTTP_QUERY_CUSTOM, set this parameter to WINHTTP_HEADER_NAME_BY_INDEX.
index used to enumerate multiple headers with the same name. When calling the function, this parameter is the index of the specified header to return. When the function returns, this parameter is the index of the next header. If the next index cannot be found, ERROR_WINHTTP_HEADER_NOT_FOUND is returned. Set this parameter to WINHTTP_NO_HEADER_INDEX to specify that only the first occurrence of a header should be returned.
func WinHttpReadData ¶
WinHttpReadData reads data from a handle opened by the WinHttpOpenRequest function.
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpreaddata
hRequest is a valid HINTERNET handle returned from a previous call to WinHttpOpenRequest. WinHttpReceiveResponse or WinHttpQueryDataAvailable must have been called for this handle and must have completed before WinHttpReadData is called. Although calling WinHttpReadData immediately after completion of WinHttpReceiveResponse avoids the expense of a buffer copy, doing so requires that the application use a fixed-length buffer for reading.
size is the number of bytes to read
func WinHttpReceiveResponse ¶
WinHttpReceiveResponse waits to receive the response to an HTTP request initiated by WinHttpSendRequest. When WinHttpReceiveResponse completes successfully, the status code and response headers have been received and are available for the application to inspect using WinHttpQueryHeaders. An application must call WinHttpReceiveResponse before it can use WinHttpQueryDataAvailable and WinHttpReadData to access the response entity body (if any).
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpreceiveresponse
hRequest an HINTERNET handle returned by WinHttpOpenRequest and sent by WinHttpSendRequest.
Wait until WinHttpSendRequest has completed for this handle before calling WinHttpReceiveResponse.
func WinHttpSendRequest ¶
func WinHttpSendRequest(hRequest windows.Handle, headers string, headersLength uint32, optionalData uintptr, optionalDataLen uint32, totalLen uint32, context uintptr) error
WinHttpSendRequest sends the specified request to the HTTP server
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpsendrequest
hRequest is an HINTERNET handle returned by WinHttpOpenRequest.
headers an string that contains the additional headers to append to the request.
This parameter can be WINHTTP_NO_ADDITIONAL_HEADERS if there are no additional headers to append.
headersLength contains the length, in characters, of the additional headers.
If this parameter is -1L and pwszHeaders is not NULL, this function assumes that pwszHeaders is null-terminated, and the length is calculated.
optionalData is a pointer a buffer that contains any optional data to send immediately after the request headers.
This parameter is generally used for POST and PUT operations. The optional data can be the resource or data posted to the server. This parameter can be WINHTTP_NO_REQUEST_DATA if there is no optional data to send. If the dwOptionalLength parameter is 0, this parameter is ignored and set to NULL. This buffer must remain available until the request handle is closed or the call to WinHttpReceiveResponse has completed.
optionalDataLen is an unsigned long integer value that contains the length, in bytes, of the optional data.
This parameter can be zero if there is no optional data to send. This parameter must contain a valid length when the lpOptional parameter is not NULL. Otherwise, lpOptional is ignored and set to NULL.
totalLen is an unsigned long integer value that contains the length, in bytes, of the total data sent.
This parameter specifies the Content-Length header of the request. If the value of this parameter is greater than the length specified by dwOptionalLength, then WinHttpWriteData can be used to send additional data. dwTotalLength must not change between calls to WinHttpSendRequest for the same request. If dwTotalLength needs to be changed, the caller should create a new request.
context A pointer to a pointer-sized variable that contains an application-defined value that is passed, with the request handle, to any callback functions.
func WinHttpSetOption ¶
WinHttpSetOption set an internal option
https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nf-winhttp-winhttpsetoption
hInternet is the HINTERNET handle on which to set data. Be aware that this can be either a Session handle or a Request handle, depending on what option is being set. For more information about how to determine which handle is appropriate to use in setting a particular option, see the Option Flags.
option contains the Internet option to set. This can be one of the Option Flags values. https://learn.microsoft.com/en-us/windows/win32/winhttp/option-flags
buffer a pointer to a buffer that contains the option setting.
size contains the length of the buffer. The length of the buffer is specified in characters for the following options; for all other options, the length is specified in bytes.
Types ¶
type Client ¶
type Client struct {
Transport http.RoundTripper
Timeout time.Duration
}
Client is an HTTP client used for making HTTP requests using the Windows winhttp API This type mimics the Golang http.Client type at https://pkg.go.dev/net/http#Client The Transport is optional and the http.DefaultTransport will be used if one is not provided
func NewHTTPClient ¶
NewHTTPClient returns an HTTP/1.1 client using the Windows WinHTTP API
func (*Client) Do ¶
Do send an HTTP request and returns an HTTP response using the Windows winhttp API. The high-level API call flow to send data is: WinHttpOpen -> WinHttpConnect -> WinHttpOpenRequest -> WinHttpSendRequest. The high-level API call flow to receive data is: WinHttpReceiveResponse -> WinHttpQueryDataAvailable -> WinHttpReadData.
func (*Client) Get ¶
Get issues an HTTP GET request to the specified URL and returns an HTTP response
Source Files
Directories