The winhttp Reference Manual

This is the winhttp Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 18:17:24 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 winhttp

FFI wrapper to WINHTTP

Author

Frank James <>

License

MIT

Dependency

cffi (system).

Source

winhttp.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 winhttp/winhttp.asd

Source

winhttp.asd.

Parent Component

winhttp (system).

ASDF Systems

winhttp.


3.1.2 winhttp/package.lisp

Source

winhttp.asd.

Parent Component

winhttp (system).

Packages

winhttp.


3.1.3 winhttp/ffi.lisp

Dependency

package.lisp (file).

Source

winhttp.asd.

Parent Component

winhttp (system).

Public Interface
Internals

3.1.4 winhttp/util.lisp

Dependency

ffi.lisp (file).

Source

winhttp.asd.

Parent Component

winhttp (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 winhttp

Source

package.lisp.

Use List
  • cffi.
  • common-lisp.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Macros

Macro: define-status-callback (name (hinternet context status infop infolen) &body body)

Define a foreign callback function which can be used to receive http request status updates. See MSDN for information on WinHttpSetStatusCallback function. Use SET-STATUS-CALLBACK to register this with a request handle.

HINTERNET ::= handle
CONTEXT ::= pointer to DWORD context
STATUS ::= symbol naming status update type
INFOP ::= pointer to info buffer
INFOLEN ::= length of info buffer

Package

winhttp.

Source

util.lisp.

Macro: with-connect ((var http hostname port) &body body)

Evaluate body with VAR bound to a connection handle.

Package

winhttp.

Source

util.lisp.

Macro: with-http ((var &optional user-agent) &body body)

Evaluate body with VAR bound to a session handle.

Package

winhttp.

Source

util.lisp.

Macro: with-request ((var hconn &key verb url https-p) &body body)

Evaludate body with VAR bound to a request handle.

Package

winhttp.

Source

util.lisp.

Macro: with-websocket ((var hostname port &key url https-p) &body body)

Bind VAR to a websocket connected to hostname:port/url.

Package

winhttp.

Source

ffi.lisp.


5.1.2 Ordinary functions

Function: add-request-headers (hreq header)
Package

winhttp.

Source

ffi.lisp.

Function: close-handle (h)
Package

winhttp.

Source

ffi.lisp.

Function: crack-url (url)

Parse a URL into its components.

Package

winhttp.

Source

ffi.lisp.

Function: http-connect (hsession hostname &optional port)
Package

winhttp.

Source

ffi.lisp.

Function: http-open (&optional user-agent)
Package

winhttp.

Source

ffi.lisp.

Function: http-open-request (hconnect &key verb url https-p)
Package

winhttp.

Source

ffi.lisp.

Function: http-request (url &key method post-data post-start post-end rawp headers timeout ignore-certificates-p statuscb recv-buf recv-start recv-end)

Send HTTP request to server.
URL ::= string in format [http|https://][username:password@]hostname[:port][/url]
METHOD ::= HTTP verb e.g. :GET, :POST etc
POST-DATA ::= if specified, is an octet vector sent as post data. Uses region bounded by POST-START and POST-END.
RAWP ::= if true returns octets otherwise return data is parsed as text.
HEADERS ::= list of (header &optional value)* extra headers to add.
TIMEOUT ::= integer milliseconds to wait for connection and receive. IGNORE-CERTIFICATES-P ::= if true will set option flags to ignore certificate errors. STATUSCB ::= if non-nil, is a symbol naming a callback defined using define-status-callback. This will be invoked to inform various status messages.
RECV-BUF ::= if provided, is an octet vector that receives the reply body.
If not supplied a buffer is allocated. Uses region bounded by RECV-START and RECV-END. Returns values return-data status-code headers content-length.

Package

winhttp.

Source

util.lisp.

Function: query-data-available (hreq)
Package

winhttp.

Source

ffi.lisp.

Function: query-headers (hreq)
Package

winhttp.

Source

ffi.lisp.

Function: query-status-code (hreq)
Package

winhttp.

Source

ffi.lisp.

Function: read-data (hreq seq &key start end)
Package

winhttp.

Source

ffi.lisp.

Function: receive-response (hreq)
Package

winhttp.

Source

ffi.lisp.

Function: send-request (hreq seq &key start end)
Package

winhttp.

Source

ffi.lisp.

Function: set-credentials (hreq username password &optional scheme target)
Package

winhttp.

Source

ffi.lisp.

Function: set-status-callback (hinternet callback)

Set a callback to receive status updates. This can be used to track progress of an HTTP request.
HINTERNET ::= request handle
CALLBACK ::= foreign callback address.

Package

winhttp.

Source

ffi.lisp.

Function: upgrade-to-websocket (hrequest)

Call this before the initial SEND-REQUEST call.

Package

winhttp.

Source

ffi.lisp.

Function: websocket-close (hwebsocket &optional status)

Close the websocket handle

Package

winhttp.

Source

ffi.lisp.

Function: websocket-complete-upgrade (hrequest)

Complete the upgrade to the websocket. returns the websocket handle. The request handle can now be closed.

Package

winhttp.

Source

ffi.lisp.

Function: websocket-query-close-status (hwebsocket)

Get the websocket close status.

Package

winhttp.

Source

ffi.lisp.

Function: websocket-receive (hwebsocket seq &key start end)

Receive some data.
HWEBSOCKET ::= the websocket handke SEQ ::= buffer that receives the data START, END ::= buffer region to fill in returns values count buffer-type, where COUNT ::= number of bytes received BUFFER-TYPE ::= type of message received

Package

winhttp.

Source

ffi.lisp.

Function: websocket-send (hwebsocket seq &key start end buffer-type)

Send some data on a websocket. HWEBSOCKET ::= websocket handle SEQ ::= buffer
START,END ::= buffer region to send BUFFER-TYPE ::= type of message

Package

winhttp.

Source

ffi.lisp.

Function: websocket-shutdown (hwebsocket &optional status)

Shutdown a websocket

Package

winhttp.

Source

ffi.lisp.


5.2 Internals


5.2.1 Constants

Constant: +access-no-proxy+
Package

winhttp.

Source

ffi.lisp.

Constant: +addreq-add+
Package

winhttp.

Source

ffi.lisp.

Constant: +addreq-replace+
Package

winhttp.

Source

ffi.lisp.

Constant: +flag-secure+
Package

winhttp.

Source

ffi.lisp.

Constant: +icu-decode+
Package

winhttp.

Source

ffi.lisp.

Constant: +icu-escape+
Package

winhttp.

Source

ffi.lisp.

Constant: +websocket-binary-fragment+
Package

winhttp.

Source

ffi.lisp.

Constant: +websocket-binary-message+
Package

winhttp.

Source

ffi.lisp.

Constant: +websocket-close+
Package

winhttp.

Source

ffi.lisp.

Constant: +websocket-utf8-fragment+
Package

winhttp.

Source

ffi.lisp.

Constant: +websocket-utf8-message+
Package

winhttp.

Source

ffi.lisp.

Constant: +winhttp-option-upgrade-to-web-socket+
Package

winhttp.

Source

ffi.lisp.


5.2.2 Special variables

Special Variable: *charsets*
Package

winhttp.

Source

util.lisp.

Special Variable: *info-levels*
Package

winhttp.

Source

ffi.lisp.

Special Variable: *status-cb-types*
Package

winhttp.

Source

util.lisp.

Special Variable: *winhttp-errors*
Package

winhttp.

Source

ffi.lisp.


5.2.3 Macros

Macro: with-buffers (bindings &body body)
Package

winhttp.

Source

ffi.lisp.

Macro: with-wide-string ((var string) &body body)
Package

winhttp.

Source

ffi.lisp.


5.2.4 Ordinary functions

Function: %add-request-headers (hreq headers len modifiers)
Package

winhttp.

Source

ffi.lisp.

Function: %close-handle (h)
Package

winhttp.

Source

ffi.lisp.

Function: %crack-url (url url-len flags components)
Package

winhttp.

Source

ffi.lisp.

Function: %format-message (flags source msg-id lang-id buffer size args)
Package

winhttp.

Source

ffi.lisp.

Function: %get-last-error ()
Package

winhttp.

Source

ffi.lisp.

Function: %http-connect (hsession server port reserved)
Package

winhttp.

Source

ffi.lisp.

Function: %http-open (user access-type proxy bypass flags)
Package

winhttp.

Source

ffi.lisp.

Function: %http-query-headers (hreq info name buf len idx)
Package

winhttp.

Source

ffi.lisp.

Function: %query-data-available (hreq nbytes)
Package

winhttp.

Source

ffi.lisp.

Function: %read-data (hreq buf len nbytes)
Package

winhttp.

Source

ffi.lisp.

Function: %receive-response (hreq reserved)
Package

winhttp.

Source

ffi.lisp.

Function: %send-request (hreq headers hlen optional len total context)
Package

winhttp.

Source

ffi.lisp.

Function: %set-credentials (hreq targets scheme username password params)
Package

winhttp.

Source

ffi.lisp.

Function: %set-option (hreq option buf len)
Package

winhttp.

Source

ffi.lisp.

Function: %set-status-callback (hinternet callback flags reserved)
Package

winhttp.

Source

ffi.lisp.

Function: %set-timeouts (hreq resolve connect send recv)
Package

winhttp.

Source

ffi.lisp.

Function: %websocket-close (hwebsocket status reason creason)
Package

winhttp.

Source

ffi.lisp.

Function: %websocket-complete-upgrade (hreq pcxt)
Package

winhttp.

Source

ffi.lisp.

Function: %websocket-query-close-status (hwebsocket status reason creason reasonlength)
Package

winhttp.

Source

ffi.lisp.

Function: %websocket-recv (hwebsocket buffer cbuffer nbytes buffertype)
Package

winhttp.

Source

ffi.lisp.

Function: %websocket-send (hwebsocket btype buf cbuf)
Package

winhttp.

Source

ffi.lisp.

Function: %websocket-shutdown (hwebsocket status reason creason)
Package

winhttp.

Source

ffi.lisp.

Function: %win-http-open-request (hconnect verb object version referrer accept-types flags)
Package

winhttp.

Source

ffi.lisp.

Function: charset-by-name (str)

Lookup a charset identifier by name. We only support the charsets supported by babel. We do a lookup by name because we don’t want to be interning strings received from the web server.

Package

winhttp.

Source

util.lisp.

Function: format-message (code)

Use FormatMessage to convert the error code into a system-defined string.

Package

winhttp.

Source

ffi.lisp.

Function: get-buffer-type (buffertype)
Package

winhttp.

Source

ffi.lisp.

Function: get-content-charset (headers)

Try and get the content charset from the headers. We need this otherwise babel may not be able to decode the text.

Package

winhttp.

Source

util.lisp.

Function: get-last-error ()
Package

winhttp.

Source

ffi.lisp.

Function: memset (p type &optional val)
Package

winhttp.

Source

ffi.lisp.

Function: query-content-length (headers)

Returns content length as specified in header.

Package

winhttp.

Source

util.lisp.

Function: query-info-level (name)
Package

winhttp.

Source

ffi.lisp.

Function: set-ignore-certificates (hreq)
Package

winhttp.

Source

ffi.lisp.

Function: set-secure-protocols (hinternet &key ssl2 ssl3 tls1 tls1-1 tls1-2)

Set the TLS protocols that can be used for a session. HINTERNET ::= session handle.

Package

winhttp.

Source

ffi.lisp.

Function: set-timeouts (hreq &key resolve connect send recv)
Package

winhttp.

Source

ffi.lisp.

Function: winhttp-error-string (code)
Package

winhttp.

Source

ffi.lisp.


5.2.5 Generic functions

Generic Reader: win-error-code (condition)
Package

winhttp.

Methods
Reader Method: win-error-code ((condition win-error))
Source

ffi.lisp.

Target Slot

code.


5.2.6 Conditions

Condition: win-error
Package

winhttp.

Source

ffi.lisp.

Direct superclasses

error.

Direct methods

win-error-code.

Direct slots
Slot: code
Initform

(quote 0)

Initargs

:code

Readers

win-error-code.

Writers

This slot is read-only.


5.2.7 Classes

Class: url-components-tclass
Package

winhttp.

Source

ffi.lisp.

Direct superclasses
  • foreign-struct-type.
  • translatable-foreign-type.

Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %  
A   C   D   F   G   H   M   Q   R   S   U   W  
Index Entry  Section

%
%add-request-headers: Private ordinary functions
%close-handle: Private ordinary functions
%crack-url: Private ordinary functions
%format-message: Private ordinary functions
%get-last-error: Private ordinary functions
%http-connect: Private ordinary functions
%http-open: Private ordinary functions
%http-query-headers: Private ordinary functions
%query-data-available: Private ordinary functions
%read-data: Private ordinary functions
%receive-response: Private ordinary functions
%send-request: Private ordinary functions
%set-credentials: Private ordinary functions
%set-option: Private ordinary functions
%set-status-callback: Private ordinary functions
%set-timeouts: Private ordinary functions
%websocket-close: Private ordinary functions
%websocket-complete-upgrade: Private ordinary functions
%websocket-query-close-status: Private ordinary functions
%websocket-recv: Private ordinary functions
%websocket-send: Private ordinary functions
%websocket-shutdown: Private ordinary functions
%win-http-open-request: Private ordinary functions

A
add-request-headers: Public ordinary functions

C
charset-by-name: Private ordinary functions
close-handle: Public ordinary functions
crack-url: Public ordinary functions

D
define-status-callback: Public macros

F
format-message: Private ordinary functions
Function, %add-request-headers: Private ordinary functions
Function, %close-handle: Private ordinary functions
Function, %crack-url: Private ordinary functions
Function, %format-message: Private ordinary functions
Function, %get-last-error: Private ordinary functions
Function, %http-connect: Private ordinary functions
Function, %http-open: Private ordinary functions
Function, %http-query-headers: Private ordinary functions
Function, %query-data-available: Private ordinary functions
Function, %read-data: Private ordinary functions
Function, %receive-response: Private ordinary functions
Function, %send-request: Private ordinary functions
Function, %set-credentials: Private ordinary functions
Function, %set-option: Private ordinary functions
Function, %set-status-callback: Private ordinary functions
Function, %set-timeouts: Private ordinary functions
Function, %websocket-close: Private ordinary functions
Function, %websocket-complete-upgrade: Private ordinary functions
Function, %websocket-query-close-status: Private ordinary functions
Function, %websocket-recv: Private ordinary functions
Function, %websocket-send: Private ordinary functions
Function, %websocket-shutdown: Private ordinary functions
Function, %win-http-open-request: Private ordinary functions
Function, add-request-headers: Public ordinary functions
Function, charset-by-name: Private ordinary functions
Function, close-handle: Public ordinary functions
Function, crack-url: Public ordinary functions
Function, format-message: Private ordinary functions
Function, get-buffer-type: Private ordinary functions
Function, get-content-charset: Private ordinary functions
Function, get-last-error: Private ordinary functions
Function, http-connect: Public ordinary functions
Function, http-open: Public ordinary functions
Function, http-open-request: Public ordinary functions
Function, http-request: Public ordinary functions
Function, memset: Private ordinary functions
Function, query-content-length: Private ordinary functions
Function, query-data-available: Public ordinary functions
Function, query-headers: Public ordinary functions
Function, query-info-level: Private ordinary functions
Function, query-status-code: Public ordinary functions
Function, read-data: Public ordinary functions
Function, receive-response: Public ordinary functions
Function, send-request: Public ordinary functions
Function, set-credentials: Public ordinary functions
Function, set-ignore-certificates: Private ordinary functions
Function, set-secure-protocols: Private ordinary functions
Function, set-status-callback: Public ordinary functions
Function, set-timeouts: Private ordinary functions
Function, upgrade-to-websocket: Public ordinary functions
Function, websocket-close: Public ordinary functions
Function, websocket-complete-upgrade: Public ordinary functions
Function, websocket-query-close-status: Public ordinary functions
Function, websocket-receive: Public ordinary functions
Function, websocket-send: Public ordinary functions
Function, websocket-shutdown: Public ordinary functions
Function, winhttp-error-string: Private ordinary functions

G
Generic Function, win-error-code: Private generic functions
get-buffer-type: Private ordinary functions
get-content-charset: Private ordinary functions
get-last-error: Private ordinary functions

H
http-connect: Public ordinary functions
http-open: Public ordinary functions
http-open-request: Public ordinary functions
http-request: Public ordinary functions

M
Macro, define-status-callback: Public macros
Macro, with-buffers: Private macros
Macro, with-connect: Public macros
Macro, with-http: Public macros
Macro, with-request: Public macros
Macro, with-websocket: Public macros
Macro, with-wide-string: Private macros
memset: Private ordinary functions
Method, win-error-code: Private generic functions

Q
query-content-length: Private ordinary functions
query-data-available: Public ordinary functions
query-headers: Public ordinary functions
query-info-level: Private ordinary functions
query-status-code: Public ordinary functions

R
read-data: Public ordinary functions
receive-response: Public ordinary functions

S
send-request: Public ordinary functions
set-credentials: Public ordinary functions
set-ignore-certificates: Private ordinary functions
set-secure-protocols: Private ordinary functions
set-status-callback: Public ordinary functions
set-timeouts: Private ordinary functions

U
upgrade-to-websocket: Public ordinary functions

W
websocket-close: Public ordinary functions
websocket-complete-upgrade: Public ordinary functions
websocket-query-close-status: Public ordinary functions
websocket-receive: Public ordinary functions
websocket-send: Public ordinary functions
websocket-shutdown: Public ordinary functions
win-error-code: Private generic functions
win-error-code: Private generic functions
winhttp-error-string: Private ordinary functions
with-buffers: Private macros
with-connect: Public macros
with-http: Public macros
with-request: Public macros
with-websocket: Public macros
with-wide-string: Private macros


A.3 Variables

Jump to:   *   +  
C   S  
Index Entry  Section

*
*charsets*: Private special variables
*info-levels*: Private special variables
*status-cb-types*: Private special variables
*winhttp-errors*: Private special variables

+
+access-no-proxy+: Private constants
+addreq-add+: Private constants
+addreq-replace+: Private constants
+flag-secure+: Private constants
+icu-decode+: Private constants
+icu-escape+: Private constants
+websocket-binary-fragment+: Private constants
+websocket-binary-message+: Private constants
+websocket-close+: Private constants
+websocket-utf8-fragment+: Private constants
+websocket-utf8-message+: Private constants
+winhttp-option-upgrade-to-web-socket+: Private constants

C
code: Private conditions
Constant, +access-no-proxy+: Private constants
Constant, +addreq-add+: Private constants
Constant, +addreq-replace+: Private constants
Constant, +flag-secure+: Private constants
Constant, +icu-decode+: Private constants
Constant, +icu-escape+: Private constants
Constant, +websocket-binary-fragment+: Private constants
Constant, +websocket-binary-message+: Private constants
Constant, +websocket-close+: Private constants
Constant, +websocket-utf8-fragment+: Private constants
Constant, +websocket-utf8-message+: Private constants
Constant, +winhttp-option-upgrade-to-web-socket+: Private constants

S
Slot, code: Private conditions
Special Variable, *charsets*: Private special variables
Special Variable, *info-levels*: Private special variables
Special Variable, *status-cb-types*: Private special variables
Special Variable, *winhttp-errors*: Private special variables