ASN.1 C Runtime Library API header file asnrt.h provides the following functionality in a manner that is intuitive and easy to use:
This API represents a simple memory allocation system. These functions allow dynamic memory allocation. The users are advised to override these functions if the default generated implements doesn't fit their need.
This function allocates a block (nitems * size) bytes and clears it to 0.
Prototype:
void* asn_alloc(size_t nitems, size_t size)Parameters:
nitems - The multiplier of size
.
size - the number of bytes wanted.
Return: A pointer to the newly allocated block on success, otherwise NULL is return.
This function deallocates a memory block allocated by a previous call to asn_alloc(). If the block pointer parameter is NULL, it immediately returns.
Prototype:
asn_free(void* block)Parameters:
block - Points to a memory block previously obtained by calling asn_alloc().Return:
None
This function copies a block of n bytes from src to dest.
Prototype:
asn_memcpy(void* dest, const void* src, size_t n)Parameters:
dest - Points to the destination memory block. src - Points to the source memory block. n - Number of bytes to copy.Return:
The destination memory block
This function compares the first n bytes of the blocks s1 and s2 as unsigned chars.
Prototype:
asn_memcmp(const void* s1, const void* s2, size_t n)Parameters:
s1 - Points to the memory block 1. s1 - Points to the memory block 2. n - Number of bytes to compare.Return:
<0 if s1<s2; =0 if s1==s2; >0 if s1>s2
This function performs a binary search for the value key in a table (array) of nelem elements in memory.
Prototype:
void* asn_bsearch(const void* key, const void* base, size_t nelem, size_t width, int (*fcmp)(const void*, const void*))Parameters:
key - The item to be searched for (the search key). base - The base (0th element) of the search table. nelem - The number of entries in the table. width - The number of bytes in each entry. fcmp - A user-defined comparison routine that compares two items and returns a value based on the comparison.Return:
The address of the first entry in the table that matches the search key on success; 0 (No match) on failure
This API enables encoding/decoding routines to interface with I/O stream.
This is a stream reader callback function using by the read_to_buffer() function to read a byte from input stream.
Prototype:
typedef int (*ReadByte)(void)Parameters:
NoneReturn:
0~255 on success, -1 on end of stream.
This is a stream writer callback function using by the flush_buffer() function to write a byte to output stream.
Prototype:
typedef void (*WriteByte)(char byte)Parameters:
byte - The byte to write to output stram.Return:
None
This is a string writer callback function using by the print routine to print almost anything. This function pointer is compatible with the printf() function.
Prototype:
typedef int Print(const char *__format, ...)Parameters:
__format - The string format. ... - variable argumentsReturn:
number of bytes output on success, -1 otherwise
This function read I/O input stream to the buffer via a reader callback.
Prototype:
void read_to_buffer(Buffer* buffer, ReadByte read_byte)Parameters:
buffer - The buffer to load into. read_byte - The reader callback.Return:
None
This is a string writer callback function using by the print routine to print almost anything. This function pointer is compatible with the printf() function.
Prototype:
void flush_buffer(Buffer* buffer, WriteByte write_byte)Parameters:
buffer - The buffer to flush. write_byte - The writer callbackReturn:
None
This API enables allocation/deallocation working buffer. If the buffer is created by calling wrapBuffer(), it must be destroyed by calling asn_free(); If the buffer is created by calling allocBuffer(), it must be destroyed by calling freeBuffer(). In most cases, wrapBuffer() is called when decoding, allocBuffer() is called when encoding.
This function wraps a byte array into a buffer. The new buffer will be backed by the given byte array; that is, modifications to the buffer will cause the array to be modified and vice versa. For Basic Encoding Rules, the new buffer's capacity and limit will be numBytes, and for Pack Encoding Rules, the new buffer's capacity and limit will be numBytes*8.
Prototype:
Buffer* wrapBuffer(char* array, unsigned long numBytes, char encodingRules)Parameters:
array - The bytes array to wrap. numBytes - The length of this array. encodingRules - The encoding rules.Return:
The newly create buffer, NULL if fail to do so.
This function allocates a new buffer. For Basic Encoding Rules, the new buffer's capacity and limit will be numBytes, and for Pack Encoding Rules, the new buffer's capacity and limit will be numBytes*8.
Prototype:
Buffer* allocBuffer(unsigned long numBytes, boolean autoExpand, char encodingRules)Parameters:
numBytes - The length of this array. autoExpand - Whether or not this buffer should auto-expand its array size when overflow in encoding. encodingRules - The encoding rules.Return:
The newly create buffer, NULL if fail to do so.
This function frees a buffer. The memory of byte array and the buffer itself will be freed. Caution: if this buffer is create by wrapBuffer(), it must be deallocated by calling asn_free() instead of this routine.
Prototype:
void freeBuffer(Buffer* buffer)Parameters:
buffer - The buffer to free.Return:
None
This API provides generic encoding/decoding routines.
This function encodes the object with encoding rules specified in the buffer.
Prototype:
int encode_object(Buffer* buffer, void* object, Type* type)Parameters:
buffer - The working buffer. object - The object to encode. type - The metadata type.Return:
zero if encoding is successful, non-zero error code otherwise
This function decodes the object with encoding rules specified in the buffer.
Prototype:
int decode_object(Buffer* buffer, void* object, Type* type)Parameters:
buffer - The working buffer. object - The object to decode. type - The metadata type.Return:
zero if encoding is successful, non-zero error code otherwise
This API provides generic free routine.
This function frees the object content (memory allocated dynamically).
Prototype:
void free_object(void* object, Type* type)Parameters:
object - The object to free. type - The metadata type.Return:
None
This API provides generic print routine.
This function print the object content with printer callback.
Prototype:
void print_object(void* object, Type* type, Print print)Parameters:
object - The object to print. type - The metadata type. print - The printer callback.Return:
None
Whenever encoding/decoding routine return error codes, the more detail context informations are stored in context member of the buffer. The struct for the context is:
typedef struct { jmp_buf jumper; char* file_name; int line_number; unsigned long position; void* data; int extval; } Context;which contains source file name, line number, and the buffer's position, these informations are useful in diagnosing issues.