00001 00002 /* 00003 00004 Arbitrary Attribute Interchange Protocol , AAIP version 0.2 00005 Demonstration program for encoding and decoding EA and ACL. 00006 00007 See http://libburnia-project.org/wiki/AAIP 00008 00009 test/aaip_0.2.h - Public declarations 00010 00011 */ 00012 00013 #ifndef Aaip_h_is_includeD 00014 #define Aaip_h_is_includeD yes 00015 00016 00017 /* --------------------------------- Encoder ---------------------------- */ 00018 00019 /* Convert an array of Arbitrary Attributes into a series of AAIP fields. 00020 @param aa_name The 2 byte SUSP Signature Word of the fields 00021 @param num_attrs Number of attributes 00022 @param names Array of pointers to 0 terminated name strings 00023 @param attr_lengths Array of byte lengths for each attribute payload 00024 @param attrs Array of pointers to the attribute payload bytes 00025 @param result_len Number of bytes in the resulting SUSP field string 00026 @param result *result will point to the start of the result string. 00027 This is malloc() memory which needs to be freed when 00028 no longer needed 00029 @param flag Bitfield for control purposes 00030 bit0= set CONTINUE bit of last AA field to 1 00031 @return >0 is the number of SUSP fields generated, 00032 0 means error 00033 */ 00034 unsigned int aaip_encode(char aa_name[2], 00035 unsigned int num_attrs, char **names, 00036 size_t *attr_lengths, char **attrs, 00037 size_t *result_len, unsigned char **result, int flag); 00038 00039 00040 /* Convert an ACL from long text form into the value of an Arbitrary 00041 Attribute. According to AAIP 0.2 this value is to be stored together with 00042 an empty name. 00043 @param acl_text The ACL in long text form 00044 @param result_len Number of bytes in the resulting value 00045 @param result *result will point to the start of the result string. 00046 This is malloc() memory which needs to be freed when 00047 no longer needed 00048 @param flag Bitfield for control purposes 00049 bit0= count only 00050 bit1= use numeric qualifiers rather than names 00051 @return >0 means ok 00052 0 means error 00053 */ 00054 int aaip_encode_acl(char *acl_text, 00055 size_t *result_len, unsigned char **result, int flag); 00056 00057 00058 /* --------------------------------- Decoder ---------------------------- */ 00059 00060 /* 00061 The AAIP decoder avoids the use of dynamic memory. It rather provides a 00062 stateful decoding context with a small buffer which delivers results to 00063 caller provided memory locations. 00064 This may be done stream-like via the Component Level Interface or to 00065 fixly sized storage for name and value via the Pair Level Interface. 00066 */ 00067 00068 00069 /* The AAIP decoder context. 00070 */ 00071 struct aaip_state; 00072 00073 00074 /* Obtain the size in bytes of an aaip_state object. 00075 */ 00076 size_t aaip_sizeof_aaip_state(void); 00077 00078 00079 /* Initialize a AAIP decoder context. 00080 This has to be done before the first AA field of a node is processed. 00081 The caller has to provide the storage of the struct aaip_state. 00082 */ 00083 int aaip_init(struct aaip_state *aaip, char aa_name[2], int flag); 00084 00085 00086 /* ------------------------------------------------------------------------- */ 00087 /* Component Level Interface 00088 Provides support for unlimited component size but demands the caller 00089 to have a growing storage facility resp. to do own oversize handling. 00090 00091 This interface expects moderatly sized input pieces and will hand out 00092 moderately sized result pieces. The number of ransactions is virtually 00093 unlimited. 00094 */ 00095 00096 /* Submit small data chunk for decoding. 00097 The return value will tell whether data are pending for being fetched. 00098 @param aaip The AAIP decoder context 00099 @param data Not more than 2048 bytes input for the decoder 00100 @param num_data Number of bytes in data 00101 0 inquires the buffer status avoiding replies <= 0 00102 @param ready_bytes Number of decoded bytes ready for delivery 00103 @param flag Bitfield for control purposes 00104 @return -1= non-AA field detected 00105 *ready_bytes gives number of consumed bytes in data 00106 0= cannot accept data because buffer full 00107 1= no component record complete, submit more data 00108 2= component record complete, may be delivered 00109 3= component complete, may be delivered 00110 4= no component available, no more data expected, done 00111 */ 00112 int aaip_submit_data(struct aaip_state *aaip, 00113 unsigned char *data, size_t num_data, 00114 size_t *ready_bytes, int flag); 00115 00116 00117 /* Fetch the available part of current component. 00118 The return value will tell whether it belongs to name or to value and 00119 whether that name or value is completed now. 00120 @param aaip The AAIP decoder context 00121 @param result Has to point to storage for the component data 00122 @param result_size Gives the amount of provided result storage 00123 @param num_result Will tell the number of fetched result bytes 00124 @param flag Bitfield for control purposes 00125 bit0= discard data rather than copying to result 00126 @return -2 = insufficient result_size 00127 -1 = no data ready for delivery 00128 0 = result holds the final part of a name 00129 1 = result holds an intermediate part of a name 00130 2 = result holds the final part of a value 00131 3 = result holds an intermediate part of a value 00132 */ 00133 int aaip_fetch_data(struct aaip_state *aaip, 00134 char *result, size_t result_size, size_t *num_result, 00135 int flag); 00136 00137 00138 /* Skip the current component and eventually the following value component. 00139 This has to be called if fetching of a component shall be aborted 00140 but the next component resp. pair shall be fetchable again. 00141 aaip_submit_data() will not indicate readiness for fetching until all 00142 bytes of the skipped components are submitted. Those bytes get discarded. 00143 @param aaip The AAIP decoder context 00144 @param flag Bitfield for control purposes 00145 bit0= do not skip value if current component is name 00146 @return <=0 error , 1= now in skip state, 2= not in skip state 00147 */ 00148 int aaip_skip_component(struct aaip_state *aaip, int flag); 00149 00150 00151 /* ------------------------------------------------------------------------- */ 00152 /* Pair Level Interface 00153 Provides support for names and values of limited size. The limits are 00154 given by the caller who has to provide the storage for name and value. 00155 00156 This interface expects moderatly sized input pieces. 00157 The number of input transcations is virtually unlimited. 00158 The number of pair transactions after aaip_init() should be limited 00159 to 4 billion. 00160 */ 00161 00162 00163 /* Accept raw input data and collect a pair of name and value. 00164 The return value iwill indicate whether the pair is complete, whether more 00165 pairs are complete or whether more data are desired. No input data will be 00166 accepted as long as complete pairs are pending. The end of the attribute 00167 list will be indicated. 00168 @param aaip The AAIP decoder context 00169 @param data The raw data to decode 00170 @param num_data Number of data bytes provided 00171 @param consumed Returns the number of consumed data bytes 00172 @param name Buffer to build the name string 00173 @param name_size Maximum number of bytes in name 00174 @param name_fill Holds the current buffer fill of name 00175 @param value Buffer to build the value string 00176 @param value_size Maximum number of bytes in value 00177 @param value_fill Holds the current buffer fill of value 00178 @param flag Bitfield for control purposes - submit 0 for now 00179 @return <0 error 00180 0 data not accepted, first fetch pending pairs with num_data == 0 00181 1 name and value are not valid yet, submit more data 00182 2 name and value are valid, submit more data 00183 3 name and value are valid, pairs pending, fetch with num_data == 0 00184 4 name and value are valid, no more data expected 00185 5 name and value are not valid, no more data expected 00186 00187 */ 00188 int aaip_decode_pair(struct aaip_state *aaip, 00189 unsigned char *data, size_t num_data, size_t *consumed, 00190 char *name, size_t name_size, size_t *name_fill, 00191 char *value, size_t value_size, size_t *value_fill, 00192 int flag); 00193 00194 00195 /* Inquire the number of pairs which were skipped because being oversized. 00196 @param aaip The AAIP decoder context 00197 @param flag Bitfield for control purposes - submit 0 for now 00198 @return The number of pairs skipped since aaip_init() 00199 */ 00200 unsigned int aaip_get_pairs_skipped(struct aaip_state *aaip, int flag); 00201 00202 00203 /* Convert an AAIP 0.2 ACL attribute value into the long text form of ACL. 00204 @param data The raw data to decode 00205 @param num_data Number of data bytes provided 00206 @param consumed Returns the number of consumed data bytes 00207 @param acl_text Will be filled with ACL long text form 00208 @param acl_text_size Maximum number of bytes to be written to acl_text 00209 @param acl_text_fill Will return the number of bytes in acl_text 00210 @param flag Bitfield for control purposes 00211 bit0= count only, do not really produce bytes: 00212 acl_text will not be touched, 00213 acl_text_size will be ignored, 00214 *acl_text_fill will return the counted number 00215 bit1= expected is a default ACL (see return value 2) 00216 @return 1 success 00217 2 success, begin of default/access ACL encountered, 00218 submit data + *consumed for access/default ACL 00219 -1 error with reading of qualifier 00220 -2 error with writing of ACL text line 00221 -3 version mismatch 00222 -4 unknown tag type encountered 00223 */ 00224 int aaip_decode_acl(unsigned char *data, size_t num_data, size_t *consumed, 00225 char *acl_text, size_t acl_text_size, 00226 size_t *acl_text_fill, int flag); 00227 00228 00229 #endif /* ! Aaip_h_is_includeD */ 00230
1.5.6