|
|
 |
 |
|
Detailed Description
BER/DER utility functions are provided for memory management, formatting output of ASN.1 messages, and error reporting. In many cases, these functions are closely coupled with the rt (runtime) series of common functions. The common functions provide common functionality shared between the BER/DER, PER, and XER runtime libraries. In many cases, these functions simply provide wrappers to the rt functions to maintain compatibility with existing versions of the ASN1C compiler.
|
Functions |
|
int | xu_verify_len (ASN1OCTET *msg_p) |
|
void * | xu_parse_mmbuf (ASN1OCTET **buf_p2, int *buflen_p, ASN1OCTET *start_p, int bufsiz) |
| void * | xu_malloc (ASN1CTXT *ctxt_p, int nbytes) |
| void | xu_alloc_array (ASN1CTXT *ctxt_p, ASN1SeqOf *seqOf_p, int recSize, int recCount) |
| void | xu_freeall (ASN1CTXT *ctxt_p) |
|
void | xu_octscpy_s (ASN1UINT *nocts_p, ASN1OCTET *data_p, char *cstr, char zterm) |
|
void | xu_octscpy_ss (ASN1OctStr *octStr_p, char *cstring, char zterm) |
|
void | xu_octscpy_d (ASN1CTXT *ctxt_p, ASN1UINT *nocts_p, ASN1ConstOctetPtr *data_p2, char *cstring, char zterm) |
|
void | xu_octscpy_ds (ASN1CTXT *ctxt_p, ASN1DynOctStr *octStr_p, char *cstring, char zterm) |
|
void | xu_octmcpy_s (ASN1OctStr *octStr_p, void *data_p, int datalen) |
|
void | xu_octmcpy_d (ASN1CTXT *ctxt_p, ASN1DynOctStr *octStr_p, void *data_p, int datalen) |
|
char * | xu_fetchstr (int numocts, char *data) |
|
int | xu_hexstrcpy (char *data, char *hstring) |
|
int | xu_binstrcpy (char *data, char *bstring) |
| int | xu_dump (ASN1OCTET *msgptr, ASN1DumpCbFunc cb, void *cbArg_p) |
| int | xu_fdump (FILE *file_p, ASN1OCTET *msgptr) |
| void | xu_hex_dump (ASN1OCTET *data, int numocts, ASN1OCTET hdrflg) |
|
void | xu_fmt_tag (ASN1TAG *tag_p, char *class_p, char *form_p, char *id_code) |
| char * | xu_fmt_tag2 (ASN1TAG *tag_p, char *bufp) |
|
char * | xu_fmt_contents (ASN1CTXT *ctxt_p, int len, int *count) |
| int | xu_error (ASN1CTXT *ctxt_p, int status, char *module, int lineno) |
| int | xu_addErrParm (ASN1CTXT *ctxt_p, char *errprm_p) |
| int | xu_addIntErrParm (ASN1CTXT *ctxt_p, int errParm) |
| int | xu_addUnsignedErrParm (ASN1CTXT *ctxt_p, unsigned int errParm) |
| int | xu_addTagErrParm (ASN1CTXT *ctxt_p, ASN1TAG errParm) |
| void | xu_perror (ASN1CTXT *ctxt_p) |
| void | xu_log_error (ASN1CTXT *ctxt_p, ASN1DumpCbFunc cb, void *cbArg_p) |
| char * | xu_fmtErrMsg (ASN1CTXT *ctxt_p, char *bufp) |
|
int | xu_fread (FILE *fp, ASN1OCTET *bufp, int bufsiz) |
|
void | xu_SaveBufferState (ASN1CTXT *pCtxt, ASN1BUFSAVE *pSavedInfo) |
|
void | xu_RestoreBufferState (ASN1CTXT *pCtxt, ASN1BUFSAVE *pSavedInfo) |
Function Documentation
| int xu_addErrParm |
( |
ASN1CTXT * |
ctxt_p, |
|
|
char * |
errprm_p |
|
) |
|
|
|
|
This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C. Users are encouraged to use the rtMem functions or associated macros for memory management.
- Parameters:
-
| ctxt_p | A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. This structure holds information on the last error that occurred during encoding or decoding. |
| errprm_p | A pointer to the typed error parameter. |
|
| int xu_addIntErrParm |
( |
ASN1CTXT * |
ctxt_p, |
|
|
int |
errParm |
|
) |
|
|
|
|
This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C. Users are encouraged to use the rtMem functions or associated macros for memory management.
- Parameters:
-
| ctxt_p | A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. This structure holds information on the last error that occurred during encoding or decoding. |
| errParm | The typed error parameter. |
|
| int xu_addTagErrParm |
( |
ASN1CTXT * |
ctxt_p, |
|
|
ASN1TAG |
errParm |
|
) |
|
|
|
|
This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C. Users are encouraged to use the rtMem functions or associated macros for memory management.
- Parameters:
-
| ctxt_p | A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. This structure holds information on the last error that occurred during encoding or decoding. |
| errParm | The typed error parameter. |
|
| int xu_addUnsignedErrParm |
( |
ASN1CTXT * |
ctxt_p, |
|
|
unsigned int |
errParm |
|
) |
|
|
|
|
This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C. Users are encouraged to use the rtMem functions or associated macros for memory management.
- Parameters:
-
| ctxt_p | A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. This structure holds information on the last error that occurred during encoding or decoding. |
| errParm | The typed error parameter. |
|
| void xu_alloc_array |
( |
ASN1CTXT * |
ctxt_p, |
|
|
ASN1SeqOf * |
seqOf_p, |
|
|
int |
recSize, |
|
|
int |
recCount |
|
) |
|
|
|
|
This function will allocate space for a given count of fixed size elements.
- Parameters:
-
| ctxt_p | A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. |
| seqOf_p | A pointer to a generic sequence of structure variables to receive the returned memory. This structure contains a record count and a data pointer element. The record count is populated with the recCount passed into the function. The data pointer is set to the value that is returned from the memory allocation function. |
| recSize | The number of bytes in one record in the array. |
| recCount | The number of records to allocate. A pointer to a generic sequence of structure variable to receive the returned memory. This structure contains a record count and data pointer element. The record count is populated with the recCount passed into the function. The data pointer is set to the value that is returned from the memory allocation function. |
|
| int xu_dump |
( |
ASN1OCTET * |
msgptr, |
|
|
ASN1DumpCbFunc |
cb, |
|
|
void * |
cbArg_p |
|
) |
|
|
|
|
This function dumps an encoded ASN.1 message to the standard output device or to another interface in a formatted display. The display includes, for each message component, message tag (class, form, and ID code) and data (in hexadecimal and character text formats).
This function is invoked for each line of text formatted from the given message. The formatted line is passed on the text_p argument. The cbArg_p argument allows a user to defined callback argument to be passed to the callback function. This argument is specified in the call to xu_dump.
Use of the callback function is optional. If dump to standard output (stdout) is desired, the argument should be specified as NULL (note: the macro XU_DUMP in asn1type.h can be used for this purpose).
- Parameters:
-
| *msgptr | A pointer to an encoded ASN.1 message. |
| cb | Callback function that gets invoked for each line of formatted output. For a dump to standard output (stdout), this parameter can be specified as NULL. |
| cbArg_p | Callback function argument will be passed to the callback function. |
- Returns:
- Status of the dump operation. Possible values are ASN_OK if decoding is successful or one of the negative status codes.
|
| int xu_error |
( |
ASN1CTXT * |
ctxt_p, |
|
|
int |
status, |
|
|
char * |
module, |
|
|
int |
lineno |
|
) |
|
|
|
|
This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C.
- Parameters:
-
| ctxt_p | A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. This structure holds information on the last error that occurred during encoding or decoding. |
| status | Error status code, |
| module | Name of the module (C or C++ source file) in which the module occurred. |
| lineno | The line at which the error occurred. |
|
| int xu_fdump |
( |
FILE * |
file_p, |
|
|
ASN1OCTET * |
msgptr |
|
) |
|
|
|
|
This function dumps an encoded ASN.1 message to a text file. The display includes, for each message component, message tag (class, form, and ID code), length, and data (in hexadecimal and character text formats).
- Parameters:
-
| *file_p | A text file pointer. |
| *msgptr | A pointer to an encoded ASN.1 message buffer. |
- Returns:
- Status of the dump operation. Possible values are ASN_OK if decoding is successful or one of the negative status codes.
|
| char* xu_fmt_tag2 |
( |
ASN1TAG * |
tag_p, |
|
|
char * |
bufp |
|
) |
|
|
|
|
This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C.
- Parameters:
-
| tag_p | Name of the variable. |
| bufp | The ASN.1 value. |
|
| char* xu_fmtErrMsg |
( |
ASN1CTXT * |
ctxt_p, |
|
|
char * |
bufp |
|
) |
|
|
|
|
This function provides parameterized error text corresponding to the last error recorded in the given ASN.1 context structure.
This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C. Users are encouraged to use the rtMem functions or associated macros for memory management.
- Parameters:
-
| ctxt_p | A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. This structure holds information on the last error that occurred during the encoding or the decoding. |
| bufp | A pointer to a text buffer in which the parameterized error message is to be formatted. The call is responsible for allocating space for this message. A 128-bit buffer should be sufficient for all messages. |
- Returns:
- A pointer to the formatted error message. This is the address of the buffer passed as the second input argument.
|
| void xu_freeall |
( |
ASN1CTXT * |
ctxt_p |
) |
|
|
|
|
This function frees up any dynamic memory allocated by the decode functions in the course of decoding a message. A call to this function releases all memory previously allocated using xu_malloc within the given context.
Note that the main logic for the xu_freeall function call is now in the rtMemFree function in the common runtime library. This function is still maintained for compatibility, but it acts as a pass-through to the rtMemFree function.
- Parameters:
-
| ctxt_p | A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. |
|
| void xu_hex_dump |
( |
ASN1OCTET * |
data, |
|
|
int |
numocts, |
|
|
ASN1OCTET |
hdrflg |
|
) |
|
|
|
|
This function dumps binary data in raw hexadecimal and character text formats. It can be used only to examine runtime library encode/decode functions input or output data. This function outputs data only to the standard output device.
This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C.
- Parameters:
-
| *data | A pointer to the start of the block of memory to be dumped. |
| numocts | The number of octets (bytes) to be dumped. |
| hdrflg | A Boolean variable indicating whether or not a head line should be dumped as the first line of the display. |
|
| void xu_log_error |
( |
ASN1CTXT * |
ctxt_p, |
|
|
ASN1DumpCbFunc |
cb, |
|
|
void * |
cbArg_p |
|
) |
|
|
|
|
This function is identical to xu_perror except it allows the error output to be redirected to another interface (for example, to a syslog-type logging daemon). This is accomplished through the callback function parameter. The prototype for this function is as follows: int callback_function (char* text_p, void* cbArg_p);
The text_p parameter contains the formatted error message. The cbArg_p argument allows a user defined callback argument to be passed to the callback function. This argument is specified in the call to xu_log_error.
The callback function is invoked twice on a call to xu_log_error. The first call contains the error message text indicating the module, line number, and status of the error. The second call contains the parameterized error message text.
This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C. Users are encouraged to use the rtMem functions or associated macros for memory management.
- Parameters:
-
| ctxt_p | The pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. This structure holds information on the last error that occurred during encoding or decoding. |
| cb | The callback function that gets invoked for each line of formatted error text. |
| cbArg_p | The callback function argument. |
|
| void* xu_malloc |
( |
ASN1CTXT * |
ctxt_p, |
|
|
int |
nbytes |
|
) |
|
|
|
|
This method provides a front-end to the C malloc function to allocate dynamic memory for decoded message components. The following ASN.1 constructs may require allocation of dynamic memory within the generated C structure:
- BIT STRING
- OCTET STRING
- SEQUENCE OF
- SET OF
- ANY
This function uses a nibble memory management scheme to make memory allocations more efficient. On an initial allocation request, malloc will be called to obtain a large block of memory. This memory will then be subdivided as subsequent calls to this function are made. When the block is expired, another call to malloc will be made to allocate another large block and then subdivision process repeated. All large memory blocks allocated from within the context are freed when xu_freeall function is called.
Note that the main logic for the xu_malloc function is now in the rtMemAlloc function in the common runtime library. This function is still maintained for compatibility purposes, but it acts as a pass through to the rtMemAlloc function.
- Parameters:
-
| ctxt_p | A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. |
| nbytes | The number of bytes to allocate. |
- Returns:
- A pointer to the allocated dynamic memory block. This will be null if a free block of the requested size does not exist.
|
| void xu_perror |
( |
ASN1CTXT * |
ctxt_p |
) |
|
|
|
|
The function prints information about the last recorded error within the given ASN.1 context structure. The display includes information on the module that generated the error, the source code line number, the status, and a parameterized error message. This function is considered depreciated and is only being maintained to provide backward compatibility with older versions of ASN1C. Users are encouraged to use the rtMem functions or associated macros for memory management.
- Parameters:
-
| ctxt_p | A pointer to a context structure. This provides a storage area for the function to store all working variables that must be maintained between function calls. This structure holds information on the last error that occurred during encoding or decoding. |
|
|
This document may be distributed in any form, electronic
or otherwise, provided that it is distributed in its entirety
and that the copyright and this notice are included.
|
This file was last modified on
8 Sep 2005.
ASN1C BER Runtime, ASN1C v5.8x |
|
