The winhttp Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The winhttp Reference Manual

This is the winhttp Reference Manual, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Fri May 24 10:04:30 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

winhttp

CFFI bindings to WinHttp.dll. Provides a native HTTP client for those few Common Lisp Windows users.

1. Introduction

The canonical Common Lisp HTTP client is drakma which makes use of cl+ssl. This in turn requires openssl binaries installed on your system. All of this works great on Linux but on Windows this is generally a very poor experience.

However, Microsoft ships a fully featured HTTP client (WinHttp.dll) with Windows and is available on all Windows systems, no installing third party libraries is required.

This project provides a set of cffi bindings to the WinHttp API.

Usage

For almost all uses, the HTTP-REQUEST function is sufficient. It allows sending POST data, optional extra headers, basic authentication credentials.

(http-request "http://www.google.com")

For advanced uses, make use of the with-http, with-connect, with-request macros and other functions. See the relevant MSDN pages for usage of the underlying APIs.

Examples

I've included an example XML-RPC client that I have found useful. It is largely taken from the S-XML-RPC project, replacing the http client with winhttp.

(xmlrpc:call "https://username:password@hostname:port/RPC2" "xmlrpc_method" arg1 arg2 ...)

License

Released under the terms of the MIT license.

Frank James July 2017.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 winhttp

Author

Frank James <frank.a.james@gmail.com>

License

MIT

Description

FFI wrapper to WINHTTP

Dependency

cffi

Source

winhttp.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 winhttp.asd

Location

winhttp.asd

Systems

