telodendria/include/Cytoplasm/HttpClient.h
Jordan Bancino 461357b526 Move headers from src/include to include/Cytoplasm.
This makes it easier to build Cytoplasm as a component of another
program (for example, Telodendria), or as a standalone system library.
2024-01-13 18:40:31 -05:00

104 lines
3.4 KiB
C

/*
* Copyright (C) 2022-2024 Jordan Bancino <@jordan:bancino.net>
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation files
* (the "Software"), to deal in the Software without restriction,
* including without limitation the rights to use, copy, modify, merge,
* publish, distribute, sublicense, and/or sell copies of the Software,
* and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
#ifndef CYTOPLASM_HTTPCLIENT_H
#define CYTOPLASM_HTTPCLIENT_H
/***
* @Nm HttpClient
* @Nd Extremely simple HTTP client.
* @Dd April 29 2023
* @Xr Http HttpServer Tls
*
* .Nm
* HttpClient
* builds on the HTTP API to provide a simple yet functional HTTP
* client. It aims at being easy to use and minimal, yet also
* efficient.
*/
#include <stdio.h>
#include "HashMap.h"
#include "Http.h"
/**
* A server response is represented by a client context. It is
* opaque, so the functions defined in this API should be used to
* fetch data from and manipulate it.
*/
typedef struct HttpClientContext HttpClientContext;
/**
* Make an HTTP request. This function takes the request method,
* any flags defined in the HTTP API, the port, hostname, and path,
* all in that order. It returns NULL if there was an error making
* the request. Otherwise it returns a client context. Note that this
* function does not actually send any data, it simply makes the
* connection. Use
* .Fn HttpRequestHeader
* to add headers to the request. Then, send headers with
* .Fn HttpRequestSendHeaders .
* Finally, the request body, if any, can be written to the output
* stream, and then the request can be fully sent using
* .Fn HttpRequestSend .
*/
extern HttpClientContext *
HttpRequest(HttpRequestMethod, int, unsigned short, char *, char *);
/**
* Set a request header to send to the server when making the
* request.
*/
extern void HttpRequestHeader(HttpClientContext *, char *, char *);
/**
* Send the request headers to the server. This must be called before
* the request body can be written or a response body can be read.
*/
extern void HttpRequestSendHeaders(HttpClientContext *);
/**
* Flush the request stream to the server. This function should be
* called before the response body is read.
*/
extern HttpStatus HttpRequestSend(HttpClientContext *);
/**
* Get the headers returned by the server.
*/
extern HashMap * HttpResponseHeaders(HttpClientContext *);
/**
* Get the stream used to write the request body and read the
* response body.
*/
extern Stream * HttpClientStream(HttpClientContext *);
/**
* Free all memory associated with the client context. This closes the
* connection, if it was still open.
*/
extern void HttpClientContextFree(HttpClientContext *);
#endif /* CYTOPLASM_HTTPCLIENT_H */