naett.c

Tiny cross-platform HTTP / HTTPS client library in C.
git clone git://git.finwo.net/lib/naett.c
Log | Files | Refs | README | LICENSE

naett.h (4383B)

      1 #ifndef LIBNAETT_H
      2 #define LIBNAETT_H
      3 
      4 #ifdef __cplusplus
      5 extern "C" {
      6 #endif
      7 
      8 #if __ANDROID__
      9 #include <jni.h>
     10 typedef JavaVM* naettInitData;
     11 #else
     12 typedef void* naettInitData;
     13 #endif
     14 
     15 #define NAETT_UA "Naett/1.0"
     16 
     17 /**
     18  * @brief Global init method.
     19  * Call to initialize the library.
     20  */
     21 void naettInit(naettInitData initThing);
     22 
     23 typedef struct naettReq naettReq;
     24 typedef struct naettRes naettRes;
     25 // If naettReadFunc is called with NULL dest, it must respond with the body size
     26 typedef int (*naettReadFunc)(void* dest, int bufferSize, void* userData);
     27 typedef int (*naettWriteFunc)(const void* source, int bytes, void* userData);
     28 typedef int (*naettHeaderLister)(const char* name, const char* value, void* userData);
     29 
     30 // Option to `naettRequest`
     31 typedef struct naettOption naettOption;
     32 
     33 // Sets request method. Defaults to "GET".
     34 naettOption* naettMethod(const char* method);
     35 // Adds a request header.
     36 naettOption* naettHeader(const char* name, const char* value);
     37 // Sets the request body. Ignored if a body reader is configured.
     38 // The body is not copied, and the passed pointer must be valid for the
     39 // lifetime of the request.
     40 naettOption* naettBody(const char* body, int size);
     41 // Sets a request body reader.
     42 naettOption* naettBodyReader(naettReadFunc reader, void* userData);
     43 // Sets a response body writer.
     44 naettOption* naettBodyWriter(naettWriteFunc writer, void* userData);
     45 // Sets connection timeout in milliseconds.
     46 naettOption* naettTimeout(int milliSeconds);
     47 // Sets the user agent.
     48 naettOption* naettUserAgent(const char *userAgent);
     49 
     50 /**
     51  * @brief Creates a new request to the specified url.
     52  * Use varargs options to configure the connection and following request.
     53  */
     54 #define naettRequest(url, ...) naettRequest_va(url, countOptions(__VA_ARGS__), ##__VA_ARGS__)
     55 
     56 /**
     57  * @brief Creates a new request to the specified url.
     58  * Uses an array of options rather than varargs.
     59  */
     60 naettReq* naettRequestWithOptions(const char* url, int numOptions, const naettOption** options);
     61 
     62 /**
     63  * @brief Makes a request and returns a response object.
     64  * The actual request is processed asynchronously, use `naettComplete`
     65  * to check if the response is completed.
     66  *
     67  * A request object can be reused multiple times to make requests, but
     68  * there can be only one active request using the same request object.
     69  */
     70 naettRes* naettMake(naettReq* request);
     71 
     72 /**
     73  * @brief Frees a previously allocated request object.
     74  * The request must not have any pending responses.
     75  */
     76 void naettFree(naettReq* request);
     77 
     78 /**
     79  * @brief Checks if a response is complete, with a result
     80  * or with an error.
     81  * Use `naettGetStatus` to get the status.
     82  */
     83 int naettComplete(const naettRes* response);
     84 
     85 enum naettStatus {
     86     naettConnectionError = -1,
     87     naettProtocolError = -2,
     88     naettReadError = -3,
     89     naettWriteError = -4,
     90     naettGenericError = -5,
     91     naettProcessing = 0,
     92 };
     93 
     94 /**
     95  * @brief Returns the status of a response.
     96  * Status codes > 0 are HTTP status codes as returned by the server.
     97  * Status codes < 0 are processing errors according to the `naettStatus`
     98  * enum values.
     99  */
    100 int naettGetStatus(const naettRes* response);
    101 
    102 /**
    103  * @brief Returns the response body.
    104  * The body returned by this method is always empty when a custom
    105  * body reader has been set up using the `naettBodyReader` option.
    106  */
    107 const void* naettGetBody(naettRes* response, int* outSize);
    108 
    109 /**
    110  * @brief Returns the HTTP header value for the specified header name.
    111  */
    112 const char* naettGetHeader(naettRes* response, const char* name);
    113 
    114 /**
    115  * @brief Returns how many bytes have been read from the response so far,
    116  * and the integer pointed to by totalSize gets the Content-Length if available,
    117  * or -1 if not (or 0 if headers have not been read yet).
    118  */
    119 int naettGetTotalBytesRead(naettRes* response, int* totalSize);
    120 
    121 /**
    122  * @brief Enumerates all response headers as long as the `lister`
    123  * returns true.
    124  */
    125 void naettListHeaders(naettRes* response, naettHeaderLister lister, void* userData);
    126 
    127 /**
    128  * @brief Returns the request that initiated this response
    129  */
    130 naettReq* naettGetRequest(naettRes* response);
    131 
    132 /**
    133  * @brief Closes a response object.
    134  */
    135 void naettClose(naettRes* response);
    136 
    137 // Varargs glue
    138 naettReq* naettRequest_va(const char* url, int numOptions, ...);
    139 #define countOptions(...) ((sizeof((void*[]){ __VA_ARGS__ }) / sizeof(void*)))
    140 
    141 #ifdef __cplusplus
    142 }
    143 #endif
    144 
    145 #endif  // LIBNAETT_H