00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as 00002 * applicable. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef APR_POLL_H 00018 #define APR_POLL_H 00019 /** 00020 * @file apr_poll.h 00021 * @brief APR Poll interface 00022 */ 00023 #include "apr.h" 00024 #include "apr_pools.h" 00025 #include "apr_errno.h" 00026 #include "apr_inherit.h" 00027 #include "apr_file_io.h" 00028 #include "apr_network_io.h" 00029 00030 #if APR_HAVE_NETINET_IN_H 00031 #include <netinet/in.h> 00032 #endif 00033 00034 #ifdef __cplusplus 00035 extern "C" { 00036 #endif /* __cplusplus */ 00037 00038 /** 00039 * @defgroup apr_poll Poll Routines 00040 * @ingroup APR 00041 * @{ 00042 */ 00043 00044 /** 00045 * @defgroup apr_poll_opt Poll options 00046 * @{ 00047 */ 00048 #define APR_POLLIN 0x001 /**< Can read without blocking */ 00049 #define APR_POLLPRI 0x002 /**< Priority data available */ 00050 #define APR_POLLOUT 0x004 /**< Can write without blocking */ 00051 #define APR_POLLERR 0x010 /**< Pending error */ 00052 #define APR_POLLHUP 0x020 /**< Hangup occurred */ 00053 #define APR_POLLNVAL 0x040 /**< Descriptior invalid */ 00054 /** @} */ 00055 00056 /** Used in apr_pollfd_t to determine what the apr_descriptor is */ 00057 typedef enum { 00058 APR_NO_DESC, /**< nothing here */ 00059 APR_POLL_SOCKET, /**< descriptor refers to a socket */ 00060 APR_POLL_FILE, /**< descriptor refers to a file */ 00061 APR_POLL_LASTDESC /**< descriptor is the last one in the list */ 00062 } apr_datatype_e ; 00063 00064 /** Union of either an APR file or socket. */ 00065 typedef union { 00066 apr_file_t *f; /**< file */ 00067 apr_socket_t *s; /**< socket */ 00068 } apr_descriptor; 00069 00070 /** @see apr_pollfd_t */ 00071 typedef struct apr_pollfd_t apr_pollfd_t; 00072 00073 /** Poll descriptor set. */ 00074 struct apr_pollfd_t { 00075 apr_pool_t *p; /**< associated pool */ 00076 apr_datatype_e desc_type; /**< descriptor type */ 00077 apr_int16_t reqevents; /**< requested events */ 00078 apr_int16_t rtnevents; /**< returned events */ 00079 apr_descriptor desc; /**< @see apr_descriptor */ 00080 void *client_data; /**< allows app to associate context */ 00081 }; 00082 00083 /** 00084 * Setup the memory required for poll to operate properly 00085 * @param new_poll The poll structure to be used. 00086 * @param num The number of socket descriptors to be polled. 00087 * @param cont The pool to operate on. 00088 * @deprecated This function is deprecated, APR applications should control the pollset memory themselves. 00089 */ 00090 APR_DECLARE(apr_status_t) apr_poll_setup(apr_pollfd_t **new_poll, 00091 apr_int32_t num, 00092 apr_pool_t *cont); 00093 00094 /** 00095 * Poll the sockets in the poll structure 00096 * @param aprset The poll structure we will be using. 00097 * @param numsock The number of sockets we are polling 00098 * @param nsds The number of sockets signalled. 00099 * @param timeout The amount of time in microseconds to wait. This is 00100 * a maximum, not a minimum. If a socket is signalled, we 00101 * will wake up before this time. A negative number means 00102 * wait until a socket is signalled. 00103 * @remark 00104 * <PRE> 00105 * The number of sockets signalled is returned in the second argument. 00106 * 00107 * This is a blocking call, and it will not return until either a 00108 * socket has been signalled, or the timeout has expired. 00109 * </PRE> 00110 */ 00111 APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t numsock, 00112 apr_int32_t *nsds, 00113 apr_interval_time_t timeout); 00114 00115 /** 00116 * Add a socket to the poll structure. 00117 * @param aprset The poll structure we will be using. 00118 * @param sock The socket to add to the current poll structure. 00119 * @param event The events to look for when we do the poll. One of: 00120 * <PRE> 00121 * APR_POLLIN signal if read will not block 00122 * APR_POLLPRI signal if prioirty data is availble to be read 00123 * APR_POLLOUT signal if write will not block 00124 * </PRE> 00125 * @deprecated This function is deprecated, APR applications should control the pollset memory themselves. 00126 */ 00127 APR_DECLARE(apr_status_t) apr_poll_socket_add(apr_pollfd_t *aprset, 00128 apr_socket_t *sock, 00129 apr_int16_t event); 00130 00131 /** 00132 * Modify a socket in the poll structure with mask. 00133 * @param aprset The poll structure we will be using. 00134 * @param sock The socket to modify in poll structure. 00135 * @param events The events to stop looking for during the poll. One of: 00136 * <PRE> 00137 * APR_POLLIN signal if read will not block 00138 * APR_POLLPRI signal if priority data is available to be read 00139 * APR_POLLOUT signal if write will not block 00140 * </PRE> 00141 * @deprecated This function is deprecated, APR applications should control the pollset memory themselves. 00142 */ 00143 APR_DECLARE(apr_status_t) apr_poll_socket_mask(apr_pollfd_t *aprset, 00144 apr_socket_t *sock, 00145 apr_int16_t events); 00146 /** 00147 * Remove a socket from the poll structure. 00148 * @param aprset The poll structure we will be using. 00149 * @param sock The socket to remove from the current poll structure. 00150 * @deprecated This function is deprecated, APR applications should control the pollset memory themselves. 00151 */ 00152 APR_DECLARE(apr_status_t) apr_poll_socket_remove(apr_pollfd_t *aprset, 00153 apr_socket_t *sock); 00154 00155 /** 00156 * Clear all events in the poll structure. 00157 * @param aprset The poll structure we will be using. 00158 * @param events The events to clear from all sockets. One of: 00159 * <PRE> 00160 * APR_POLLIN signal if read will not block 00161 * APR_POLLPRI signal if priority data is available to be read 00162 * APR_POLLOUT signal if write will not block 00163 * </PRE> 00164 * @deprecated This function is deprecated, APR applications should control the pollset memory themselves. 00165 */ 00166 APR_DECLARE(apr_status_t) apr_poll_socket_clear(apr_pollfd_t *aprset, 00167 apr_int16_t events); 00168 00169 /** 00170 * Get the return events for the specified socket. 00171 * @param event The returned events for the socket. One of: 00172 * <PRE> 00173 * APR_POLLIN Data is available to be read 00174 * APR_POLLPRI Priority data is availble to be read 00175 * APR_POLLOUT Write will succeed 00176 * APR_POLLERR An error occurred on the socket 00177 * APR_POLLHUP The connection has been terminated 00178 * APR_POLLNVAL This is an invalid socket to poll on. 00179 * Socket not open. 00180 * </PRE> 00181 * @param sock The socket we wish to get information about. 00182 * @param aprset The poll structure we will be using. 00183 * @deprecated This function is deprecated, APR applications should control the pollset memory themselves. 00184 */ 00185 APR_DECLARE(apr_status_t) apr_poll_revents_get(apr_int16_t *event, 00186 apr_socket_t *sock, 00187 apr_pollfd_t *aprset); 00188 00189 /* General-purpose poll API for arbitrarily large numbers of 00190 * file descriptors 00191 */ 00192 00193 /** Opaque structure used for pollset API */ 00194 typedef struct apr_pollset_t apr_pollset_t; 00195 00196 /** 00197 * Setup a pollset object 00198 * @param pollset The pointer in which to return the newly created object 00199 * @param size The maximum number of descriptors that this pollset can hold 00200 * @param p The pool from which to allocate the pollset 00201 * @param flags Optional flags to modify the operation of the pollset 00202 * (reserved for future expansion) 00203 */ 00204 APR_DECLARE(apr_status_t) apr_pollset_create(apr_pollset_t **pollset, 00205 apr_uint32_t size, 00206 apr_pool_t *p, 00207 apr_uint32_t flags); 00208 00209 /** 00210 * Destroy a pollset object 00211 * @param pollset The pollset to destroy 00212 */ 00213 APR_DECLARE(apr_status_t) apr_pollset_destroy(apr_pollset_t *pollset); 00214 00215 /** 00216 * Add a socket or file descriptor to a pollset 00217 * @param pollset The pollset to which to add the descriptor 00218 * @param descriptor The descriptor to add 00219 * @remark If you set client_data in the descriptor, that value 00220 * will be returned in the client_data field whenever this 00221 * descriptor is signalled in apr_pollset_poll(). 00222 */ 00223 APR_DECLARE(apr_status_t) apr_pollset_add(apr_pollset_t *pollset, 00224 const apr_pollfd_t *descriptor); 00225 00226 /** 00227 * Remove a descriptor from a pollset 00228 * @param pollset The pollset from which to remove the descriptor 00229 * @param descriptor The descriptor to remove 00230 */ 00231 APR_DECLARE(apr_status_t) apr_pollset_remove(apr_pollset_t *pollset, 00232 const apr_pollfd_t *descriptor); 00233 00234 /** 00235 * Block for activity on the descriptor(s) in a pollset 00236 * @param pollset The pollset to use 00237 * @param timeout Timeout in microseconds 00238 * @param num Number of signalled descriptors (output parameter) 00239 * @param descriptors Array of signalled descriptors (output parameter) 00240 */ 00241 APR_DECLARE(apr_status_t) apr_pollset_poll(apr_pollset_t *pollset, 00242 apr_interval_time_t timeout, 00243 apr_int32_t *num, 00244 const apr_pollfd_t **descriptors); 00245 00246 /** @} */ 00247 00248 #ifdef __cplusplus 00249 } 00250 #endif 00251 00252 #endif /* ! APR_POLL_H */ 00253