Version 0.1.10 from FTP
[asterisk/asterisk.git] / include / asterisk / io.h
1 /*
2  * Asterisk
3  * 
4  * Mark Spencer <markster@marko.net>
5  *
6  * Copyright(C) Mark Spencer
7  * 
8  * Distributed under the terms of the GNU General Public License (GPL) Version 2
9  *
10  * I/O Managment (derived from Cheops-NG)
11  *
12  */
13
14 #ifndef _IO_H
15 #define _IO_H
16
17 #include <sys/poll.h>           /* For POLL* constants */
18
19 #if defined(__cplusplus) || defined(c_plusplus)
20 extern "C" {
21 #endif
22
23 /*! Input ready */
24 #define AST_IO_IN       POLLIN
25 /*! Output ready */
26 #define AST_IO_OUT      POLLOUT
27 /*! Priority input ready */
28 #define AST_IO_PRI      POLLPRI
29
30 /* Implicitly polled for */
31 /*! Error condition (errno or getsockopt) */
32 #define AST_IO_ERR      POLLERR
33 /*! Hangup */
34 #define AST_IO_HUP      POLLHUP
35 /*! Invalid fd */
36 #define AST_IO_NVAL     POLLNVAL
37
38 /*
39  * An Asterisk IO callback takes its id, a file descriptor, list of events, and
40  * callback data as arguments and returns 0 if it should not be
41  * run again, or non-zero if it should be run again.
42  */
43
44 struct io_context;
45
46 //! Creates a context
47 /*!
48  * Create a context for I/O operations
49  * Basically mallocs an IO structure and sets up some default values.
50  * Returns an allocated io_context structure
51  */
52 extern struct io_context *io_context_create(void);
53
54 //! Destroys a context
55 /*
56  * \param ioc structure to destroy
57  * Destroy a context for I/O operations
58  * Frees all memory associated with the given io_context structure along with the structure itself
59  */
60 extern void io_context_destroy(struct io_context *ioc);
61
62 typedef int (*ast_io_cb)(int *id, int fd, short events, void *cbdata);
63 #define AST_IO_CB(a) ((ast_io_cb)(a))
64
65 //! Adds an IO context
66 /*! 
67  * \param ioc which context to use
68  * \param fd which fd to monitor
69  * \param callback callback function to run
70  * \param events event mask of events to wait for
71  * \param data data to pass to the callback
72  * Watch for any of revents activites on fd, calling callback with data as 
73  * callback data.  Returns a pointer to ID of the IO event, or NULL on failure.
74  */
75 extern int *ast_io_add(struct io_context *ioc, int fd, ast_io_cb callback, short events, void *data);
76
77 //! Changes an IO handler
78 /*!
79  * \param ioc which context to use
80  * \param id
81  * \param fd the fd you wish it to contain now
82  * \param callback new callback function
83  * \param events event mask to wait for
84  * \param data data to pass to the callback function
85  * Change an i/o handler, updating fd if > -1, callback if non-null, and revents
86  * if >-1, and data if non-null.  Returns a pointero to the ID of the IO event,
87  * or NULL on failure.
88  */
89 extern int *ast_io_change(struct io_context *ioc, int *id, int fd, ast_io_cb callback, short events, void *data);
90
91 //! Removes an IO context
92 /*! 
93  * \param ioc which io_context to remove it from
94  * \param id which ID to remove
95  * Remove an I/O id from consideration  Returns 0 on success or -1 on failure.
96  */
97 extern int ast_io_remove(struct io_context *ioc, int *id);
98
99 //! Waits for IO
100 /*!
101  * \param ioc which context to act upon
102  * \param howlong how many milliseconds to wait
103  * Wait for I/O to happen, returning after
104  * howlong milliseconds, and after processing
105  * any necessary I/O.  Returns the number of
106  * I/O events which took place.
107  */
108 extern int ast_io_wait(struct io_context *ioc, int howlong);
109
110 //! Dumps the IO array
111 /*
112  * Debugging: Dump everything in the I/O array
113  */
114 extern void ast_io_dump(struct io_context *ioc);
115
116 //! Set fd into non-echoing mode (if fd is a tty)
117
118 extern int ast_hide_password(int fd);
119
120 //! Restores TTY mode
121 /*
122  * Call with result from previous ast_hide_password
123  */
124 extern int ast_restore_tty(int fd, int oldstatus);
125
126 #if defined(__cplusplus) || defined(c_plusplus)
127 }
128 #endif
129
130
131 #endif