1 /* distcache, Distributed Session Caching technology 2 * Copyright (C) 2000-2003 Geoff Thorpe, and Cryptographic Appliances, Inc. 3 * Copyright (C) 2004 The Distcache.org project 4 * 5 * This library is free software; you can redistribute it and/or modify it under 6 * the terms of the GNU Lesser General Public License as published by the Free 7 * Software Foundation; using version 2.1 of the License. The copyright holders 8 * may elect to allow the application of later versions of the License to this 9 * software, please contact the author (geoff@distcache.org) if you wish us to 10 * review any later version released by the Free Software Foundation. 11 * 12 * This library is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 14 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 15 * details. 16 * 17 * You should have received a copy of the GNU Lesser General Public License 18 * along with this library; if not, write to the Free Software Foundation, Inc., 19 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 20 */ 21 #ifndef HEADER_LIBNAL_NAL_H 22 #define HEADER_LIBNAL_NAL_H 23 24 /*-----------------------*/ 25 /* "libnal" EXTERNAL API */ 26 /* ----------------------*/ 27 28 typedef struct st_NAL_ADDRESS NAL_ADDRESS; 29 typedef struct st_NAL_LISTENER NAL_LISTENER; 30 typedef struct st_NAL_CONNECTION NAL_CONNECTION; 31 typedef struct st_NAL_SELECTOR NAL_SELECTOR; 32 typedef struct st_NAL_BUFFER NAL_BUFFER; 33 34 /* Flags passed to NAL_CONNECTION_add_to_selector_ex() */ 35 #define NAL_SELECT_FLAG_READ (unsigned int)0x0001 36 #define NAL_SELECT_FLAG_SEND (unsigned int)0x0002 37 #define NAL_SELECT_FLAG_RW (NAL_SELECT_FLAG_READ | NAL_SELECT_FLAG_SEND) 38 39 /********************/ 40 /* Global functions */ 41 /********************/ 42 43 void NAL_config_set_nagle(int enabled); 44 45 /*********************/ 46 /* Address functions */ 47 /*********************/ 48 49 NAL_ADDRESS * NAL_ADDRESS_new(void); 50 void NAL_ADDRESS_free(NAL_ADDRESS *addr); 51 void NAL_ADDRESS_reset(NAL_ADDRESS *addr); 52 int NAL_ADDRESS_create(NAL_ADDRESS *addr, const char *addr_string, 53 unsigned int def_buffer_size); 54 unsigned int NAL_ADDRESS_get_def_buffer_size(const NAL_ADDRESS *addr); 55 int NAL_ADDRESS_set_def_buffer_size(NAL_ADDRESS *addr, 56 unsigned int def_buffer_size); 57 int NAL_ADDRESS_can_connect(const NAL_ADDRESS *addr); 58 int NAL_ADDRESS_can_listen(const NAL_ADDRESS *addr); 59 60 /**********************/ 61 /* Selector functions */ 62 /**********************/ 63 64 NAL_SELECTOR * NAL_SELECTOR_new(void); 65 void NAL_SELECTOR_free(NAL_SELECTOR *sel); 66 void NAL_SELECTOR_reset(NAL_SELECTOR *sel); 67 int NAL_SELECTOR_select(NAL_SELECTOR *sel, 68 unsigned long usec_timeout, 69 int use_timeout); 70 unsigned int NAL_SELECTOR_num_objects(const NAL_SELECTOR *sel); 71 /* implementation-specific constructors */ 72 NAL_SELECTOR * NAL_SELECTOR_new_fdselect(void); 73 NAL_SELECTOR * NAL_SELECTOR_new_fdpoll(void); 74 75 /********************************/ 76 /* Listener functions (general) */ 77 /********************************/ 78 79 NAL_LISTENER * NAL_LISTENER_new(void); 80 void NAL_LISTENER_free(NAL_LISTENER *list); 81 void NAL_LISTENER_reset(NAL_LISTENER *list); 82 int NAL_LISTENER_create(NAL_LISTENER *list, 83 const NAL_ADDRESS *addr); 84 int NAL_LISTENER_add_to_selector(NAL_LISTENER *list, 85 NAL_SELECTOR *sel); 86 void NAL_LISTENER_del_from_selector(NAL_LISTENER *list); 87 int NAL_LISTENER_finished(const NAL_LISTENER *list); 88 89 /************************************/ 90 /* Listener functions (specialised) */ 91 /************************************/ 92 93 int NAL_LISTENER_set_fs_owner(NAL_LISTENER *list, 94 const char *ownername, 95 const char *groupname); 96 int NAL_LISTENER_set_fs_perms(NAL_LISTENER *list, 97 const char *octal_string); 98 99 /**********************************/ 100 /* Connection functions (general) */ 101 /**********************************/ 102 103 NAL_CONNECTION *NAL_CONNECTION_new(void); 104 void NAL_CONNECTION_free(NAL_CONNECTION *conn); 105 void NAL_CONNECTION_reset(NAL_CONNECTION *conn); 106 int NAL_CONNECTION_create(NAL_CONNECTION *conn, 107 const NAL_ADDRESS *addr); 108 int NAL_CONNECTION_accept(NAL_CONNECTION *conn, 109 NAL_LISTENER *list); 110 int NAL_CONNECTION_set_size(NAL_CONNECTION *conn, 111 unsigned int size); 112 NAL_BUFFER * NAL_CONNECTION_get_read(NAL_CONNECTION *conn); 113 NAL_BUFFER * NAL_CONNECTION_get_send(NAL_CONNECTION *conn); 114 const NAL_BUFFER *NAL_CONNECTION_get_read_c(const NAL_CONNECTION *conn); 115 const NAL_BUFFER *NAL_CONNECTION_get_send_c(const NAL_CONNECTION *conn); 116 int NAL_CONNECTION_io(NAL_CONNECTION *conn); 117 int NAL_CONNECTION_is_established(const NAL_CONNECTION *conn); 118 int NAL_CONNECTION_add_to_selector(NAL_CONNECTION *conn, 119 NAL_SELECTOR *sel); 120 void NAL_CONNECTION_del_from_selector(NAL_CONNECTION *conn); 121 122 /**************************************/ 123 /* Connection functions (specialised) */ 124 /**************************************/ 125 126 int NAL_CONNECTION_create_pair(NAL_CONNECTION *conn1, 127 NAL_CONNECTION *conn2, 128 unsigned int def_buffer_size); 129 #if 0 130 int NAL_CONNECTION_create_dummy(NAL_CONNECTION *conn, 131 unsigned int def_buffer_size); 132 #endif 133 134 /********************/ 135 /* Buffer functions */ 136 /********************/ 137 138 NAL_BUFFER * NAL_BUFFER_new(void); 139 void NAL_BUFFER_free(NAL_BUFFER *buf); 140 void NAL_BUFFER_reset(NAL_BUFFER *buf); 141 int NAL_BUFFER_set_size(NAL_BUFFER *buf, 142 unsigned int size); 143 int NAL_BUFFER_empty(const NAL_BUFFER *buf); 144 int NAL_BUFFER_full(const NAL_BUFFER *buf); 145 int NAL_BUFFER_notempty(const NAL_BUFFER *buf); 146 int NAL_BUFFER_notfull(const NAL_BUFFER *buf); 147 unsigned int NAL_BUFFER_used(const NAL_BUFFER *buf); 148 unsigned int NAL_BUFFER_unused(const NAL_BUFFER *buf); 149 unsigned int NAL_BUFFER_size(const NAL_BUFFER *buf); 150 const unsigned char *NAL_BUFFER_data(const NAL_BUFFER *buf); 151 /* Now we define the general "access" functions for the buffer type */ 152 unsigned int NAL_BUFFER_write(NAL_BUFFER *buf, 153 const unsigned char *ptr, 154 unsigned int size); 155 unsigned int NAL_BUFFER_read(NAL_BUFFER *buf, 156 unsigned char *ptr, 157 unsigned int size); 158 unsigned int NAL_BUFFER_transfer(NAL_BUFFER *dest, NAL_BUFFER *src, 159 unsigned int max); 160 161 /***************** WARNING START ********************/ 162 /* These functions manipulate internal data directly and are to be used with 163 * caution - it's easy for data to "go missing" or "get created out of nowhere" 164 * by misusing these functions. */ 165 /******** WARNING END - you have been warned ********/ 166 167 /* Returns a pointer to the tail of the buffer's data, you should never attempt 168 * to write more than NAL_BUFFER_unused(buf) bytes from the return value. */ 169 unsigned char * NAL_BUFFER_write_ptr(NAL_BUFFER *buf); 170 /* If you wrote data directly to the buffer using ...write_ptr() rather than 171 * NAL_BUFFER_write(), then use this call to indicate that the buffer has "size" 172 * more bytes available to it at the position ...write_ptr() returned. */ 173 void NAL_BUFFER_wrote(NAL_BUFFER *buf, 174 unsigned int size); 175 176 /*************************/ 177 /* En/Decoding functions */ 178 /*************************/ 179 180 /* This set of functions provide architecture-independant ways of encoding 181 * various primitive types. The general format of the functions is; 182 * int NAL_decode_XX(const unsigned char **bin, unsigned int *bin_len, 183 * XX *val); 184 * and 185 * int NAL_encode_XX(unsigned char **bin, unsigned int *cnt, 186 * const XX val); 187 * where 'XX' is the primitive type in question. The behaviour is that bin & 188 * bin_len are altered after the encoding/decoding so that bin points to the 189 * next unused byte and bin_len is reduced by the number of bytes used. As such, 190 * these functions can be used in situations where (i) the input may be 191 * insufficient to encode or decode the relevant structure, and (ii) where 192 * multiple levels of encoding/decoding may be constructed for aggregate 193 * structure types. 194 * 195 * The return values are zero for failure and non-zero for success. 196 */ 197 int NAL_decode_uint32(const unsigned char **bin, unsigned int *bin_len, 198 unsigned long *val); 199 int NAL_decode_uint16(const unsigned char **bin, unsigned int *bin_len, 200 unsigned int *val); 201 int NAL_decode_char(const unsigned char **bin, unsigned int *bin_len, 202 unsigned char *val); 203 int NAL_decode_bin(const unsigned char **bin, unsigned int *bin_len, 204 unsigned char *val, unsigned int val_len); 205 206 int NAL_encode_uint32(unsigned char **bin, unsigned int *bin_len, 207 const unsigned long val); 208 int NAL_encode_uint16(unsigned char **bin, unsigned int *bin_len, 209 const unsigned int val); 210 int NAL_encode_char(unsigned char **bin, unsigned int *bin_len, 211 const unsigned char val); 212 int NAL_encode_bin(unsigned char **bin, unsigned int *bin_len, 213 const unsigned char *val, const unsigned int val_len); 214 215 #endif /* !defined(HEADER_LIBNAL_NAL_H) */ 216 217