winhttp (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 winhttp/package.lisp

Parent

winhttp (system)

Location

package.lisp

Packages

winhttp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 winhttp/ffi.lisp

Dependency

package.lisp (file)

Parent

winhttp (system)

Location

ffi.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 winhttp/util.lisp

Dependency

ffi.lisp (file)

Parent

winhttp (system)

Location

util.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 winhttp

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

Macro: with-connect (VAR HTTP HOSTNAME PORT) &body BODY

Evaluate body with VAR bound to a connection handle.

Package

winhttp

Source

util.lisp (file)

Macro: with-http (VAR &optional USER-AGENT) &body BODY

Evaluate body with VAR bound to a session handle.

Package

winhttp

Source

util.lisp (file)

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 (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: add-request-headers HREQ HEADER
Package

winhttp

Source

ffi.lisp (file)

Function: close-handle H
Package

winhttp

Source

ffi.lisp (file)

Function: crack-url URL

Parse a URL into its components.

Package

winhttp

Source

ffi.lisp (file)

Function: http-connect HSESSION HOSTNAME &optional PORT
Package

winhttp

Source

ffi.lisp (file)

Function: http-open &optional USER-AGENT
Package

winhttp

Source

ffi.lisp (file)

Function: http-open-request HCONNECT &key VERB URL HTTPS-P
Package

winhttp

Source

ffi.lisp (file)

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 (file)

Function: query-data-available HREQ
Package

winhttp

Source

ffi.lisp (file)

Function: query-headers HREQ
Package

winhttp

Source

ffi.lisp (file)

Function: query-status-code HREQ
Package

winhttp

Source

ffi.lisp (file)

Function: read-data HREQ SEQ &key START END
Package

winhttp

Source

ffi.lisp (file)

Function: receive-response HREQ
Package

winhttp

Source

ffi.lisp (file)

Function: send-request HREQ SEQ &key START END
Package

winhttp

Source

ffi.lisp (file)

Function: set-credentials HREQ USERNAME PASSWORD &optional SCHEME TARGET
Package

winhttp

Source

ffi.lisp (file)

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 (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Constants

Constant: +access-no-proxy+
Package

winhttp

Source

ffi.lisp (file)

Constant: +addreq-add+
Package

winhttp

Source

ffi.lisp (file)

Constant: +addreq-replace+
Package

winhttp

Source

ffi.lisp (file)

Constant: +flag-secure+
Package

winhttp

Source

ffi.lisp (file)

Constant: +icu-decode+
Package

winhttp

Source

ffi.lisp (file)

Constant: +icu-escape+
Package

winhttp

Source

ffi.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Special variables

Special Variable: *charsets*
Package

winhttp

Source

util.lisp (file)

Special Variable: *info-levels*
Package

winhttp

Source

ffi.lisp (file)

Special Variable: *status-cb-types*
Package

winhttp

Source

util.lisp (file)

Special Variable: *winhttp-errors*
Package

winhttp

Source

ffi.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Macros

Macro: with-buffers BINDINGS &body BODY
Package

winhttp

Source

ffi.lisp (file)

Macro: with-wide-string (VAR STRING) &body BODY
Package

winhttp

Source

ffi.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Functions

Function: %add-request-headers HREQ HEADERS LEN MODIFIERS
Package

winhttp

Source

ffi.lisp (file)

Function: %close-handle H
Package

winhttp

Source

ffi.lisp (file)

Function: %crack-url URL URL-LEN FLAGS COMPONENTS
Package

winhttp

Source

ffi.lisp (file)

Function: %format-message FLAGS SOURCE MSG-ID LANG-ID BUFFER SIZE ARGS
Package

winhttp

Source

ffi.lisp (file)

Function: %get-last-error ()
Package

winhttp

Source

ffi.lisp (file)

Function: %http-connect HSESSION SERVER PORT RESERVED
Package

winhttp

Source

ffi.lisp (file)

Function: %http-open USER ACCESS-TYPE PROXY BYPASS FLAGS
Package

winhttp

Source

ffi.lisp (file)

Function: %http-query-headers HREQ INFO NAME BUF LEN IDX
Package

winhttp

Source

ffi.lisp (file)

Function: %query-data-available HREQ NBYTES
Package

winhttp

Source

ffi.lisp (file)

Function: %read-data HREQ BUF LEN NBYTES
Package

winhttp

Source

ffi.lisp (file)

Function: %receive-response HREQ RESERVED
Package

winhttp

Source

ffi.lisp (file)

Function: %send-request HREQ HEADERS HLEN OPTIONAL LEN TOTAL CONTEXT
Package

winhttp

Source

ffi.lisp (file)

Function: %set-credentials HREQ TARGETS SCHEME USERNAME PASSWORD PARAMS
Package

winhttp

Source

ffi.lisp (file)

Function: %set-option HREQ OPTION BUF LEN
Package

winhttp

Source

ffi.lisp (file)

Function: %set-status-callback HINTERNET CALLBACK FLAGS RESERVED
Package

winhttp

Source

ffi.lisp (file)

Function: %set-timeouts HREQ RESOLVE CONNECT SEND RECV
Package

winhttp

Source

ffi.lisp (file)

Function: %win-http-open-request HCONNECT VERB OBJECT VERSION REFERRER ACCEPT-TYPES FLAGS
Package

winhttp

Source

ffi.lisp (file)

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 (file)

Function: format-message CODE

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

Package

winhttp

Source

ffi.lisp (file)

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 (file)

Function: get-last-error ()
Package

winhttp

Source

ffi.lisp (file)

Function: memset P TYPE &optional VAL
Package

winhttp

Source

ffi.lisp (file)

Function: query-content-length HEADERS

Returns content length as specified in header.

Package

winhttp

Source

util.lisp (file)

Function: query-info-level NAME
Package

winhttp

Source

ffi.lisp (file)

Function: set-ignore-certificates HREQ
Package

winhttp

Source

ffi.lisp (file)

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 (file)

Function: set-timeouts HREQ &key RESOLVE CONNECT SEND RECV
Package

winhttp

Source

ffi.lisp (file)

Function: winhttp-error-string CODE
Package

winhttp

Source

ffi.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.5 Generic functions

Generic Function: win-error-code CONDITION
Package

winhttp

Methods
Method: win-error-code (CONDITION win-error)
Source

ffi.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.6 Conditions

Condition: win-error ()
Package

winhttp

Source

ffi.lisp (file)

Direct superclasses

error (condition)

Direct methods

win-error-code (method)

Direct slots
Slot: code
Initargs

:code

Initform

(quote 0)

Readers

win-error-code (generic function)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.7 Classes

Class: url-components-tclass ()
Package

winhttp

Source

ffi.lisp (file)

Direct superclasses
  • translatable-foreign-type (class)
  • foreign-struct-type (class)

Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   W  
Index Entry  Section

F
File, Lisp, winhttp.asd: The winhttp<dot>asd file
File, Lisp, winhttp/ffi.lisp: The winhttp/ffi<dot>lisp file
File, Lisp, winhttp/package.lisp: The winhttp/package<dot>lisp file
File, Lisp, winhttp/util.lisp: The winhttp/util<dot>lisp file

L
Lisp File, winhttp.asd: The winhttp<dot>asd file
Lisp File, winhttp/ffi.lisp: The winhttp/ffi<dot>lisp file
Lisp File, winhttp/package.lisp: The winhttp/package<dot>lisp file
Lisp File, winhttp/util.lisp: The winhttp/util<dot>lisp file

W
winhttp.asd: The winhttp<dot>asd file
winhttp/ffi.lisp: The winhttp/ffi<dot>lisp file
winhttp/package.lisp: The winhttp/package<dot>lisp file
winhttp/util.lisp: The winhttp/util<dot>lisp file

Jump to:   F   L   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

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

A
add-request-headers: Exported functions

C
charset-by-name: Internal functions
close-handle: Exported functions
crack-url: Exported functions

D
define-status-callback: Exported macros

F
format-message: Internal functions
Function, %add-request-headers: Internal functions
Function, %close-handle: Internal functions
Function, %crack-url: Internal functions
Function, %format-message: Internal functions
Function, %get-last-error: Internal functions
Function, %http-connect: Internal functions
Function, %http-open: Internal functions
Function, %http-query-headers: Internal functions
Function, %query-data-available: Internal functions
Function, %read-data: Internal functions
Function, %receive-response: Internal functions
Function, %send-request: Internal functions
Function, %set-credentials: Internal functions
Function, %set-option: Internal functions
Function, %set-status-callback: Internal functions
Function, %set-timeouts: Internal functions
Function, %win-http-open-request: Internal functions
Function, add-request-headers: Exported functions
Function, charset-by-name: Internal functions
Function, close-handle: Exported functions
Function, crack-url: Exported functions
Function, format-message: Internal functions
Function, get-content-charset: Internal functions
Function, get-last-error: Internal functions
Function, http-connect: Exported functions
Function, http-open: Exported functions
Function, http-open-request: Exported functions
Function, http-request: Exported functions
Function, memset: Internal functions
Function, query-content-length: Internal functions
Function, query-data-available: Exported functions
Function, query-headers: Exported functions
Function, query-info-level: Internal functions
Function, query-status-code: Exported functions
Function, read-data: Exported functions
Function, receive-response: Exported functions
Function, send-request: Exported functions
Function, set-credentials: Exported functions
Function, set-ignore-certificates: Internal functions
Function, set-secure-protocols: Internal functions
Function, set-status-callback: Exported functions
Function, set-timeouts: Internal functions
Function, winhttp-error-string: Internal functions

G
Generic Function, win-error-code: Internal generic functions
get-content-charset: Internal functions
get-last-error: Internal functions

H
http-connect: Exported functions
http-open: Exported functions
http-open-request: Exported functions
http-request: Exported functions

M
Macro, define-status-callback: Exported macros
Macro, with-buffers: Internal macros
Macro, with-connect: Exported macros
Macro, with-http: Exported macros
Macro, with-request: Exported macros
Macro, with-wide-string: Internal macros
memset: Internal functions
Method, win-error-code: Internal generic functions

Q
query-content-length: Internal functions
query-data-available: Exported functions
query-headers: Exported functions
query-info-level: Internal functions
query-status-code: Exported functions

R
read-data: Exported functions
receive-response: Exported functions

S
send-request: Exported functions
set-credentials: Exported functions
set-ignore-certificates: Internal functions
set-secure-protocols: Internal functions
set-status-callback: Exported functions
set-timeouts: Internal functions

W
win-error-code: Internal generic functions
win-error-code: Internal generic functions
winhttp-error-string: Internal functions
with-buffers: Internal macros
with-connect: Exported macros
with-http: Exported macros
with-request: Exported macros
with-wide-string: Internal macros

Jump to:   %  
A   C   D   F   G   H   M   Q   R   S   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +  
C   S  
Index Entry  Section

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

+
+access-no-proxy+: Internal constants
+addreq-add+: Internal constants
+addreq-replace+: Internal constants
+flag-secure+: Internal constants
+icu-decode+: Internal constants
+icu-escape+: Internal constants

C
code: Internal conditions
Constant, +access-no-proxy+: Internal constants
Constant, +addreq-add+: Internal constants
Constant, +addreq-replace+: Internal constants
Constant, +flag-secure+: Internal constants
Constant, +icu-decode+: Internal constants
Constant, +icu-escape+: Internal constants

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

Jump to:   *   +  
C   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S   U   W  
Index Entry  Section

C
Class, url-components-tclass: Internal classes
Condition, win-error: Internal conditions

P
Package, winhttp: The winhttp package

S
System, winhttp: The winhttp system

U
url-components-tclass: Internal classes

W
win-error: Internal conditions
winhttp: The winhttp system
winhttp: The winhttp package

Jump to:   C   P   S   U   W