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 POLLCOMPAT
  27 #include "asterisk/poll-compat.h"
  28 #else
  29 #include <sys/poll.h>           /* For POLL* constants */
  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 /*
  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 /*! Creates a context */
  60 /*!
  61  * Create a context for I/O operations
  62  * Basically mallocs an IO structure and sets up some default values.
  63  * Returns an allocated io_context structure
  64  */
  65 struct io_context *io_context_create(void);
  66
  67 /*! Destroys a context */
  68 /*
  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 /*! Adds an IO context */
  79 /*!
  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.  Returns a pointer to ID of the IO event, or NULL on failure.
  87  */
  88 int *ast_io_add(struct io_context *ioc, int fd, ast_io_cb callback, short events, void *data);
  89
  90 /*! Changes an IO handler */
  91 /*!
  92  * \param ioc which context to use
  93  * \param id
  94  * \param fd the fd you wish it to contain now
  95  * \param callback new callback function
  96  * \param events event mask to wait for
  97  * \param data data to pass to the callback function
  98  * Change an i/o handler, updating fd if > -1, callback if non-null, and revents
  99  * if >-1, and data if non-null.  Returns a pointero to the ID of the IO event,
 100  * or 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 /*! Removes an IO context */
 105 /*!
 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  Returns 0 on success or -1 on failure.
 109  */
 110 int ast_io_remove(struct io_context *ioc, int *id);
 111
 112 /*! Waits for IO */
 113 /*!
 114  * \param ioc which context to act upon
 115  * \param howlong how many milliseconds to wait
 116  * Wait for I/O to happen, returning after
 117  * howlong milliseconds, and after processing
 118  * any necessary I/O.  Returns the number of
 119  * I/O events which took place.
 120  */
 121 int ast_io_wait(struct io_context *ioc, int howlong);
 122
 123 /*! Dumps the IO array */
 124 /*
 125  * Debugging: Dump everything in the I/O array
 126  */
 127 void ast_io_dump(struct io_context *ioc);
 128
 129 /*! Set fd into non-echoing mode (if fd is a tty) */
 130
 131 int ast_hide_password(int fd);
 132
 133 /*! Restores TTY mode */
 134 /*
 135  * Call with result from previous ast_hide_password
 136  */
 137 int ast_restore_tty(int fd, int oldstatus);
 138
 139 int ast_get_termcols(int fd);
 140
 141 #if defined(__cplusplus) || defined(c_plusplus)
 142 }
 143 #endif
 144
 145 #endif /* _ASTERISK_IO_H */