Standardized routines for forking processes (keeps all the specialized code in one...
[asterisk/asterisk.git] / include / asterisk / io.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief I/O Management (derived from Cheops-NG)
21  */
22
23 #ifndef _ASTERISK_IO_H
24 #define _ASTERISK_IO_H
25
26 #ifdef HAVE_SYS_POLL_H
27 #include <sys/poll.h>           /* For POLL* constants */
28 #else
29 #include "asterisk/poll-compat.h"
30 #endif
31
32 #if defined(__cplusplus) || defined(c_plusplus)
33 extern "C" {
34 #endif
35
36 /*! Input ready */
37 #define AST_IO_IN       POLLIN
38 /*! Output ready */
39 #define AST_IO_OUT      POLLOUT
40 /*! Priority input ready */
41 #define AST_IO_PRI      POLLPRI
42
43 /* Implicitly polled for */
44 /*! Error condition (errno or getsockopt) */
45 #define AST_IO_ERR      POLLERR
46 /*! Hangup */
47 #define AST_IO_HUP      POLLHUP
48 /*! Invalid fd */
49 #define AST_IO_NVAL     POLLNVAL
50
51 /*! \brief
52  * An Asterisk IO callback takes its id, a file descriptor, list of events, and
53  * callback data as arguments and returns 0 if it should not be
54  * run again, or non-zero if it should be run again.
55  */
56
57 struct io_context;
58
59 /*! 
60  * \brief Creates a context 
61  * Create a context for I/O operations
62  * Basically mallocs an IO structure and sets up some default values.
63  * \return an allocated io_context structure
64  */
65 struct io_context *io_context_create(void);
66
67 /*! 
68  * \brief Destroys a context 
69  * \param ioc structure to destroy
70  * Destroy a context for I/O operations
71  * Frees all memory associated with the given io_context structure along with the structure itself
72  */
73 void io_context_destroy(struct io_context *ioc);
74
75 typedef int (*ast_io_cb)(int *id, int fd, short events, void *cbdata);
76 #define AST_IO_CB(a) ((ast_io_cb)(a))
77
78 /*! 
79  * \brief Adds an IO context 
80  * \param ioc which context to use
81  * \param fd which fd to monitor
82  * \param callback callback function to run
83  * \param events event mask of events to wait for
84  * \param data data to pass to the callback
85  * Watch for any of revents activites on fd, calling callback with data as
86  * callback data.  
87  * \retval a pointer to ID of the IO event
88  * \retval NULL on failure
89  */
90 int *ast_io_add(struct io_context *ioc, int fd, ast_io_cb callback, short events, void *data);
91
92 /*! 
93  * \brief Changes an IO handler 
94  * \param ioc which context to use
95  * \param id
96  * \param fd the fd you wish it to contain now
97  * \param callback new callback function
98  * \param events event mask to wait for
99  * \param data data to pass to the callback function
100  * Change an I/O handler, updating fd if > -1, callback if non-null, 
101  * and revents if >-1, and data if non-null.
102  * \retval a pointer to the ID of the IO event
103  * \retval NULL on failure
104  */
105 int *ast_io_change(struct io_context *ioc, int *id, int fd, ast_io_cb callback, short events, void *data);
106
107 /*! 
108  * \brief Removes an IO context 
109  * \param ioc which io_context to remove it from
110  * \param id which ID to remove
111  * Remove an I/O id from consideration  
112  * \retval 0 on success
113  * \retval -1 on failure
114  */
115 int ast_io_remove(struct io_context *ioc, int *id);
116
117 /*! 
118  * \brief Waits for IO 
119  * \param ioc which context to act upon
120  * \param howlong how many milliseconds to wait
121  * Wait for I/O to happen, returning after
122  * howlong milliseconds, and after processing
123  * any necessary I/O.  
124  * \return he number of I/O events which took place.
125  */
126 int ast_io_wait(struct io_context *ioc, int howlong);
127
128 /*! 
129  * \brief Dumps the IO array.
130  * Debugging: Dump everything in the I/O array
131  */
132 void ast_io_dump(struct io_context *ioc);
133
134 /*! Set fd into non-echoing mode (if fd is a tty) */
135
136 int ast_hide_password(int fd);
137
138 /*! 
139  * \brief Restores TTY mode.
140  * Call with result from previous ast_hide_password
141  */
142 int ast_restore_tty(int fd, int oldstatus);
143
144 int ast_get_termcols(int fd);
145
146 #if defined(__cplusplus) || defined(c_plusplus)
147 }
148 #endif
149
150 #endif /* _ASTERISK_IO_H */