Asterisk - The Open Source Telephony Project GIT-master-7921072
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
27#include "asterisk/netsock2.h"
28
29#if defined(__cplusplus) || defined(c_plusplus)
30extern "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
54struct 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 */
62struct 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 */
70void io_context_destroy(struct io_context *ioc);
71
72typedef 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 */
87int *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 */
102int *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 */
112int 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 */
123int 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 */
130void 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 */
137int 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 */
144int 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 */
151int 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 */
162int 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 */
174int 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 */
186int 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:1638
static const char type[]
Definition: chan_ooh323.c:109
int ast_hide_password(int fd)
Hide password.
Definition: io.c:337
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_io_add(struct io_context *ioc, int fd, ast_io_cb callback, short events, void *data)
Adds an IO context.
Definition: io.c:162
void io_context_destroy(struct io_context *ioc)
Destroys a context.
Definition: io.c:107
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
int ast_io_wait(struct io_context *ioc, int howlong)
Waits for IO.
Definition: io.c:278
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_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