football
socket abstraction layer
fb_public.h
Go to the documentation of this file.
1 
9 #pragma once
10 
11 #include <config.h>
12 
13 #include <stdarg.h>
14 #include <stdbool.h>
15 #include "stdarg.h"
16 #include <sys/types.h>
17 #include <netinet/in.h>
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
27 typedef enum fb_event_type_t {
40 
42 typedef struct fb_event_t {
43  int magic; /* Enums and ints are same thing, right? :( TODO: Fix this. */
44  FB_EVENTTYPE type;
45  int socket;
46  void *context;
49  char *command;
50  int argc;
51  char **argv;
53  char **param_names;
54  char **param_values;
56 
66 
69  FB_INTERNATIONALIZATION_NONE,
73 
75 typedef struct fb_service_options_t {
76  int line_port;
77  int http_port;
78  int https_port;
79  int queue_size;
80  size_t context_size;
81  char *greeting;
83  char *name;
86  time_t websocket_ping_interval;
89  bool transfer_only;
90  struct fb_service_t *parent;
92 
93 typedef struct fb_service_t FB_SERVICE;
94 typedef struct fb_connection_t FB_CONNECTION;
95 typedef struct fb_iterator_t FB_ITERATOR;
96 
97 #ifdef NDEBUG
98 typedef void (* FB_LOGGING_FUNCTION)(int level, const char *format, ...);
99 #else
100 typedef void (* FB_LOGGING_FUNCTION)(const char *file, int line, const char *func, int level, const char *format, ...);
101 #endif
102 extern void fb_set_logging (int logtype, FB_LOGGING_FUNCTION func);
103 extern FB_LOGGING_FUNCTION fb_log;
104 
105 /* Useful utility functions available */
106 extern bool fb_expandcalloc (void **data, size_t *count, size_t newcount, size_t itemsize);
107 
108 /* "Legitimate", i.e. published API, subroutines */
109 extern FB_EVENT *fb_wait (void);
110 extern FB_EVENT *fb_poll (void);
111 extern FB_EVENT *fb_poll_until (time_t untilwhen);
112 extern FB_EVENT *fb_poll_with_timeout (double timeout);
113 extern void fb_interrupt (void);
114 
115 extern FB_SERVICE *fb_create_service (const FB_SERVICE_OPTIONS *options);
116 extern bool fb_transfer (FB_CONNECTION *connection, FB_SERVICE *service);
117 extern bool fb_services_are_open (void);
118 extern void fb_close_service (FB_SERVICE *service);
119 extern bool fb_init_tls_support (const char *path);
120  extern void fb_cleanup_tls_support (void);
121 
122 extern FB_EVENT *fb_accept_file (FB_SERVICE *service, char *filename);
123 extern FB_EVENT *fb_loopback_socket (FB_SERVICE *service);
124 extern void fb_close_connection (FB_CONNECTION *connection);
125 extern ssize_t fb_fprint (void *thing, const char *bytes, ssize_t length);
126 extern ssize_t fb_fprintf (void *thing, const char *format, ...);
127 extern ssize_t fb_vfprintf (void *thing, const char *format, va_list parameters);
128 extern ssize_t fb_bfprintf (void *thing, const char *format, ...);
129 extern ssize_t fb_bvfprintf (void *thing, const char *format, va_list parameters);
130 extern ssize_t fb_cbfprintf (void *thing, bool (*callback) (FB_CONNECTION *), const char *format, ...);
131 extern ssize_t fb_cbvfprintf (void *thing, bool (*callback) (FB_CONNECTION *), const char *format, va_list parameters);
132 
133 extern FB_ITERATOR *fb_new_iterator (FB_SERVICE *service);
134 extern FB_EVENT *fb_iterate_next (struct fb_iterator_t *it);
135 extern void fb_destroy_iterator (FB_ITERATOR *it);
136 extern void fb_accept_input (FB_CONNECTION *connection, bool input);
137 
138 #ifdef __cplusplus
139 }
140 #endif
141 
142 
ssize_t fb_cbfprintf(void *thing, bool(*callback)(FB_CONNECTION *), const char *format,...)
Definition: fb_event.c:222
FB_EVENT * fb_iterate_next(struct fb_iterator_t *it)
Get the next iteration.
Definition: fb_service.c:690
FB_EVENT * fb_poll(void)
Quick poll with no waiting.
Definition: fb_socketmgr.c:672
ssize_t fb_bvfprintf(void *thing, const char *format, va_list parameters)
Definition: fb_event.c:216
FB_ITERATOR * fb_new_iterator(FB_SERVICE *service)
Create a new iterator.
Definition: fb_service.c:672
fb_internationalizaton_mode_t
Internationalization mode– how to mangle filenames for language-specific files.
Definition: fb_public.h:68
@ FB_INTERNATIONALIZATION_EXTENSION
Do not look for language-specific files.
Definition: fb_public.h:70
@ FB_INTERNATIONALIZATION_DIRECTORY
Insert /<lang>/ after service path.
Definition: fb_public.h:71
struct fb_event_t FB_EVENT
Events are returned in this structure.
ssize_t fb_fprint(void *thing, const char *bytes, ssize_t length)
Adds an unformatted message to the output queue.
Definition: fb_event.c:164
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...
enum fb_internationalizaton_mode_t FB_I18N_MODE
Internationalization mode– how to mangle filenames for language-specific files.
struct fb_service_options_t FB_SERVICE_OPTIONS
Service options are passed to a new service, defining its behavior.
fb_service_greeting_mode_t
Greeting mode allows a service to require, accept, or not use greetings to trigger a line session via...
Definition: fb_public.h:60
@ FB_GREETING_REQUIRE
Both line and HTTP sessions wait for HELO.
Definition: fb_public.h:64
@ FB_GREETING_FALLBACK
Like Allow, but unrecognized HTTP request triggers line session.
Definition: fb_public.h:63
@ FB_GREETING_OFF
Immediately start line session, error on HELO.
Definition: fb_public.h:61
@ FB_GREETING_ALLOW
Immediately start line session but ignore HELO; accept on HTTP and start line session.
Definition: fb_public.h:62
ssize_t fb_vfprintf(void *thing, const char *format, va_list parameters)
Definition: fb_event.c:201
FB_EVENT * fb_accept_file(FB_SERVICE *service, char *filename)
Make a connection that reads from a file.
Definition: fb_service.c:576
void fb_close_connection(FB_CONNECTION *connection)
Initiate connection closure.
Definition: fb_service.c:557
ssize_t fb_fprintf(void *thing, const char *format,...)
Add messages to output queues in various forms and styles.
Definition: fb_event.c:192
FB_EVENT * fb_poll_with_timeout(double timeout)
Poll with a duration.
Definition: fb_socketmgr.c:681
FB_EVENT * fb_wait(void)
Poll indefinitely.
Definition: fb_socketmgr.c:689
fb_event_type_t
Event types returned from the socket manager.
Definition: fb_public.h:27
@ FB_EVENT_ITERATOR
Iterator response: Connection is open.
Definition: fb_public.h:32
@ FB_EVENT_FAULTING
User thingies only: Socket has an error pending.
Definition: fb_public.h:36
@ FB_EVENT_INPUT
Connection: Input from a line or websocket session.
Definition: fb_public.h:29
@ FB_EVENT_WRITABLE
User thingies only: Socket is write-ready.
Definition: fb_public.h:34
@ FB_EVENT_STOPPED
Service: No remaining connections, service is terminating.
Definition: fb_public.h:31
@ FB_EVENT_CLOSE
Connection: Connection is closing.
Definition: fb_public.h:30
@ FB_EVENT_TIMEOUT
The poll timeout expired.
Definition: fb_public.h:37
@ FB_EVENT_INTERRUPT
A signal interrupted while waiting.
Definition: fb_public.h:38
@ FB_EVENT_READABLE
User thingies only: Socket is read-ready.
Definition: fb_public.h:35
@ FB_EVENT_ITERATOR_CLOSE
Iterator response: Connection is closing.
Definition: fb_public.h:33
@ FB_EVENT_CONNECT
Connection: A line or websocket session is beginning.
Definition: fb_public.h:28
FB_EVENT * fb_loopback_socket(FB_SERVICE *service)
Make a connection with a pipe.
Definition: fb_service.c:625
FB_EVENT * fb_poll_until(time_t untilwhen)
Poll with a timeout at a specific time.
Definition: fb_socketmgr.c:695
void fb_accept_input(FB_CONNECTION *connection, bool input)
Public interface to enable/disable reading on a connection.
Definition: fb_socketmgr.c:305
enum fb_event_type_t FB_EVENTTYPE
Event types returned from the socket manager.
bool fb_transfer(FB_CONNECTION *connection, FB_SERVICE *service)
Transfer a connection to a new service.
Definition: fb_service.c:464
ssize_t fb_cbvfprintf(void *thing, bool(*callback)(FB_CONNECTION *), const char *format, va_list parameters)
Definition: fb_event.c:231
void fb_destroy_iterator(FB_ITERATOR *it)
Destroy an iterator and release its resources.
Definition: fb_service.c:715
bool fb_services_are_open(void)
Indicate whether there are any services open.
Definition: fb_service.c:47
ssize_t fb_bfprintf(void *thing, const char *format,...)
Definition: fb_event.c:207
bool fb_expandcalloc(void **data, size_t *count, size_t newcount, size_t itemsize)
calloc() with ability to expand the allocated data.
Definition: fb_utility.c:127
void fb_close_service(FB_SERVICE *service)
Initiate closure of a service.
Definition: fb_service.c:292
void fb_interrupt(void)
Return an FB_EVENT_INTERRUPTED on current or next poll.
Definition: fb_socketmgr.c:117
void fb_set_logging(int logtype, FB_LOGGING_FUNCTION func)
Set logging level.
Definition: fb_utility.c:36
FB_SERVICE * fb_create_service(const FB_SERVICE_OPTIONS *options)
Create a new service and initialize its listeners.
Definition: fb_service.c:151
Connection state information.
Definition: fb_service.h:199
Events are returned in this structure.
Definition: fb_public.h:42
char ** param_names
Parameter names (for HTTP query parameters)
Definition: fb_public.h:53
int socket
The socket creating an event, for user thingies only.
Definition: fb_public.h:45
char * command
A command received on a connection, raw form.
Definition: fb_public.h:49
struct fb_service_t * service
All connection events and service closed.
Definition: fb_public.h:48
struct fb_connection_t * connection
For connect, close, and input.
Definition: fb_public.h:47
int argc
The number of terms in argv.
Definition: fb_public.h:50
int param_count
Number of entries in param_names & param_values.
Definition: fb_public.h:52
char ** argv
Lexically split command received on a connection.
Definition: fb_public.h:51
void * context
Provided for connections, or if supplied for user thingies.
Definition: fb_public.h:46
char ** param_values
Values corresponding to param_names positions (for HTTP query parameters).
Definition: fb_public.h:54
int magic
Private.
Definition: fb_public.h:43
Iterator for connections on a football service.
Definition: fb_service.h:233
Service options are passed to a new service, defining its behavior.
Definition: fb_public.h:75
int greeting_timeout
Limit greeting and/or TLS negotiation, 0 to disable.
Definition: fb_public.h:82
size_t context_size
Size of user context allocated for new connections.
Definition: fb_public.h:80
int http_port
HTTP (or combo depending on service mode) port, or 0 to disable.
Definition: fb_public.h:77
char * greeting
Default HELO.
Definition: fb_public.h:81
char * locale_directory
Subdirectory with internationalization files for HTTP.
Definition: fb_public.h:85
int line_port
Line-oriented port, or 0 to disable.
Definition: fb_public.h:76
char * serve_directory
Location of files to be served by HTTP.
Definition: fb_public.h:84
int https_port
HTTP Secure port, or combo, or 0 to disable.
Definition: fb_public.h:78
char * name
Name of service, for URL processing and hosts_access lookups.
Definition: fb_public.h:83
struct fb_service_t * parent
Service will accept transfers; no ports required.
Definition: fb_public.h:90
FB_GREETING_MODE greeting_mode
Whether to accept/require greeting.
Definition: fb_public.h:88
int queue_size
Listen queue size before connections are rejected.
Definition: fb_public.h:79
FB_I18N_MODE internationalization
How often to send a ping on websocket; 0 = never.
Definition: fb_public.h:87
Football service state structure.
Definition: fb_service.h:128