#include <config.h>
#include <stdarg.h>
#include <stdbool.h>
#include <sys/types.h>
#include <netinet/in.h>

Data Structures
struct	fb_event_t
	Events are returned in this structure. More...

struct	fb_service_options_t
	Service options are passed to a new service, defining its behavior. More...

Typedefs
typedef enum fb_event_type_t	FB_EVENTTYPE
	Event types returned from the socket manager.

typedef struct fb_event_t	FB_EVENT
	Events are returned in this structure.

typedef enum fb_service_greeting_mode_t	FB_GREETING_MODE
	Greeting mode allows a service to require, accept, or not use greetings to trigger a line session via the HTTP or TLS port.

typedef enum fb_internationalizaton_mode_t	FB_I18N_MODE
	Internationalization mode– how to mangle filenames for language-specific files.

typedef struct fb_service_options_t	FB_SERVICE_OPTIONS
	Service options are passed to a new service, defining its behavior.

typedef struct fb_service_t	FB_SERVICE

typedef struct fb_connection_t	FB_CONNECTION

typedef struct fb_iterator_t	FB_ITERATOR

typedef void(*	FB_LOGGING_FUNCTION) (const char file, int line, const char func, int level, const char *format,...)

Enumerations
enum	fb_event_type_t { FB_EVENT_CONNECT = 1 , FB_EVENT_INPUT , FB_EVENT_CLOSE , FB_EVENT_STOPPED , FB_EVENT_ITERATOR , FB_EVENT_ITERATOR_CLOSE , FB_EVENT_WRITABLE , FB_EVENT_READABLE , FB_EVENT_FAULTING , FB_EVENT_TIMEOUT , FB_EVENT_INTERRUPT }
	Event types returned from the socket manager. More...

enum	fb_service_greeting_mode_t { FB_GREETING_OFF , FB_GREETING_ALLOW , FB_GREETING_FALLBACK , FB_GREETING_REQUIRE }
	Greeting mode allows a service to require, accept, or not use greetings to trigger a line session via the HTTP or TLS port. More...

enum	fb_internationalizaton_mode_t { FB_INTERNATIONALIZATION_NONE , FB_INTERNATIONALIZATION_EXTENSION , FB_INTERNATIONALIZATION_DIRECTORY }
	Internationalization mode– how to mangle filenames for language-specific files. More...

Functions
void	fb_set_logging (int logtype, FB_LOGGING_FUNCTION func)
	Set logging level.

bool	fb_expandcalloc (void *data, size_t count, size_t newcount, size_t itemsize)
	calloc() with ability to expand the allocated data.

FB_EVENT *	fb_wait (void)
	Poll indefinitely.

FB_EVENT *	fb_poll (void)
	Quick poll with no waiting.

FB_EVENT *	fb_poll_until (time_t untilwhen)
	Poll with a timeout at a specific time.

FB_EVENT *	fb_poll_with_timeout (double timeout)
	Poll with a duration.

void	fb_interrupt (void)
	Return an FB_EVENT_INTERRUPTED on current or next poll.

FB_SERVICE *	fb_create_service (const FB_SERVICE_OPTIONS *options)
	Create a new service and initialize its listeners.

bool	fb_transfer (FB_CONNECTION connection, FB_SERVICE service)
	Transfer a connection to a new service.

bool	fb_services_are_open (void)
	Indicate whether there are any services open.

void	fb_close_service (FB_SERVICE *service)
	Initiate closure of a service.

bool	fb_init_tls_support (const char *path)

void	fb_cleanup_tls_support (void)

FB_EVENT *	fb_accept_file (FB_SERVICE service, char filename)
	Make a connection that reads from a file.

FB_EVENT *	fb_loopback_socket (FB_SERVICE *service)
	Make a connection with a pipe.

void	fb_close_connection (FB_CONNECTION *connection)
	Initiate connection closure.

ssize_t	fb_fprint (void thing, const char bytes, ssize_t length)
	Adds an unformatted message to the output queue.

ssize_t	fb_fprintf (void thing, const char format,...)
	Add messages to output queues in various forms and styles.

ssize_t	fb_vfprintf (void thing, const char format, va_list parameters)

ssize_t	fb_bfprintf (void thing, const char format,...)

ssize_t	fb_bvfprintf (void thing, const char format, va_list parameters)

ssize_t	fb_cbfprintf (void thing, bool(callback)(FB_CONNECTION ), const char format,...)

ssize_t	fb_cbvfprintf (void thing, bool(callback)(FB_CONNECTION ), const char format, va_list parameters)

FB_ITERATOR *	fb_new_iterator (FB_SERVICE *service)
	Create a new iterator.

FB_EVENT *	fb_iterate_next (struct fb_iterator_t *it)
	Get the next iteration.

void	fb_destroy_iterator (FB_ITERATOR *it)
	Destroy an iterator and release its resources.

void	fb_accept_input (FB_CONNECTION *connection, bool input)
	Public interface to enable/disable reading on a connection.

Variables
FB_LOGGING_FUNCTION	fb_log

Detailed Description

Football public declarations.

Football socket abstraction layer
Author
Perette Barella

