h2_client.h File Reference

HTTP/2 client API. More...

#include <stddef.h>
#include <stdint.h>
#include <keel/allocator.h>
#include <keel/event_ctx.h>
#include <keel/h2.h>
#include <keel/tls.h>

Include dependency graph for h2_client.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	KlH2ClientHeader
struct	KlH2ClientResponse
struct	KlH2ClientCallbacks
struct	KlH2ClientSession
struct	KlH2ClientConfig

Macros
#define	KL_H2_CLIENT_DEFAULT_TIMEOUT_MS   30000
	Default connect/request timeout (ms).
#define	KL_H2_CLIENT_RECV_BUF_SIZE   16384
	Receive buffer size (bytes).

Typedefs
typedef struct KlH2ClientConn	KlH2ClientConn
typedef struct KlH2ClientStream	KlH2ClientStream
typedef struct KlH2ClientSession	KlH2ClientSession
typedef KlH2ClientSession *(*	KlH2ClientSessionFactory) (KlAllocator *alloc)
	Factory for creating client-side HTTP/2 sessions.
typedef void(*	KlH2ClientResponseFn) (KlH2ClientConn *c, int32_t stream_id, const KlH2ClientResponse *resp, void *user_data)
	Per-stream response completion callback.
typedef void(*	KlH2ClientErrorFn) (KlH2ClientConn *c, const char *msg, void *user_data)
	Connection-level error callback.

Functions
KlH2ClientConn *	kl_h2_client_connect (KlEventCtx *ev, KlAllocator *alloc, const KlH2ClientConfig *cfg, const char *url, KlH2ClientErrorFn on_error, void *user_data)
	Connect to an HTTP/2 server.
int32_t	kl_h2_client_request (KlH2ClientConn *c, const char *method, const char *path, const KlH2ClientHeader *hdrs, int n, const char *body, size_t body_len, KlH2ClientResponseFn on_resp, void *ud)
	Submit an HTTP/2 request.
void	kl_h2_client_close (KlH2ClientConn *c)
	Close the HTTP/2 client connection.
void	kl_h2_client_free (KlH2ClientConn *c)
	Free all HTTP/2 client resources.
void	kl_h2_client_response_free (KlH2ClientResponse *resp, KlAllocator *alloc)
	Free a response's headers and body (allocator-owned).

Detailed Description

HTTP/2 client API.

Async HTTP/2 client driven by KlEventCtx watchers. Uses a pluggable session vtable (KlH2ClientSession) so the actual HTTP/2 framing can be backed by nghttp2 or any other library. Shared protocol constants (max streams, window size) from h2.h.

Macro Definition Documentation

KL_H2_CLIENT_DEFAULT_TIMEOUT_MS

#define KL_H2_CLIENT_DEFAULT_TIMEOUT_MS   30000

Default connect/request timeout (ms).

KL_H2_CLIENT_RECV_BUF_SIZE

#define KL_H2_CLIENT_RECV_BUF_SIZE   16384

Receive buffer size (bytes).

Typedef Documentation

KlH2ClientConn

typedef struct KlH2ClientConn KlH2ClientConn

KlH2ClientStream

typedef struct KlH2ClientStream KlH2ClientStream

KlH2ClientSession

typedef struct KlH2ClientSession KlH2ClientSession

KlH2ClientSessionFactory

typedef KlH2ClientSession *(* KlH2ClientSessionFactory) (KlAllocator *alloc)

Factory for creating client-side HTTP/2 sessions.

KlH2ClientResponseFn

typedef void(* KlH2ClientResponseFn) (KlH2ClientConn *c, int32_t stream_id, const KlH2ClientResponse *resp, void *user_data)

Per-stream response completion callback.

KlH2ClientErrorFn

typedef void(* KlH2ClientErrorFn) (KlH2ClientConn *c, const char *msg, void *user_data)

Connection-level error callback.

Function Documentation

kl_h2_client_connect()

KlH2ClientConn * kl_h2_client_connect	(	KlEventCtx *	ev,
		KlAllocator *	alloc,
		const KlH2ClientConfig *	cfg,
		const char *	url,
		KlH2ClientErrorFn	on_error,
		void *	user_data
	)

Connect to an HTTP/2 server.

Initiates TCP connect, optional TLS handshake, then creates the H2 session via the factory. Drives I/O via KlEventCtx watchers.

Parameters

ev	Event context.
alloc	Allocator (must outlive connection).
cfg	Configuration (session factory required).
url	Target URL (http:// or https://).
on_error	Error callback.
user_data	Opaque pointer for callbacks.

Returns

Connection handle, or NULL on failure.

kl_h2_client_request()

int32_t kl_h2_client_request	(	KlH2ClientConn *	c,
		const char *	method,
		const char *	path,
		const KlH2ClientHeader *	hdrs,
		int	n,
		const char *	body,
		size_t	body_len,
		KlH2ClientResponseFn	on_resp,
		void *	ud
	)

Submit an HTTP/2 request.

Returns

Stream ID (>0) on success, -1 on error.

kl_h2_client_close()

void kl_h2_client_close

(

KlH2ClientConn *

c

)

Close the HTTP/2 client connection.

kl_h2_client_free()

void kl_h2_client_free

(

KlH2ClientConn *

c

)

Free all HTTP/2 client resources.

kl_h2_client_response_free()

void kl_h2_client_response_free	(	KlH2ClientResponse *	resp,
		KlAllocator *	alloc
	)

Free a response's headers and body (allocator-owned).