anntp

a nntp implementation in pure C99
Log | Files | Refs | README | LICENSE

README (2582B)

      1 *****************************
      2                  __
      3  ___ ____  ___  / /____ 
      4 / _ `/ _ \/ _ \/ __/ _ \
      5 \_,_/_//_/_//_/\__/ .__/
      6                   /_/    
      7                        v0.1.0
      8 *****************************
      9 
     10 anntp minimalist, light, and hackable single-header NNTP (Network News Transfer Protocol) client library implemented in
     11 semi-portable C99.    It is low-level, but still usable, minimalist, and portable enough between UNIX systems.
     12 
     13 Right now, it supports:
     14 
     15 * multiple connections,
     16 * low-level server/client I/O, with a billion variation of the same two functions,
     17 * auth,
     18 * TLS (just TLS, no STARTTLS, sorry),
     19 * error-handling,
     20 * "idiomatic" C
     21 
     22 ---
     23 
     24 Requirements
     25 ============
     26 
     27 * A C compiler
     28 * OpenSSL/LibreSSL (optional) for TLS support
     29 * An UNIX like system
     30 
     31 Usage
     32 =====
     33 
     34 0) Copy anntp.h to your project
     35 1) Include the library in as many places as you want, but in one, add:
     36 
     37 	#define ANNTP_IMPLEMENTATION
     38 
     39     *before* including anntp.h
     40 2) Optionally, define any of these to configure anntp:
     41 	+ ANNTP_BUFSIZE [0x1000]: Default buffer size
     42 	+ ANNTP_MALLOC [malloc]: Memory allocator function
     43 	+ ANNTP_FREE [free]: Memory freeing function
     44 	+ ANNTP_STRDUP [stdup or custom]: strdup() function
     45 	+ ANNTP_API [extern]: Extra function declaration type for API functions
     46 
     47 3) ENJOY!
     48 
     49 Memory management
     50 -----------------
     51 
     52 `anntp_free_*` functions free stuff, see their arguments to what they free, it should be obvious when looking at them
     53 
     54 > NOTE: all strings returned by the library are dynamically allocated
     55 
     56 Error handling
     57 --------------
     58 
     59 There is an AnntpErrCode enum with the types of errors:
     60 
     61 * ANE_OK	- success
     62 * ANE_PARAMS	- wrong parameters
     63 * ANE_IO	- I/O error (OOM, sending, receiving, ..., pretty broad of a variant)
     64 * ANE_TLS	- TLS error
     65 * ANE_PROTO	- protocol exception; server sent something unexpected
     66 * ANE_AUTH	- authentication failure
     67 
     68 EXAMPLES
     69 ========
     70 
     71 See examples/ for a couple examples, but for now you can read the greeting with:
     72 
     73 	#include <stdio.h>
     74 	#define ANNTP_IMPLEMENTATION
     75 	#include "anntp.h"
     76 
     77 	int
     78 	main()
     79 	{
     80 		anntp_init();
     81 		AnntpConnection* c = anntp_mkconn("news.example.com", "119", false);
     82 		if (!c) return 1;
     83 
     84 		char line[256];
     85 		if (anntp_readline(c, line, sizeof(line)) > 0) {
     86 			puts(line);
     87 		}
     88 
     89 		anntp_freeconn(c);
     90 		return 0;
     91 	}
     92 
     93 LICENSE
     94 =======
     95 
     96 Under the CC0. Public domain! Use at your own risk.
     97 
     98 See more information at the LICENSE file.
     99 
    100 CONTACT
    101 =======
    102 
    103 * Mario Rosell <mario@mariorosell.es (email broken right now)
    104 * Contributors: See CONTRIBUTORS file for more.
    105 
    106 TODOS
    107 =====
    108 
    109 See the NEWS file for a changelog and info.
    110