189 lines
7.9 KiB
C
189 lines
7.9 KiB
C
|
|
/*
|
|
|
|
Arbitrary Attribute Interchange Protocol , AAIP version 0.2
|
|
Demonstration program for encoding and decoding EA and ACL.
|
|
|
|
See http://libburnia-project.org/wiki/AAIP
|
|
|
|
test/aaip_0.2.h - Public declarations
|
|
|
|
*/
|
|
|
|
#ifndef Aaip_h_is_includeD
|
|
#define Aaip_h_is_includeD yes
|
|
|
|
|
|
/* --------------------------------- Encoder ---------------------------- */
|
|
|
|
/* Convert an array of Arbitrary Attributes into a series of AAIP fields.
|
|
@param aa_name The 2 byte SUSP Signature Word of the fields
|
|
@param num_attrs Number of attributes
|
|
@param names Array of pointers to 0 terminated name strings
|
|
@param attr_lengths Array of byte lengths for each attribute payload
|
|
@param attrs Array of pointers to the attribute payload bytes
|
|
@param result_len Number of bytes in the resulting SUSP field string
|
|
@param result *result will point to the start of the result string.
|
|
This is malloc() memory which needs to be freed when
|
|
no longer needed
|
|
@param flag Bitfield for control purposes
|
|
bit0= set CONTINUE bit of last AA field to 1
|
|
@return >0 is the number of SUSP fields generated,
|
|
0 means error
|
|
*/
|
|
unsigned int aaip_encode(char aa_name[2],
|
|
unsigned int num_attrs, char **names,
|
|
size_t *attr_lengths, char **attrs,
|
|
size_t *result_len, unsigned char **result, int flag);
|
|
|
|
|
|
/* >>> Encoder for ACLs */;
|
|
|
|
|
|
/* --------------------------------- Decoder ---------------------------- */
|
|
|
|
/*
|
|
The AAIP decoder avoids the use of dynamic memory. It rather provides a
|
|
stateful decoding context with a small buffer which delivers results to
|
|
caller provided memory locations.
|
|
This may be done stream-like via the Component Level Interface or to
|
|
fixly sized storage for name and value via the Pair Level Interface.
|
|
*/
|
|
|
|
|
|
/* The AAIP decoder context.
|
|
*/
|
|
struct aaip_state;
|
|
|
|
|
|
/* Obtain the size in bytes of an aaip_state object.
|
|
*/
|
|
size_t aaip_sizeof_aaip_state(void);
|
|
|
|
|
|
/* Initialize a AAIP decoder context.
|
|
This has to be done before the first AA field of a node is processed.
|
|
The caller has to provide the storage of the struct aaip_state.
|
|
*/
|
|
int aaip_init(struct aaip_state *aaip, char aa_name[2], int flag);
|
|
|
|
|
|
/* ------------------------------------------------------------------------- */
|
|
/* Component Level Interface
|
|
Provides support for unlimited component size but demands the caller
|
|
to have a growing storage facility resp. to do own oversize handling.
|
|
|
|
This interface expects moderatly sized input pieces and will hand out
|
|
moderately sized result pieces. The number of ransactions is virtually
|
|
unlimited.
|
|
*/
|
|
|
|
/* Submit small data chunk for decoding.
|
|
The return value will tell whether data are pending for being fetched.
|
|
@param aaip The AAIP decoder context
|
|
@param data Not more than 2048 bytes input for the decoder
|
|
@param num_data Number of bytes in data
|
|
0 inquires the buffer status avoiding replies <= 0
|
|
@param ready_bytes Number of decoded bytes ready for delivery
|
|
@param flag Bitfield for control purposes
|
|
@return -1= non-AA field detected
|
|
*ready_bytes gives number of consumed bytes in data
|
|
0= cannot accept data because buffer full
|
|
1= no component record complete, submit more data
|
|
2= component record complete, may be delivered
|
|
3= component complete, may be delivered
|
|
4= no component available, no more data expected, done
|
|
*/
|
|
int aaip_submit_data(struct aaip_state *aaip,
|
|
unsigned char *data, size_t num_data,
|
|
size_t *ready_bytes, int flag);
|
|
|
|
|
|
/* Fetch the available part of current component.
|
|
The return value will tell whether it belongs to name or to value and
|
|
whether that name or value is completed now.
|
|
@param aaip The AAIP decoder context
|
|
@param result Has to point to storage for the component data
|
|
@param result_size Gives the amount of provided result storage
|
|
@param num_result Will tell the number of fetched result bytes
|
|
@param flag Bitfield for control purposes
|
|
bit0= discard data rather than copying to result
|
|
@return -2 = insufficient result_size
|
|
-1 = no data ready for delivery
|
|
0 = result holds the final part of a name
|
|
1 = result holds an intermediate part of a name
|
|
2 = result holds the final part of a value
|
|
3 = result holds an intermediate part of a value
|
|
*/
|
|
int aaip_fetch_data(struct aaip_state *aaip,
|
|
char *result, size_t result_size, size_t *num_result,
|
|
int flag);
|
|
|
|
|
|
/* Skip the current component and eventually the following value component.
|
|
This has to be called if fetching of a component shall be aborted
|
|
but the next component resp. pair shall be fetchable again.
|
|
aaip_submit_data() will not indicate readiness for fetching until all
|
|
bytes of the skipped components are submitted. Those bytes get discarded.
|
|
@param aaip The AAIP decoder context
|
|
@param flag Bitfield for control purposes
|
|
bit0= do not skip value if current component is name
|
|
@return <=0 error , 1= now in skip state, 2= not in skip state
|
|
*/
|
|
int aaip_skip_component(struct aaip_state *aaip, int flag);
|
|
|
|
|
|
/* ------------------------------------------------------------------------- */
|
|
/* Pair Level Interface
|
|
Provides support for names and values of limited size. The limits are
|
|
given by the caller who has to provide the storage for name and value.
|
|
|
|
This interface expects moderatly sized input pieces.
|
|
The number of input transcations is virtually unlimited.
|
|
The number of pair transactions after aaip_init() should be limited
|
|
to 4 billion.
|
|
*/
|
|
|
|
|
|
/* Accept raw input data and collect a pair of name and value.
|
|
The return value iwill indicate whether the pair is complete, whether more
|
|
pairs are complete or whether more data are desired. No input data will be
|
|
accepted as long as complete pairs are pending. The end of the attribute
|
|
list will be indicated.
|
|
@param aaip The AAIP decoder context
|
|
@param data The raw data to decode
|
|
@param num_data Number of data bytes provided
|
|
@param consumed Returns the number of consumed data bytes
|
|
@param name Buffer to build the name string
|
|
@param name_size Maximum number of bytes in name
|
|
@param name_fill Holds the current buffer fill of name
|
|
@param value Buffer to build the value string
|
|
@param value_size Maximum number of bytes in value
|
|
@param value_fill Holds the current buffer fill of value
|
|
@param flag Bitfield for control purposes - submit 0 for now
|
|
@return <0 error
|
|
0 data not accepted, first fetch pending pairs with num_data == 0
|
|
1 name and value are not valid yet, submit more data
|
|
2 name and value are valid, submit more data
|
|
3 name and value are valid, pairs pending, fetch with num_data == 0
|
|
4 name and value are valid, no more data expected
|
|
5 name and value are not valid, no more data expected
|
|
|
|
*/
|
|
int aaip_decode_pair(struct aaip_state *aaip,
|
|
unsigned char *data, size_t num_data, size_t *consumed,
|
|
char *name, size_t name_size, size_t *name_fill,
|
|
char *value, size_t value_size, size_t *value_fill,
|
|
int flag);
|
|
|
|
|
|
/* Inquire the number of pairs which were skipped because being oversized.
|
|
@param aaip The AAIP decoder context
|
|
@param flag Bitfield for control purposes - submit 0 for now
|
|
@return The number of pairs skipped since aaip_init()
|
|
*/
|
|
unsigned int aaip_get_pairs_skipped(struct aaip_state *aaip, int flag);
|
|
|
|
#endif /* ! Aaip_h_is_includeD */
|
|
|