Asterisk - The Open Source Telephony Project  GIT-master-a24979a
io.h
Go to the documentation of this file.
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 #include "asterisk/poll-compat.h"
27 #include "asterisk/netsock2.h"
28 
29 #if defined(__cplusplus) || defined(c_plusplus)
30 extern "C" {
31 #endif
32 
33 /*! Input ready */
34 #define AST_IO_IN POLLIN
35 /*! Output ready */
36 #define AST_IO_OUT POLLOUT
37 /*! Priority input ready */
38 #define AST_IO_PRI POLLPRI
39 
40 /* Implicitly polled for */
41 /*! Error condition (errno or getsockopt) */
42 #define AST_IO_ERR POLLERR
43 /*! Hangup */
44 #define AST_IO_HUP POLLHUP
45 /*! Invalid fd */
46 #define AST_IO_NVAL POLLNVAL
47 
48 /*! \brief
49  * An Asterisk IO callback takes its id, a file descriptor, list of events, and
50  * callback data as arguments and returns 0 if it should not be
51  * run again, or non-zero if it should be run again.
52  */
53 
54 struct io_context;
55 
56 /*!
57  * \brief Creates a context
58  * Create a context for I/O operations
59  * Basically mallocs an IO structure and sets up some default values.
60  * \return an allocated io_context structure
61  */
62 struct io_context *io_context_create(void);
63 
64 /*!
65  * \brief Destroys a context
66  * \param ioc structure to destroy
67  * Destroy a context for I/O operations
68  * Frees all memory associated with the given io_context structure along with the structure itself
69  */
70 void io_context_destroy(struct io_context *ioc);
71 
72 typedef int (*ast_io_cb)(int *id, int fd, short events, void *cbdata);
73 #define AST_IO_CB(a) ((ast_io_cb)(a))
74 
75 /*!
76  * \brief Adds an IO context
77  * \param ioc which context to use
78  * \param fd which fd to monitor
79  * \param callback callback function to run
80  * \param events event mask of events to wait for
81  * \param data data to pass to the callback
82  * Watch for any of revents activities on fd, calling callback with data as
83  * callback data.
84  * \return a pointer to ID of the IO event
85  * \retval NULL on failure
86  */
87 int *ast_io_add(struct io_context *ioc, int fd, ast_io_cb callback, short events, void *data);
88 
89 /*!
90  * \brief Changes an IO handler
91  * \param ioc which context to use
92  * \param id
93  * \param fd the fd you wish it to contain now
94  * \param callback new callback function
95  * \param events event mask to wait for
96  * \param data data to pass to the callback function
97  * Change an I/O handler, updating fd if > -1, callback if non-null,
98  * and revents if > -1, and data if non-null.
99  * \return a pointer to the ID of the IO event
100  * \retval NULL on failure
101  */
102 int *ast_io_change(struct io_context *ioc, int *id, int fd, ast_io_cb callback, short events, void *data);
103 
104 /*!
105  * \brief Removes an IO context
106  * \param ioc which io_context to remove it from
107  * \param id which ID to remove
108  * Remove an I/O id from consideration
109  * \retval 0 on success
110  * \retval -1 on failure
111  */
112 int ast_io_remove(struct io_context *ioc, int *id);
113 
114 /*!
115  * \brief Waits for IO
116  * \param ioc which context to act upon
117  * \param howlong how many milliseconds to wait
118  * Wait for I/O to happen, returning after
119  * howlong milliseconds, and after processing
120  * any necessary I/O.
121  * \return the number of I/O events which took place.
122  */
123 int ast_io_wait(struct io_context *ioc, int howlong);
124 
125 /*!
126  * \brief Dumps the IO array.
127  * \param ioc
128  * Debugging: Dump everything in the I/O array
129  */
130 void ast_io_dump(struct io_context *ioc);
131 
132 /*!
133  * \brief Hide password.
134  * \param fd
135  * Set fd into non-echoing mode (if fd is a tty)
136  */
137 int ast_hide_password(int fd);
138 
139 /*!
140  * \brief Restores TTY mode.
141  * \param fd, oldstatus
142  * Call with result from previous \ref ast_hide_password
143  */
144 int ast_restore_tty(int fd, int oldstatus);
145 
146 /*!
147  * \brief Columns of Terminal.
148  * \param fd
149  * Falls back to 80 if the underlying ioctl fails.
150  */
151 int ast_get_termcols(int fd);
152 
153 /*!
154  * \brief a wrapper for sd_notify(): notify systemd of any state changes.
155  * \param state a string that states the changes. See sd_notify(3).
156  * The wrapper does nothing if systemd ('s development headers) was not
157  * detected on the system.
158  * \retval 0 on success.
159  * \retval positie on success.
160  * \retval negative on error.
161  */
162 int ast_sd_notify(const char *state);
163 
164 /*!
165  * \brief Find a listening file descriptor provided by socket activation.
166  * \param type SOCK_STREAM or SOCK_DGRAM
167  * \param addr The socket address of the bound listener.
168  * \retval negative No match.
169  * \retval positive File Descriptor matching sockaddr.
170  *
171  * \note This function returns -1 if systemd's development headers were not
172  * detected on the system.
173  */
174 int ast_sd_get_fd(int type, const struct ast_sockaddr *addr);
175 
176 /*!
177  * \brief Find a listening AF_LOCAL file descriptor provided by socket activation.
178  * \param type SOCK_STREAM or SOCK_DGRAM
179  * \param path The path of the listener.
180  * \retval negative No match.
181  * \retval positive File Descriptor matching path.
182  *
183  * \note This function returns -1 if systemd's development headers were not
184  * detected on the system.
185  */
186 int ast_sd_get_fd_un(int type, const char *path);
187 
188 #if defined(__cplusplus) || defined(c_plusplus)
189 }
190 #endif
191 
192 #endif /* _ASTERISK_IO_H */
static const struct adsi_event events[]
Definition: app_adsiprog.c:85
enum queue_result id
Definition: app_queue.c:1640
static const char type[]
Definition: chan_ooh323.c:109
int ast_hide_password(int fd)
Hide password.
Definition: io.c:337
void io_context_destroy(struct io_context *ioc)
Destroys a context.
Definition: io.c:107
int ast_io_wait(struct io_context *ioc, int howlong)
Waits for IO.
Definition: io.c:278
int * ast_io_change(struct io_context *ioc, int *id, int fd, ast_io_cb callback, short events, void *data)
Changes an IO handler.
Definition: io.c:200
struct io_context * io_context_create(void)
Creates a context Create a context for I/O operations Basically mallocs an IO structure and sets up s...
Definition: io.c:81
int ast_sd_get_fd(int type, const struct ast_sockaddr *addr)
Find a listening file descriptor provided by socket activation.
Definition: io.c:438
int ast_get_termcols(int fd)
Columns of Terminal.
Definition: io.c:373
int * ast_io_add(struct io_context *ioc, int fd, ast_io_cb callback, short events, void *data)
Adds an IO context.
Definition: io.c:162
int ast_restore_tty(int fd, int oldstatus)
Restores TTY mode.
Definition: io.c:356
int ast_sd_notify(const char *state)
a wrapper for sd_notify(): notify systemd of any state changes.
Definition: io.c:392
void ast_io_dump(struct io_context *ioc)
Dumps the IO array.
Definition: io.c:312
int ast_sd_get_fd_un(int type, const char *path)
Find a listening AF_LOCAL file descriptor provided by socket activation.
Definition: io.c:454
int(* ast_io_cb)(int *id, int fd, short events, void *cbdata)
Definition: io.h:72
int ast_io_remove(struct io_context *ioc, int *id)
Removes an IO context.
Definition: io.c:245
Network socket handling.
Socket address structure.
Definition: netsock2.h:97
Global IO variables are now in a struct in order to be made threadsafe.
Definition: io.c:71