Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NAL_DECODE_UINT32(2)		   distcache		  NAL_DECODE_UINT32(2)

NAME
       NAL_decode_uint32, NAL_decode_uint16, NAL_decode_char, NAL_decode_bin,
       NAL_encode_uint32, NAL_encode_uint16, NAL_encode_char, NAL_encode_bin -
       libnal serialisation functions

SYNOPSIS
	#include <libnal/nal.h>

	int NAL_decode_uint32(const unsigned char **bin, unsigned int *bin_len,
			      unsigned long *val);
	int NAL_decode_uint16(const unsigned char **bin, unsigned int *bin_len,
			      unsigned int *val);
	int NAL_decode_char(const unsigned char	**bin, unsigned	int *bin_len,
			    unsigned char *val);
	int NAL_decode_bin(const unsigned char **bin, unsigned int *bin_len,
			   unsigned char *val, unsigned	int val_len);

	int NAL_encode_uint32(unsigned char **bin, unsigned int	*bin_len,
			      const unsigned long val);
	int NAL_encode_uint16(unsigned char **bin, unsigned int	*bin_len,
			      const unsigned int val);
	int NAL_encode_char(unsigned char **bin, unsigned int *bin_len,
			    const unsigned char	val);
	int NAL_encode_bin(unsigned char **bin,	unsigned int *bin_len,
			   const unsigned char *val, const unsigned int	val_len);

DESCRIPTION
       NAL_decode_uint32(), NAL_decode_uint16(), and NAL_decode_char() attempt
       to parse	different sized	integer	values from the	data pointed to	by
       *bin (both bin and bin_len are passed by	reference). If bin_len indi-
       cates there is sufficient data to successfully parse a value, then the
       value will be stored in val, *bin will be incremented to	point to the
       next unparsed byte of data, and *bin_len	will be	decremented to indi-
       cate how	much unparsed data remains.

       NAL_decode_bin()	follows	the semantics of the other decode functions
       except that it decodes a	block of binary	data of	length val_len.

       NAL_encode_uint32(), NAL_encode_uint16(), and NAL_encode_char() attempt
       to encode different sized integer values	to the located pointed to by
       *bin (again, both bin and bin_len are passed by reference). If bin_len
       indicates there is sufficient room to successfully encode a value, val
       will be stored at *bin, *bin will be incremented	to point to the	next
       unused byte of storage, and *bin_len will be decremented	to indicate
       how much	unused storage remains.

       NAL_encode_bin()	follows	the semantics of the other encode functions
       except that it encodes a	block of binary	data of	length val_len.

RETURN VALUES
       All the encode and decode functions return non-zero for success or zero
       for failure. On failure,	bin and	bin_len	are left unchanged.

NOTES
       The reason for passing bin and bin_len by reference to all these	func-
       tions is	to allow (de)serialisation of complex structures to be built
       up more easily without unnecessary work by the caller. The return value
       still indicates whether an encoding or decoding was successful, but the
       caller will not need to increment bin nor decrement bin_len after suc-
       cess before continuing to encode	or decode further data.

EXAMPLES
       Assume we wish to pass a	data structure between applications running on
       different machines (and potentially on different	architectures),	and
       the data	structure is defined as	follows;

	#define	MAX_DATA_SIZE 4096
	typedef	struct st_some_data_t {
	    unsigned char is_active;	  /* boolean */
	    unsigned char buffer[MAX_DATA_SIZE];
	    unsigned int buffer_used;
	} some_data_t;

       We could	define two functions for encoding and decoding an object of
       this type such that they	could be serialised and	transferred over a
       connection. The most elegant way	to build serialisation of objects is
       to create functions that	use the	same form of prototype as the libnal
       serialisation functions,	this way serialisation of complex objects can
       be performed recursively	by serialisation of aggregated types. Although
       the built-in libnal serialisation functions leave bin and bin_len un-
       changed on failure, it is generally not worth bothering to preserve
       this property at	higher-levels -	these examples do not attempt this.

       An encoding function would thus look like;

	int encode_some_data(unsigned char **bin, unsigned int *bin_len,
			     const some_data_t *val)
	{
	    if(
		    /* Encode the "is_active" boolean */
		    !NAL_encode_char(bin, bin_len, val->is_active) ||
		    /* Encode the used data */
		    !NAL_encode_uint16(bin, bin_len, val->buffer_used) ||
		    ((val->buffer_used > 0) &&
		    !NAL_encode_bin(bin, bin_len, val->buffer, val->buffer_used)))
		return 0;
	    return 1;
	}

       Note that other types that include some_data_t objects could implement
       serialisation using encode_some_data() in the same way that en-
       code_some_data()	uses the lower-level libnal functions. A corresponding
       decode function follows.

	int decode_some_data(const unsigned char **bin,	unsigned int *bin_len,
			     some_data_t *val)
	{
	    if(
		    /* Decode the "is_active" boolean */
		    !NAL_decode_char(bin, bin_len, &val->is_active) ||
		    /* Decode the used data */
		    !NAL_decode_uint16(bin, bin_len, &val->buffer_used)	||
		    /* [TODO: check 'val->buffer_used' is acceptable here] */
		    ((val->buffer_used > 0) &&
		    !NAL_decode_bin(bin, bin_len, val->buffer, val->buffer_used)))
		return 0;
	    return 1;
	}

       The above examples would	be simpler still if a wrapper function were
       first written to	serialise length-prefixed blocks of data. Such func-
       tions are not included in libnal	because	they can vary on what range of
       sizes are appropriate, what size	encoding to use	for a length-prefix,
       whether dynamic allocation should be used on decoding, etc. The above
       examples	use a static buffer and	encode the length prefix as 16-bits.

SEE ALSO
       NAL_ADDRESS_new(2) - Functions for the NAL_ADDRESS type.

       NAL_CONNECTION_new(2) - Functions for the NAL_CONNECTION	type.

       NAL_LISTENER_new(2) - Functions for the NAL_LISTENER type.

       NAL_SELECTOR_new(2) - Functions for the NAL_SELECTOR type.

       distcache(8) - Overview of the distcache	architecture.

       http://www.distcache.org/ - Distcache home page.

AUTHOR
       This toolkit was	designed and implemented by Geoff Thorpe for Crypto-
       graphic Appliances Incorporated.	Since the project was released into
       open source, it has a home page and a project environment where devel-
       opment, mailing lists, and releases are organised. For problems with
       the software or this man	page please check for new releases at the
       project web-site	below, mail the	users mailing list described there, or
       contact the author at geoff@geoffthorpe.net.

       Home Page: http://www.distcache.org

1.4.5				  2004.03.23		  NAL_DECODE_UINT32(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | NOTES | EXAMPLES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=NAL_decode_uint32&sektion=2&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help