Date
2012-03-03

Copyright
Copyright 2012-2021 Devious Fish. All rights reserved.

Typedef Documentation

◆ FB_EVENTTYPE

typedef enum fb_event_type_t FB_EVENTTYPE

Event types returned from the socket manager.

For FB_EVENT_CONNECT on HTTP or TLS ports, the event occurs when the session greets or begins a websocket session. Connections may silently exist in the socket manager before that.

◆ FB_GREETING_MODE

typedef enum fb_service_greeting_mode_t FB_GREETING_MODE

Greeting mode allows a service to require, accept, or not use greetings to trigger a line session via the HTTP or TLS port.

Greetings reduce port pollution, and encrypted line sessions are only supported via greeting.

Enumeration Type Documentation

◆ fb_event_type_t

enum fb_event_type_t

Event types returned from the socket manager.

For FB_EVENT_CONNECT on HTTP or TLS ports, the event occurs when the session greets or begins a websocket session. Connections may silently exist in the socket manager before that.

Enumerator
FB_EVENT_CONNECT	Connection: A line or websocket session is beginning.
FB_EVENT_INPUT	Connection: Input from a line or websocket session.
FB_EVENT_CLOSE	Connection: Connection is closing.
FB_EVENT_STOPPED	Service: No remaining connections, service is terminating.
FB_EVENT_ITERATOR	Iterator response: Connection is open.
FB_EVENT_ITERATOR_CLOSE	Iterator response: Connection is closing.
FB_EVENT_WRITABLE	User thingies only: Socket is write-ready.
FB_EVENT_READABLE	User thingies only: Socket is read-ready.
FB_EVENT_FAULTING	User thingies only: Socket has an error pending.
FB_EVENT_TIMEOUT	The poll timeout expired.
FB_EVENT_INTERRUPT	A signal interrupted while waiting.

◆ fb_internationalizaton_mode_t

enum fb_internationalizaton_mode_t

Internationalization mode– how to mangle filenames for language-specific files.

Enumerator

FB_INTERNATIONALIZATION_EXTENSION

Do not look for language-specific files.

Append .<lang> to filenames

FB_INTERNATIONALIZATION_DIRECTORY

Insert /<lang>/ after service path.

◆ fb_service_greeting_mode_t

enum fb_service_greeting_mode_t

Greeting mode allows a service to require, accept, or not use greetings to trigger a line session via the HTTP or TLS port.

Greetings reduce port pollution, and encrypted line sessions are only supported via greeting.

Enumerator
FB_GREETING_OFF	Immediately start line session, error on HELO. HELO not accepted on HTTP.
FB_GREETING_ALLOW	Immediately start line session but ignore HELO; accept on HTTP and start line session.
FB_GREETING_FALLBACK	Like Allow, but unrecognized HTTP request triggers line session.
FB_GREETING_REQUIRE	Both line and HTTP sessions wait for HELO. Require HELO to start line session

Function Documentation

◆ fb_accept_file()

FB_EVENT * fb_accept_file	(	FB_SERVICE *	service,
		char *	filename
	)

extern

Make a connection that reads from a file.

Parameters

service	the service to register the connection with
filename	the file to read from

Returns: a pointer to the connection, or NULL on failure.

◆ fb_accept_input()

void fb_accept_input	(	FB_CONNECTION *	connection,
		bool	input
	)

extern

Public interface to enable/disable reading on a connection.

Parameters

connection	- the connection to adjust.
input	true to enable reading, false to disable.

◆ fb_bfprintf()

ssize_t fb_bfprintf	(	void *	thing,
		const char *	format,
			...
	)

extern

See also: fb_fprintf

◆ fb_bvfprintf()

ssize_t fb_bvfprintf	(	void *	thing,
		const char *	format,
		va_list	parameters
	)

extern

See also: fb_fprintf

◆ fb_cbfprintf()

ssize_t fb_cbfprintf	(	void *	thing,
		bool()(FB_CONNECTION )	callback,
		const char *	format,
			...
	)

extern

See also: fb_fprintf

◆ fb_cbvfprintf()

ssize_t fb_cbvfprintf	(	void *	thing,
		bool()(FB_CONNECTION )	callback,
		const char *	format,
		va_list	parameters
	)

extern

See also: fb_fprintf

◆ fb_close_connection()

void fb_close_connection ( FB_CONNECTION * connection )

extern

Initiate connection closure.

If the socket is in an open state, change its state and enable writes. The next write attempt will generate a close event. If the connection is already on its way out, leave it alone.

Parameters

connection the connection to close

◆ fb_close_service()

void fb_close_service ( FB_SERVICE * service )

extern

Initiate closure of a service.

Returns: Nothing.

◆ fb_create_service()

FB_SERVICE * fb_create_service ( const FB_SERVICE_OPTIONS * options )

extern

Create a new service and initialize its listeners.

Subsequent changes made to the options do not effect behavior.

Parameters

options Options for the new service's behavior.

Returns: a pointer to the service, or NULL on failure.

◆ fb_destroy_iterator()

void fb_destroy_iterator ( FB_ITERATOR * it )

extern

