1 /*
2  * server.h -- thrulay library, server API.
3  *
4  * Written by Stanislav Shalunov, http://www.internet2.edu/~shalunov/
5  *            Bernhard Lutzmann, belu@users.sf.net
6  *            Federico Montesino Pouzols, fedemp@altern.org
7  *
8  * @(#) $Id: server.h,v 1.1.2.9 2006/08/20 18:06:19 fedemp Exp $
9  *
10  * Copyright 2003, 2006, Internet2.
11  * Legal conditions are in file LICENSE
12  * (MD5 = ecfa50d1b0bfbb81b658c810d0476a52).
13  */
14 
15 /**
16  * @file server.h
17  * @ingroup server
18  * @short thrulay server API.
19  **/
20 
21 #ifndef THRULAY_SERVER_H_INCLUDED
22 #define THRULAY_SERVER_H_INCLUDED
23 
24 /**
25  * @defgroup server thrulay server library
26  *
27  * @{
28  **/
29 
30 #include <stdint.h>
31 
32 #define THRULAY_VERSION		"thrulay/2"
33 #define THRULAY_DEFAULT_WINDOW  4194304
34 #define THRULAY_DEFAULT_SERVER_TCP_PORT		5003
35 
36 /**
37  * Logging alternatives
38  **/
39 typedef enum {
40 	LOGTYPE_SYSLOG,
41 	LOGTYPE_STDERR
42 } thrulay_server_logtype_t;
43 
44 /**
45  * Initialize thrulay server.
46  *
47  * @param log_type Where to output logs to.
48  * @param reporting_verbosity Verbosity of metrics reports.
49  *
50  * @return Return code.
51  * @retval 0 On success.
52  * @retval <0 If an error occurred (use thrulay_server_strerror to get
53  * a description).
54  **/
55 int
56 thrulay_server_init(thrulay_server_logtype_t log_type, int reporting_verbosity);
57 
58 /**
59  * Put the thrulay server to listen on a port.
60  *
61  * @param port TCP port to listen for incoming thrulay clients.
62  * @param window Server window size. The THRULAY_DEFAULT_WINDOW value can be
63  * used.
64  *
65  * @return Return code.
66  * @retval 0 On success.
67  * @retval <0 If an error occurred (use thrulay_server_strerror to get
68  * a description).
69  **/
70 int
71 thrulay_server_listen(int port, int window);
72 
73 /**
74  * Run main service loop for incoming clients. This is intended as a
75  * high level function that will serve as many clients as
76  * specified. For each client, a fork() is done and the children runs
77  * thrulay_server_process_client().
78  *
79  * thrulay_server_start(0, NULL) will take care of clients forever.
80  *
81  * @param max_clients number of clients to serve. After max_clients
82  * have been accepted, the server will stop.
83  * @param mcast_address address of a multicast group to join to.
84  *
85  *
86  * @return Return code.
87  * @retval 0 On success.
88  * @retval <0 If an error occurred (use thrulay_server_strerror to get
89  * a description).
90  **/
91 int
92 thrulay_server_start(uint32_t max_clients, const char *const mcast_address);
93 
94 /**
95  * Process a thrulay connection accepted on socket fd. This is a lower
96  * level function that attends a single thrulay client request on
97  * socket fd.
98  *
99  * @param fd socket where the connection has been accepted.
100  *
101  * @return Return code.
102  * @retval 0 On success.
103  * @retval <0 If an error occurred (use thrulay_server_strerror to get
104  * a description).
105  **/
106 int
107 thrulay_server_process_client(int fd);
108 
109 /**
110  * Add an address to the list of allowed hosts.
111  *
112  * @param address Network address to add.
113  *
114  * @return Return code.
115  * @retval 0 On success.
116  * @retval <0 If an error occurred (use thrulay_server_strerror to get
117  * a description).
118  **/
119 int
120 acl_allow_add (const char *const address);
121 
122 /**
123  * Get a description of an error code returned by any of the thrulay
124  * server functions.
125  *
126  * @return Description of last error in the thrulay server.
127  * @retval NULL if an error occurrs, the error is unknown or a wrong
128  * error code is given.
129  **/
130 const char *
131 thrulay_server_strerror(int errorcode);
132 
133 /** @} */
134 
135 #endif /* #ifndef THRULAY_SERVER_H_INCLUDED */
136