00001 #ifndef LIBNAGIOS_IOCACHE_H_INCLUDED 00002 #define LIBNAGIOS_IOCACHE_H_INCLUDED 00003 #include <stdlib.h> 00004 #include <sys/types.h> 00005 #include <sys/socket.h> 00006 00007 /** 00008 * @file iocache.h 00009 * @brief I/O cache function declarations 00010 * 00011 * The I/O cache library is useful for reading large chunks of data 00012 * from sockets and utilizing parts of that data based on either 00013 * size or a magic delimiter. 00014 * 00015 * @{ 00016 */ 00017 00018 /** opaque type for iocache operations */ 00019 struct iocache; 00020 typedef struct iocache iocache; 00021 00022 /** 00023 * Destroys an iocache object, freeing all memory allocated to it. 00024 * @param ioc The iocache object to destroy 00025 */ 00026 extern void iocache_destroy(iocache *ioc); 00027 00028 /** 00029 * Resets an iocache struct, discarding all data in it without free()'ing 00030 * any memory. 00031 * 00032 * @param[in] ioc The iocache struct to reset 00033 */ 00034 extern void iocache_reset(iocache *ioc); 00035 00036 /** 00037 * Resizes the buffer in an io cache 00038 * @param ioc The io cache to resize 00039 * @param new_size The new size of the io cache 00040 * @return 0 on success, -1 on errors 00041 */ 00042 extern int iocache_resize(iocache *ioc, unsigned long new_size); 00043 00044 /** 00045 * Grows an iocache object 00046 * This uses iocache_resize() internally 00047 * @param[in] ioc The iocache to grow 00048 * @param[in] increment How much to increase it 00049 * @return 0 on success, -1 on errors 00050 */ 00051 extern int iocache_grow(iocache *ioc, unsigned long increment); 00052 00053 /** 00054 * Returns the total size of the io cache 00055 * @param[in] ioc The iocache to inspect 00056 * @return The size of the io cache. If ioc is null, 0 is returned 00057 */ 00058 extern unsigned long iocache_size(iocache *ioc); 00059 00060 /** 00061 * Returns remaining read capacity of the io cache 00062 * @param ioc The io cache to operate on 00063 * @return The number of bytes available to read 00064 */ 00065 extern unsigned long iocache_capacity(iocache *ioc); 00066 00067 /** 00068 * Return the amount of unread but stored data in the io cache 00069 * @param ioc The io cache to operate on 00070 * @return Number of bytes available to read 00071 */ 00072 extern unsigned long iocache_available(iocache *ioc); 00073 00074 /** 00075 * Use a chunk of data from iocache based on size. The caller 00076 * must take care not to write beyond the end of the requested 00077 * buffer, or Bad Things(tm) will happen. 00078 * 00079 * @param ioc The io cache we should use data from 00080 * @param size The size of the data we want returned 00081 * @return NULL on errors (insufficient data, fe). pointer on success 00082 */ 00083 extern char *iocache_use_size(iocache *ioc, unsigned long size); 00084 00085 /** 00086 * Use a chunk of data from iocache based on delimiter. The 00087 * caller must take care not to write beyond the end of the 00088 * requested buffer, if any is returned, or Bad Things(tm) will 00089 * happen. 00090 * 00091 * @param ioc The io cache to use data from 00092 * @param delim The delimiter 00093 * @param delim_len Length of the delimiter 00094 * @param size Length of the returned buffer 00095 * @return NULL on errors (delimiter not found, insufficient data). pointer on success 00096 */ 00097 extern char *iocache_use_delim(iocache *ioc, const char *delim, size_t delim_len, unsigned long *size); 00098 00099 /** 00100 * Forget that a specified number of bytes have been used. 00101 * @param ioc The io cache that you want to un-use data in 00102 * @param size The number of bytes you want to forget you've seen 00103 * @return -1 if there was an error, 0 otherwise. 00104 */ 00105 extern int iocache_unuse_size(iocache *ioc, unsigned long size); 00106 00107 /** 00108 * Creates the iocache object, initializing it with the given size 00109 * @param size Initial size of the iocache buffer 00110 * @return Pointer to a valid iocache object 00111 */ 00112 extern iocache *iocache_create(unsigned long size); 00113 00114 /** 00115 * Read data into the iocache buffer 00116 * @param ioc The io cache we should read into 00117 * @param fd The filedescriptor we should read from 00118 * @return The number of bytes read on success. < 0 on errors 00119 */ 00120 extern int iocache_read(iocache *ioc, int fd); 00121 00122 /** 00123 * Add data to the iocache buffer 00124 * The data is copied, so it can safely be taken from the stack in a 00125 * function that returns before the data is used. 00126 * If the io cache is too small to hold the data, -1 will be returned. 00127 * 00128 * @param[in] ioc The io cache to add to 00129 * @param[in] buf Pointer to the data we should add 00130 * @param[in] len Length (in bytes) of data pointed to by buf 00131 * @return iocache_available(ioc) on success, -1 on errors 00132 */ 00133 extern int iocache_add(iocache *ioc, char *buf, unsigned int len); 00134 00135 /** 00136 * Like sendto(), but sends all cached data prior to the requested 00137 * 00138 * @param[in] ioc The iocache to send, or cache data in 00139 * @param[in] fd The file descriptor to send to 00140 * @param[in] buf Pointer to the data to send 00141 * @param[in] len Length (in bytes) of data to send 00142 * @param[in] flags Flags passed to sendto(2) 00143 * @param[in] dest_addr Destination address 00144 * @param[in] addrlen size (in bytes) of dest_addr 00145 * @return bytes sent on success, -ERRNO on errors 00146 */ 00147 extern int iocache_sendto(iocache *ioc, int fd, char *buf, unsigned int len, int flags, const struct sockaddr *dest_addr, socklen_t addrlen); 00148 00149 /** 00150 * Like send(2), but sends all cached data prior to the requested 00151 * This function uses iocache_sendto() internally, but can only be 00152 * used on connected sockets or open()'ed files. 00153 * 00154 * @param[in] ioc The iocache to send, or cache data in 00155 * @param[in] fd The file descriptor to send to 00156 * @param[in] buf Pointer to the data to send 00157 * @param[in] len Length (in bytes) of data to send 00158 * @param[in] flags Flags passed to sendto(2) 00159 * @return bytes sent on success, -ERRNO on errors 00160 */ 00161 static inline int iocache_send(iocache *ioc, int fd, char *buf, unsigned int len, int flags) 00162 { 00163 return iocache_sendto(ioc, fd, buf, len, flags, NULL, 0); 00164 } 00165 00166 /** 00167 * Like write(2), but sends all cached data prior to the requested 00168 * This function uses iocache_send() internally. 00169 * 00170 * @param[in] ioc The iocache to send, or cache data in 00171 * @param[in] fd The file descriptor to send to 00172 * @param[in] buf Pointer to the data to send 00173 * @param[in] len Length (in bytes) of data to send 00174 * @return bytes sent on success, -ERRNO on errors 00175 */ 00176 static inline int iocache_write(iocache *ioc, int fd, char *buf, unsigned int len) 00177 { 00178 return iocache_send(ioc, fd, buf, len, 0); 00179 } 00180 #endif /* INCLUDE_iocache_h__ */ 00181 /** @} */