Destroy an iterator and release its resources.

Parameters

it	The iterator

◆ fb_expandcalloc()

bool fb_expandcalloc	(	void **	data,
		size_t *	capacity,
		size_t	newcapacity,
		size_t	itemsize
	)

extern

calloc() with ability to expand the allocated data.

Does nothing if the actual capacity meets or exceeds the requested capacity. When expansion occurs, the added elements are zeroed out.

Parameters

data	the allocation to expand. May be *NULL for initial allocation.
capacity	the capacity of the allocation, which may be adjusted by this call.
newcapacity	the desired capacity of the allocation.
itemsize	the size of data items in the allocation.

Returns: true on success, false on failure (existing allocation remains valid).

◆ fb_fprint()

ssize_t fb_fprint	(	void *	thing,
		const char *	bytes,
		ssize_t	length
	)

extern

Adds an unformatted message to the output queue.

Parameters

thing	the destined service, connection or event.
bytes	the bytes to transmit.
length	number of bytes in the message.

Returns: -1 on error, number of bytes written on success or partial success.

◆ fb_fprintf()

ssize_t fb_fprintf	(	void *	thing,
		const char *	format,
			...
	)

extern

Add messages to output queues in various forms and styles.

All forms take an opaque type and determine if it's a connection or service, so you can write code once and deal with both single and broadcast messages.

'b' variants broadcast, given either a connection or service. Services always broadcast, regardless of service.
'cb' variants broadcast only to those connections identified buy the supplied callback function returning true.
'v' accepts a pointer to the format arguments.
Parameters

thing the destined service, connection or event.

format a printf format string, with values to follow.

Returns
-1 on error, number of bytes written on success or partial success.

◆ fb_iterate_next()

FB_EVENT * fb_iterate_next ( FB_ITERATOR * it )

extern

Get the next iteration.

See also: FB_EVENTTYPE

Parameters

it	The iterator

Returns: An event, or NULL if there are no more connections.

◆ fb_loopback_socket()

FB_EVENT * fb_loopback_socket ( FB_SERVICE * service )

extern

Make a connection with a pipe.

Parameters

service the service to register the connection with

Returns: a pointer to the connection, or NULL on failure.

◆ fb_new_iterator()

FB_ITERATOR * fb_new_iterator ( FB_SERVICE * service )

extern

Create a new iterator.

Create and initialize a new iterator for a service.

See also: fb_destroy_iterator().

Returns: an iterator or NULL on error.

◆ fb_poll()

FB_EVENT * fb_poll ( void )

extern

Quick poll with no waiting.

Returns: An event.

◆ fb_poll_until()

FB_EVENT * fb_poll_until ( time_t untilwhen )

extern

Poll with a timeout at a specific time.

Parameters

untilwhen Time at which timeout should occur.

Returns: An event.

◆ fb_poll_with_timeout()

FB_EVENT * fb_poll_with_timeout ( double timeout )

extern

Poll with a duration.

Parameters

timeout in seconds.

Returns: An event.

◆ fb_services_are_open()

bool fb_services_are_open ( void )

extern

Indicate whether there are any services open.

Returns: true if services exist, false otherwise.

◆ fb_set_logging()

void fb_set_logging	(	int	logtype,
		FB_LOGGING_FUNCTION	func
	)

extern

Set logging level.

Set which messages will be collected by the internal logging function, or provide an alternate logging function. When using a private logging function, logtype is not used.

Parameters

logtype	a bitmask indicating which data to log.
func	a logging function that replaces the default one.

◆ fb_transfer()

bool fb_transfer	(	FB_CONNECTION *	connection,
		FB_SERVICE *	service
	)

extern

Transfer a connection to a new service.

Parameters

connection	The connection to transfer.
service	The service to reassign it to.

◆ fb_vfprintf()

ssize_t fb_vfprintf	(	void *	thing,
		const char *	format,
		va_list	parameters
	)

extern

See also: fb_fprintf

◆ fb_wait()

FB_EVENT * fb_wait ( void )

extern

Poll indefinitely.

Returns: An event.

thing	the destined service, connection or event.
format	a printf format string, with values to follow.

Data Structures

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ FB_EVENTTYPE

◆ FB_GREETING_MODE

Enumeration Type Documentation

◆ fb_event_type_t

◆ fb_internationalizaton_mode_t

◆ fb_service_greeting_mode_t

Function Documentation

◆ fb_accept_file()

◆ fb_accept_input()

◆ fb_bfprintf()

◆ fb_bvfprintf()

◆ fb_cbfprintf()

◆ fb_cbvfprintf()

◆ fb_close_connection()

◆ fb_close_service()

◆ fb_create_service()

◆ fb_destroy_iterator()

◆ fb_expandcalloc()

◆ fb_fprint()

◆ fb_fprintf()

◆ fb_iterate_next()

◆ fb_loopback_socket()

◆ fb_new_iterator()

◆ fb_poll()

◆ fb_poll_until()

◆ fb_poll_with_timeout()

◆ fb_services_are_open()

◆ fb_set_logging()

◆ fb_transfer()

◆ fb_vfprintf()

◆ fb_wait()