00001 /* 00002 Licensed to the Apache Software Foundation (ASF) under one 00003 or more contributor license agreements. See the NOTICE file 00004 distributed with this work for additional information 00005 regarding copyright ownership. The ASF licenses this file 00006 to you under the Apache License, Version 2.0 (the 00007 "License"); you may not use this file except in compliance 00008 with the License. You may obtain a copy of the License at 00009 00010 http://www.apache.org/licenses/LICENSE-2.0 00011 00012 Unless required by applicable law or agreed to in writing, 00013 software distributed under the License is distributed on an 00014 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00015 KIND, either express or implied. See the License for the 00016 specific language governing permissions and limitations 00017 under the License. 00018 */ 00019 00020 #ifndef AVRO_H 00021 #define AVRO_H 00022 00023 /** 00024 @file avro.h 00025 @brief AVRO API 00026 */ 00027 00028 #include <stdarg.h> 00029 #include <stdint.h> 00030 #include <sys/types.h> 00031 #include <apr_pools.h> 00032 #include <apr_file_io.h> 00033 #include <apr_network_io.h> 00034 00035 #ifdef __cplusplus 00036 extern "C" { 00037 #endif 00038 00039 /** 00040 @defgroup AVRO Avro C API 00041 @{ 00042 */ 00043 00044 /** 00045 * @defgroup Handle_Routines AVRO Handles 00046 * @ingroup AVRO 00047 * @{ 00048 */ 00049 00050 /** 00051 Avro operation enum. 00052 Enum for discriminating whether an Avro handle is for encoding or decoding data. 00053 */ 00054 enum avro_op 00055 { 00056 AVRO_ENCODE = 0, /**< Marks a handle as encoding Avro data */ 00057 AVRO_DECODE = 1 /**< Marks a handle as decoding Avro data */ 00058 }; 00059 typedef enum avro_op avro_op; 00060 00061 /** 00062 Avro status enum. 00063 Enum used by Avro functions to return state. 00064 @todo expand the number of states 00065 */ 00066 enum avro_status_t 00067 { 00068 AVRO_OK = 0, /**< Function success */ 00069 AVRO_FAILURE = 1 /**< Function failure */ 00070 }; 00071 typedef enum avro_status_t avro_status_t; 00072 #define CHECK_ERROR(__status) if(__status != AVRO_OK){ return __status; } 00073 00074 /** 00075 Avro handle. 00076 Opaque handle for encoding/decoding data to memory, file or network. 00077 @warning Never operate on an Avro handle directly. Use the AVRO Handle routines instead. 00078 */ 00079 struct AVRO 00080 { 00081 enum avro_op a_op; /**< Hold the type of operation the handle is performing */ 00082 struct avro_ops 00083 { 00084 /** 00085 * Function for getting bytes from the underlying media 00086 */ 00087 avro_status_t (*a_getbytes) (struct AVRO * avro, caddr_t addr, 00088 int64_t len); 00089 /** 00090 * Function for sending bytes to the backing store 00091 */ 00092 avro_status_t (*a_putbytes) (struct AVRO * avro, const char *addr, 00093 const int64_t len); 00094 } *a_ops; 00095 apr_pool_t *pool; /**< Pool used for allocating memory for dynamic data structures */ 00096 unsigned char *schema; /**< Current AVRO schema for processing data */ 00097 00098 apr_file_t *file; /**< Used by the file-backed handle */ 00099 apr_socket_t *socket; /**< Used by the socket-backed handle */ 00100 caddr_t addr; /**< Used by the memory-backed handle */ 00101 int64_t len; /**< Used by the memory-backed handle */ 00102 int64_t used; /**< Used by the memory-backed handle */ 00103 }; 00104 typedef struct AVRO AVRO; 00105 00106 #define AVRO_GETBYTES(avro, addr, len) \ 00107 (*(avro)->a_ops->a_getbytes)(avro, addr, len) 00108 00109 #define AVRO_PUTBYTES(avro, addr, len) \ 00110 (*(avro)->a_ops->a_putbytes)(avro, addr, len) 00111 00112 /** Initialize the AVRO library 00113 @return The Avro status 00114 */ 00115 avro_status_t avro_initialize(void); 00116 00117 /** Create a memory-backed Avro handle 00118 @param avro Pointer to handle that will be initialized 00119 @param pool Pool used for allocating dynamic data structures. 00120 @param addr Address of the memory location for manipulating data 00121 @param len Size of the memory to use 00122 @param op Expressing the operation the handle should perform (e.g. encode, decode) 00123 @return The Avro status 00124 */ 00125 avro_status_t avro_create_memory (AVRO * avro, apr_pool_t * pool, 00126 caddr_t addr, int64_t len, avro_op op); 00127 00128 /** Create a file-backed Avro handle 00129 @param avro Pointer to the handle that will be initialized 00130 @param pool Pool used for allocating dynamic data structures 00131 @param file The file to read(decode) or write(encode) from 00132 @param op Expresses the operation the handle should perform (e.g. encode, decode) 00133 @return The Avro status 00134 */ 00135 avro_status_t avro_create_file (AVRO * avro, apr_pool_t * pool, 00136 apr_file_t * file, avro_op op); 00137 00138 /** Create a socket-backed Avro handle 00139 @param avro Pointer to the handle that will be initialized 00140 @param pool Pool used for allocating dynamic data structures 00141 @param socket The socket to read(decode) or write(encode) from 00142 @param op Expresses the operation the handle should perform (e.g. encode, decode) 00143 @return The Avro status 00144 */ 00145 avro_status_t avro_create_socket (AVRO * avro, apr_pool_t * pool, 00146 apr_socket_t * socket, avro_op op); 00147 /** @} */ 00148 00149 typedef avro_status_t (*avroproc_t) (AVRO *, void *, ...); 00150 typedef int bool_t; 00151 00152 /** 00153 * @defgroup Primitives AVRO Primitive Type Serialization 00154 * @ingroup AVRO 00155 * @{ 00156 */ 00157 00158 /** avro_null() will not read or write any data 00159 */ 00160 avro_status_t avro_null (void); 00161 00162 /** avro_int64() is called to read/write a 64-bit signed integer 00163 @param avro The Avro handle 00164 @param lp Pointer to the 64-bit integer 00165 @return The Avro status 00166 */ 00167 avro_status_t avro_int64 (AVRO * avro, int64_t * lp); 00168 00169 /** avro_string() is called to read/write a string 00170 @param avro The Avro handle 00171 @param str Pointer to the string 00172 @param maxlen The maximum length of the string to read/write 00173 @return The Avro status 00174 */ 00175 avro_status_t avro_string (AVRO * avro, char **str, int64_t maxlen); 00176 00177 /** avro_bytes() is called to read/write opaque bytes 00178 @param avro The Avro handle 00179 @param bytes The pointer to the bytes to read/write 00180 @param len Pointer to an integer which either (1) expresses the 00181 number of bytes you wish to encode or (2) is set on return to 00182 give the number of bytes decoded 00183 @param maxlen The maximum number of bytes to read/write 00184 @return The Avro status 00185 */ 00186 avro_status_t avro_bytes (AVRO * avro, char **bytes, int64_t * len, 00187 int64_t maxlen); 00188 00189 /** avro_bool() is called to read/write a boolean value 00190 @param avro The Avro handle 00191 @param bp Pointer to the boolean pointer 00192 @return The Avro status 00193 */ 00194 avro_status_t avro_bool (AVRO * avro, bool_t * bp); 00195 00196 /** avro_float() is called to read/write a float 00197 @param avro The Avro handle 00198 @param fp Pointer to the float 00199 @return The Avro status 00200 */ 00201 avro_status_t avro_float (AVRO * avro, float *fp); 00202 00203 /** avro_double() is called to read/write a double 00204 @param avro The Avro handle 00205 @param dp Pointer to the double 00206 @return The Avro status 00207 */ 00208 avro_status_t avro_double (AVRO * avro, double *dp); 00209 00210 /** @} */ 00211 00212 /** 00213 * @defgroup Compound AVRO Compound Type Serialization 00214 * @ingroup AVRO 00215 * @{ 00216 */ 00217 00218 /** avro_array() encodes/decodes an array of avro elements 00219 @param avro The Avro handle 00220 @param addrp Pointer to the array 00221 @param sizep Pointer to the number of elements 00222 @param maxsize The maximum number of Avro elements 00223 @param elsize The size in bytes of each element 00224 @param elproc The Avro routine to handle each element 00225 @return The Avro status 00226 */ 00227 avro_status_t avro_array (AVRO * avro, caddr_t * addrp, uint32_t * sizep, 00228 uint32_t maxsize, uint32_t elsize, 00229 avroproc_t elproc); 00230 00231 /** @} */ 00232 00233 00234 /* Useful for debugging */ 00235 void avro_dump_memory (AVRO * avro, FILE * fp); 00236 00237 avro_status_t avro_getint32_raw (AVRO * avro, int32_t * value); 00238 avro_status_t avro_putint32_raw (AVRO * avro, const int32_t value); 00239 avro_status_t avro_getint64_raw (AVRO * avro, int64_t * value); 00240 avro_status_t avro_putint64_raw (AVRO * avro, const int64_t value); 00241 00242 /** @} */ 00243 00244 #ifdef __cplusplus 00245 } 00246 #endif 00247 00248 #endif /* ifdef AVRO_H */
1.5.8