README
------

libre - "Generic library for real-time communications with async IO support"
Copyright (C) 2010 - 2016 Creytiv.com

Distributed under BSD license


Design goals:

* Portable POSIX source code (ANSI C89 and ISO C99 standard)
* Robust, fast, low memory footprint
* RFC compliance
* IPv4 and IPv6 support


Modules:

  name:     status:       description:

* aes       unstable      AES (Advanced Encryption Standard)
* base64    testing       Base-64 encoding/decoding functions
* bfcp      unstable      The Binary Floor Control Protocol (BFCP)
* conf      testing       Configuration file parser
* crc32     testing       32-bit CRC defined in ITU V.42
* dbg       testing       Debug printing
* dns       stable        DNS resolving (NAPTR, SRV, A)
* fmt       testing       Formatted printing and regular expression
* hash      testing       Hashmap table
* hmac      testing       HMAC: Keyed-Hashing for Message Authentication
* http      unstable      HTTP parser (RFC 2616)
* httpauth  testing       HTTP-based Authentication (RFC 2617)
* ice       unstable      Interactive Connectivity Establishment (ICE)
* jbuf      testing       Jitter buffer
* json      unstable      JavaScript Object Notation (JSON)
* list      stable        Sortable doubly-linked list handling
* lock      testing       Resource locking functions
* main      testing       Main poll loop
* mbuf      stable        Linear memory buffers
* md5       stable        The MD5 Message-Digest Algorithm (RFC 1321)
* mem       stable        Memory referencing
* mod       testing       Run-time module loading
* mqueue    testing       Thread-safe message queue
* msg       unstable      Generic message component library
* natbd     unstable      NAT Behavior Discovery using STUN
* net       testing       Networking routines
* odict     unstable      Ordered Dictionary
* rtp       testing       Real-time Transport Protocol
* sa        stable        Socket Address functions
* sdp       testing       Session Description Protocol
* sha       testing       Secure Hash Standard, NIST, FIPS PUB 180-1
* sip       stable        Core SIP library
* sipevent  testing       SIP Event framework
* sipreg    stable        SIP register client
* sipsess   stable        SIP Sessions
* srtp      unstable      Secure Real-time Transport Protocol (SRTP)
* stun      stable        Session Traversal Utilities for NAT (STUN)
* sys       testing       System information
* tcp       testing       TCP transport
* telev     testing       Telephony Events (RFC 4733)
* tls       unstable      Transport Layer Security
* tmr       stable        Timer handling
* turn      stable        Obtaining Relay Addresses from STUN (TURN)
* udp       testing       UDP transport
* uri       testing       Generic URI library
* websock   unstable      WebSocket Client and Server

legend:
 "stable"       - Code complete; Stable code and stable API
 "testing"      - Code complete, but API might change
 "unstable"     - Code complete but not completely tested
 "development"  - Code is under development


Features:

* RFC 1321 - The MD5 Message-Digest Algorithm
* RFC 1886 - DNS Extensions to support IP version 6
* RFC 2032 - RTP Payload Format for H.261 Video Streams
* RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1
* RFC 2617 - HTTP Authentication: Basic and Digest Access Authentication
* RFC 2782 - A DNS RR for Specifying the Location of Services (DNS SRV)
* RFC 2915 - The Naming Authority Pointer (NAPTR) DNS Resource Record
* RFC 3261 - SIP: Session Initiation Protocol
* RFC 3263 - Locating SIP Servers
* RFC 3264 - An Offer/Answer Model with SDP
* RFC 3265 - SIP-Specific Event Notification
* RFC 3327 - SIP Extension Header Field for Registering Non-Adjacent Contacts
* RFC 3428 - SIP Extension for Instant Messaging
* RFC 3489 - STUN - Simple Traversal of UDP Through NATs
* RFC 3515 - The SIP Refer Method
* RFC 3550 - RTP: A Transport Protocol for Real-Time Applications
* RFC 3551 - RTP Profile for Audio and Video Conferences with Minimal Control
* RFC 3555 - MIME Type Registration of RTP Payload Formats
* RFC 3556 - SDP Bandwidth Modifiers for RTCP Bandwidth
* RFC 3581 - An Extension to SIP for Symmetric Response Routing
* RFC 3605 - RTCP attribute in SDP
* RFC 3711 - The Secure Real-time Transport Protocol (SRTP)
* RFC 3969 - The IANA URI Parameter Registry for SIP
* RFC 3994 - Indication of Message Composition for Instant Messaging
* RFC 4346 - The TLS Protocol Version 1.1
* RFC 4566 - SDP: Session Description Protocol
* RFC 4582 - The Binary Floor Control Protocol (BFCP)
* RFC 4585 - Extended RTP Profile for RTCP-Based Feedback
* RFC 4733 - RTP Payload for DTMF Digits, Telephony Tones, and Teleph. Signals
* RFC 4961 - Symmetric RTP / RTP Control Protocol (RTCP)
* RFC 5118 - SIP Torture Test Messages for IPv6
* RFC 5245 - Interactive Connectivity Establishment (ICE)
* RFC 5389 - Session Traversal Utilities for NAT (STUN)
* RFC 5626 - Managing Client-Initiated Connections in SIP
* RFC 5761 - Multiplexing RTP Data and Control Packets on a Single Port
* RFC 5766 - Traversal Using Relays around NAT (TURN)
* RFC 5768 - Indicating Support for ICE in SIP
* RFC 5769 - Test vectors for STUN
* RFC 5780 - NAT Behaviour Discovery Using STUN
* RFC 6026 - Correct Transaction Handling for 2xx Resp. to SIP INVITE Requests
* RFC 6156 - TURN Extension for IPv6
* RFC 6188 - The Use of AES-192 and AES-256 in Secure RTP
* RFC 6455 - The WebSocket Protocol
* RFC 7159 - JavaScript Object Notation (JSON)
* RFC 7350 - DTLS as Transport for STUN
* Symmetric RTP
* draft-ietf-bfcpbis-rfc4582bis-08


Supported platforms:

* Linux
* FreeBSD
* OpenBSD
* NetBSD
* Symbian OS
* Solaris
* Windows
* Apple Mac OS X and iOS
* Android


Supported compilers:

* gcc (v2.9x to v4.x)
* gcce
* ms vc2003 compiler
* clang


Feedback:

- Please send feedback to <libre [at] creytiv.com>


Coding guidelines:

* Use enum for constants where appropriate
* Use const as much as possible (where appropriate)
* Use C99 data types (intN_t, uintN_t, bool)
* Hide data-types in .c files where possible (use struct foo)
* Avoid malloc/free, use mem_alloc/mem_deref instead
* CVS/svn/git tags are NOT allowed in the code!
* Avoid bit-fields in structs which are not portable
* Use dummy handlers for timing-critical callbacks
* return err, return alloced objects as pointer-pointers
* in allocating functions, first arg is always double pointer
* Use POSIX error-codes; EINVAL for invalid args, EBADMSG for
  parse errors and EPROTO for protocol errors


Transport protocols:


           TCP   UDP   TLS   DTLS
           ~~~   ~~~   ~~~   ~~~~

BFCP       -     yes   -     -

DNS        yes   yes   -     -

HTTP       yes   n/a   yes   n/a

ICE        -     yes   -     -

RTP        -     yes   -     -

RTCP       -     yes   -     -

SIP        yes   yes   yes   -

STUN       yes   yes   yes   yes

TURN       yes   yes   yes   yes

WEBSOCK    yes   n/a   yes   n/a