Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:54 2009

## Asterisk developer's documentation

# io.h

Go to the documentation of this file.

    00001 /*
    00002  * Asterisk -- An open source telephony toolkit.
    00003  *
    00004  * Copyright (C) 1999 - 2005, Digium, Inc.
    00005  *
    00006  * Mark Spencer <markster@digium.com>
    00007  *
    00008  * See http://www.asterisk.org for more information about
    00009  * the Asterisk project. Please do not directly contact
    00010  * any of the maintainers of this project for assistance;
    00011  * the project provides a web site, mailing lists and IRC
    00012  * channels for your use.
    00013  *
    00014  * This program is free software, distributed under the terms of
    00015  * the GNU General Public License Version 2. See the LICENSE file
    00016  * at the top of the source tree.
    00017  */
    00018
    00019 /*! \file
    00020  * \brief I/O Management (derived from Cheops-NG)
    00021  */
    00022
    00023 #ifndef _ASTERISK_IO_H
    00024 #define _ASTERISK_IO_H
    00025
    00026 #ifdef POLLCOMPAT
    00027 #include "asterisk/poll-compat.h"
    00028 #else
    00029 #include <sys/poll.h>      /* For POLL* constants */
    00030 #endif
    00031
    00032 #if defined(__cplusplus) || defined(c_plusplus)
    00033 extern "C" {
    00034 #endif
    00035
    00036 /*! Input ready */
    00037 #define AST_IO_IN    POLLIN
    00038 /*! Output ready */
    00039 #define AST_IO_OUT   POLLOUT
    00040 /*! Priority input ready */
    00041 #define AST_IO_PRI   POLLPRI
    00042
    00043 /* Implicitly polled for */
    00044 /*! Error condition (errno or getsockopt) */
    00045 #define AST_IO_ERR   POLLERR
    00046 /*! Hangup */
    00047 #define AST_IO_HUP   POLLHUP
    00048 /*! Invalid fd */
    00049 #define AST_IO_NVAL  POLLNVAL
    00050
    00051 /*
    00052  * An Asterisk IO callback takes its id, a file descriptor, list of events, and
    00053  * callback data as arguments and returns 0 if it should not be
    00054  * run again, or non-zero if it should be run again.
    00055  */
    00056
    00057 struct io_context;
    00058
    00059 /*! Creates a context */
    00060 /*!
    00061  * Create a context for I/O operations
    00062  * Basically mallocs an IO structure and sets up some default values.
    00063  * Returns an allocated io_context structure
    00064  */
    00065 extern struct io_context *io_context_create(void);
    00066
    00067 /*! Destroys a context */
    00068 /*
    00069  * \param ioc structure to destroy
    00070  * Destroy a context for I/O operations
    00071  * Frees all memory associated with the given io_context structure along with the structure itself
    00072  */
    00073 extern void io_context_destroy(struct io_context *ioc);
    00074
    00075 typedef int (*ast_io_cb)(int *id, int fd, short events, void *cbdata);
    00076 #define AST_IO_CB(a) ((ast_io_cb)(a))
    00077
    00078 /*! Adds an IO context */
    00079 /*!
    00080  * \param ioc which context to use
    00081  * \param fd which fd to monitor
    00082  * \param callback callback function to run
    00083  * \param events event mask of events to wait for
    00084  * \param data data to pass to the callback
    00085  * Watch for any of revents activites on fd, calling callback with data as
    00086  * callback data.  Returns a pointer to ID of the IO event, or NULL on failure.
    00087  */
    00088 extern int *ast_io_add(struct io_context *ioc, int fd, ast_io_cb callback, short events, void *data);
    00089
    00090 /*! Changes an IO handler */
    00091 /*!
    00092  * \param ioc which context to use
    00093  * \param id
    00094  * \param fd the fd you wish it to contain now
    00095  * \param callback new callback function
    00096  * \param events event mask to wait for
    00097  * \param data data to pass to the callback function
    00098  * Change an i/o handler, updating fd if > -1, callback if non-null, and revents
    00099  * if >-1, and data if non-null.  Returns a pointero to the ID of the IO event,
    00100  * or NULL on failure.
    00101  */
    00102 extern int *ast_io_change(struct io_context *ioc, int *id, int fd, ast_io_cb callback, short events, void *data);
    00103
    00104 /*! Removes an IO context */
    00105 /*!
    00106  * \param ioc which io_context to remove it from
    00107  * \param id which ID to remove
    00108  * Remove an I/O id from consideration  Returns 0 on success or -1 on failure.
    00109  */
    00110 extern int ast_io_remove(struct io_context *ioc, int *id);
    00111
    00112 /*! Waits for IO */
    00113 /*!
    00114  * \param ioc which context to act upon
    00115  * \param howlong how many milliseconds to wait
    00116  * Wait for I/O to happen, returning after
    00117  * howlong milliseconds, and after processing
    00118  * any necessary I/O.  Returns the number of
    00119  * I/O events which took place.
    00120  */
    00121 extern int ast_io_wait(struct io_context *ioc, int howlong);
    00122
    00123 /*! Dumps the IO array */
    00124 /*
    00125  * Debugging: Dump everything in the I/O array
    00126  */
    00127 extern void ast_io_dump(struct io_context *ioc);
    00128
    00129 /*! Set fd into non-echoing mode (if fd is a tty) */
    00130
    00131 extern int ast_hide_password(int fd);
    00132
    00133 /*! Restores TTY mode */
    00134 /*
    00135  * Call with result from previous ast_hide_password
    00136  */
    00137 extern int ast_restore_tty(int fd, int oldstatus);
    00138
    00139 extern int ast_get_termcols(int fd);
    00140
    00141 #if defined(__cplusplus) || defined(c_plusplus)
    00142 }
    00143 #endif
    00144
    00145 #endif /* _ASTERISK_IO_H */