<interface name="encdec" short="encode and decode integers, floats, and strings to and from a wide variety of binary representations"> <comments> Copyright 2002 Michael B. Allen <mballen@erols.com> </comments> <include>encdec.h</include> <title>Encdec</title> <desc> These functions may be used to encode and decode C objects such as integers, floats, doubles, times, and internationalized strings to and from a wide variety of binary formats as they might appear in portable file formats or network messages. These encodings include 16, 34, and 64 bit big and little endian intergers, big and little endian IEEE754 float and double values, 6 time encodings, and the wide range of string encodings supported by libiconv. The functions are all designed to be ideal for in-situ decoding and encoding of complex formats. <p/> <b>The Encdec Java Class</b> <p/> See the <tt>src/Encdec.java</tt> file for equivalent methods in Java. Formats generated by these two implementations are compatible with two exceptions; 64 bit times encdoded using Java will be truncated to the 1 second resolution of the C <tt>time_t</tt> type and the Java methods do not provide string encoding/decoding methods because Java supports a wide variety of encodings natively. The "UTF-8" encoding is good for transferring strings between Java and C. Note the encoding identifier used with the <tt>String</tt> constructor and <tt>String.getBytes()</tt> method may need to be specified as "UTF8" without the hyphen. In-fact many of the identifiers are different so it will be necessary to look up the correct identifier in the Java i18n documentation. </desc> <group> <title>The <ident>FLD</ident> macro</title> <code> <title>The <ident>FLD</ident> macro</title> <pre> unsigned int FLD(i, m); </pre> <desc> The <ident>FLD</ident> macro is used to decode bit-fields. It returns an integer value representing the value occupying the bits in mask <tt>m</tt>. If for example the input is <tt>0xCBA98765</tt> and the mask is <tt>0x00FFFF00</tt> a value of <tt>0xA987</tt> will be returned. With basic register optimizations this is equivalent to the expression (<tt>0xCBA98765 >> 8) & 0xFFFF</tt>. Masks can be complex. The mask <tt>0x7F080</tt> is equivalent to <tt>(i >> 7) & 0xFE1</tt>. </desc> </code> </group> <group> <title>Integer functions</title> <desc>These functions should be used to encode and decode 16, 32, and 64 bit integers.</desc> <func name="enc_uint16be"> <pre>size_t enc_uint16be(uint16_t s, unsigned char *dst);</pre> <param name="s"/> <param name="dst"/> <desc> Encode a 16 bit integer in big endian order into the memory at <tt>dst</tt> and return the number of bytes written which is always 2. </desc> </func> <func name="enc_uint32be"> <pre>size_t enc_uint32be(uint32_t i, unsigned char *dst);</pre> <param name="i"/> <param name="dst"/> <desc> Encode a 32 bit integer in big endian order into the memory at <tt>dst</tt> and return the number of bytes written which is always 4. </desc> </func> <func name="enc_uint64be"> <pre>size_t enc_uint64be(uint64_t l, unsigned char *dst);</pre> <param name="l"/> <param name="dst"/> <desc> Encode a 64 bit integer in big endian order into the memory at <tt>dst</tt> and return the number of bytes written which is always 8. </desc> </func> <func name="enc_uint16le"> <pre>size_t enc_uint16le(uint16_t s, unsigned char *dst);</pre> <param name="s"/> <param name="dst"/> <desc> Encode a 16 bit integer in little endian order into the memory at <tt>dst</tt> and return the number of bytes written which is always 2. </desc> </func> <func name="enc_uint32le"> <pre>size_t enc_uint32le(uint32_t i, unsigned char *dst);</pre> <param name="i"/> <param name="dst"/> <desc> Encode a 32 bit integer in little endian order into the memory at <tt>dst</tt> and return the number of bytes written which is always 4. </desc> </func> <func name="enc_uint64le"> <pre>size_t enc_uint64le(uint64_t l, unsigned char *dst);</pre> <param name="l"/> <param name="dst"/> <desc> Encode a 64 bit integer in little endian order into the memory at <tt>dst</tt> and return the number of bytes written which is always 8. </desc> </func> <func name="dec_uint16be"> <pre>uint16_t dec_uint16be(const unsigned char *src);</pre> <param name="src"/> <desc> Return a 16 bit integer decoded in big endian byte order from 2 bytes of <tt>src</tt> memory. </desc> </func> <func name="dec_uint32be"> <pre>uint32_t dec_uint32be(const unsigned char *src);</pre> <param name="src"/> <desc> Return a 32 bit integer decoded in big endian byte order from 4 bytes of <tt>src</tt> memory. </desc> </func> <func name="dec_uint64be"> <pre>uint64_t dec_uint64be(const unsigned char *src);</pre> <param name="src"/> <desc> Return a 64 bit integer decoded in big endian byte order from 8 bytes of <tt>src</tt> memory. </desc> </func> <func name="dec_uint16le"> <pre>uint16_t dec_uint16le(const unsigned char *src);</pre> <param name="src"/> <desc> Return a 16 bit integer decoded in little endian byte order from 2 bytes of <tt>src</tt> memory. </desc> </func> <func name="dec_uint32le"> <pre>uint32_t dec_uint32le(const unsigned char *src);</pre> <param name="src"/> <desc> Return a 32 bit integer decoded in little endian byte order from 4 bytes of <tt>src</tt> memory. </desc> </func> <func name="dec_uint64le"> <pre>uint64_t dec_uint64le(const unsigned char *src);</pre> <param name="src"/> <desc> Return a 64 bit integer decoded in little endian byte order from 8 bytes of <tt>src</tt> memory. </desc> </func> </group> <group> <title>Time functions</title> <desc> These functions may be used to encode a wide variety of low-resolution time encodings. </desc> <func name="enc_time"> <pre>size_t enc_time(const time_t *timep, unsigned char *dst, int enc);</pre> <param name="timep"/> <param name="dst"/> <param name="enc"/> <desc> Encode the <ident>time_t</ident> object pointed to by <tt>timep</tt> into the memory at <tt>dst</tt> encoded in <tt>enc</tt> format. The following constants are valid <tt>enc</tt> parameters. <pre> Identifier Units Epoch Bits Endianess Use case ---------------------------------------------------------------- TIME_1970_SEC_32BE Seconds 1970 32 big time_t TIME_1970_SEC_32LE Seconds 1970 32 little time_t TIME_1904_SEC_32BE Seconds 1904 32 big MS TIME_1904_SEC_32LE Seconds 1904 32 little MS TIME_1601_NANOS_64BE Nanoseconds 1601 64 big MS TIME_1601_NANOS_64LE Nanoseconds 1601 64 little MS TIME_1970_MILLIS_64BE Milliseconds 1970 64 big Java TIME_1970_MILLIS_64LE Milliseconds 1970 64 little Java </pre> </desc> </func> <func name="dec_time"> <pre>time_t dec_time(const unsigned char *src, int enc);</pre> <param name="src"/> <param name="enc"/> <desc> Decode a return a <ident>time_t</ident> object encoded as <tt>enc</tt> in <tt>src</tt>. The constants listed in the <tt>enc_time</tt> description are valid <tt>enc</tt> parameters for this function as well. </desc> </func> </group> <group> <title>Floating point numbers</title> <func name="enc_floatle"> <pre>size_t enc_floatle(const float f, unsigned char *dst);</pre> <param name="f"/> <param name="dst"/> <desc> Encode a 32 bit real number <tt>f</tt> into <tt>dst</tt> in little endian IEEE754 format and return the number of bytes encoded which is always 4. </desc> </func> <func name="enc_doublele"> <pre>size_t enc_doublele(const double d, unsigned char *dst);</pre> <param name="d"/> <param name="dst"/> <desc> Encode a 64 bit real number <tt>d</tt> into <tt>dst</tt> in little endian IEEE754 format and return the number of bytes encoded which is always 8. </desc> </func> <func name="enc_floatbe"> <pre>size_t enc_floatbe(const float f, unsigned char *dst);</pre> <param name="f"/> <param name="dst"/> <desc> Encode a 32 bit real number <tt>f</tt> into <tt>dst</tt> in big endian IEEE754 format and return the number of bytes encoded which is always 4. </desc> </func> <func name="enc_doublebe"> <pre>size_t enc_doublebe(const double d, unsigned char *dst);</pre> <param name="d"/> <param name="dst"/> <desc> Encode a 64 bit real number <tt>d</tt> into <tt>dst</tt> in big endian IEEE754 format and return the number of bytes encoded which is always 8. </desc> </func> <func name="dec_floatle"> <pre>float dec_floatle(const unsigned char *src);</pre> <param name="src"/> <desc> Return a 32 bit real number decoded in little endian IEEE754 format from 4 bytes of <tt>src</tt> memory. </desc> </func> <func name="dec_doublele"> <pre>double dec_doublele(const unsigned char *src);</pre> <param name="src"/> <desc> Return a 64 bit real number decoded in little endian IEEE754 format from 8 bytes of <tt>src</tt> memory. </desc> </func> <func name="dec_floatbe"> <pre>float dec_floatbe(const unsigned char *src);</pre> <param name="src"/> <desc> Return a 32 bit real number decoded in big endian IEEE754 format from 4 bytes of <tt>src</tt> memory. </desc> </func> <func name="dec_doublebe"> <pre>double dec_doublebe(const unsigned char *src);</pre> <param name="src"/> <desc> Return a 64 bit real number decoded in big endian IEEE754 format from 4 bytes of <tt>src</tt> memory. </desc> </func> </group> <group> <title>Sting functions</title> <func name="enc_mbsncpy" wrap="true"> <pre>int enc_mbsncpy(const char *src, size_t sn, char **dst, size_t dn, int cn, const char *tocode);</pre> <param name="src"/> <param name="sn"/> <param name="dst"/> <param name="dn"/> <param name="cn"/> <desc> The <ident>enc_mbsncpy</ident> function encodes the multi-byte string at <tt>src</tt> into <tt>dst</tt> using the <tt>tocode</tt> encoding identifier. The <tt>tocode</tt> parameter can be one of the standard encoding identifiers such as "UTF-8", "KOI8-R", "ISO-8859-2", etc. See the libiconv documentation for a complete list: <p/> <a href="http://www.gnu.org/software/libiconv/">http://www.gnu.org/software/libiconv/</a> <p/> Specifically the <ident>enc_mbsncpy</ident> function; <ul> <li>does not read more than <tt>sn</tt> bytes of <tt>src</tt>,</li> <li>does not write to more than <tt>dn</tt> bytes of <tt>dst</tt>,</li> <li>does not convert more than <tt>cn</tt> characters,</li> <li>does not convert characters after a '\0' encountered in <tt>src</tt>,</li> <li>advances <tt>dst</tt> by the number of bytes encoded into <tt>dst</tt></li> <li>and returns the number of characters converted</li> </ul> </desc> </func> <func name="enc_mbscpy"> <pre>int enc_mbscpy(const char *src, char **dst, const char *tocode);</pre> <param name="src"/> <param name="dst"/> <param name="tocode"/> <desc> The <ident>enc_mbscpy</ident> function encodes the multi-byte string at <tt>src</tt> into <tt>dst</tt> using the <tt>tocode</tt> encoding identifier. The conversion stops when a '\0' character is encountered in <tt>src</tt>. This function is equivalent to <tt>enc_mbsncpy(src, INT_MAX, dst, INT_MAX, INT_MAX, tocode)</tt>. See <tt>enc_mbsncpy</tt> for details. </desc> </func> <func name="dec_mbsncpy" wrap="true"> <pre>size_t dec_mbsncpy(char **src, size_t sn, char *dst, size_t dn, int cn, const char *fromcode);</pre> <param name="src"/> <param name="sn"/> <param name="dst"/> <param name="dn"/> <param name="cn"/> <param name="fromcode"/> <desc> The <ident>dec_mbsncpy</ident> function decodes the string at <tt>src</tt> encoded as <tt>fromcode</tt> to the memory at <tt>dst</tt> as a locale dependent string (possibly UTF-8). The <tt>fromcode</tt> parameter can be one of the standard encoding identifiers such as "UTF-8", "KOI8-R", "ISO-8859-2", etc. See the libiconv documentation for a complete list: <p/> <a href="http://www.gnu.org/software/libiconv/">http://www.gnu.org/software/libiconv/</a> <p/> More specifically the <ident>dec_mbsncpy</ident> function; <ul> <li>does not read more than <tt>sn</tt> bytes of <tt>src</tt>,</li> <li>does not write to more than <tt>dn</tt> bytes of <tt>dst</tt>,</li> <li>does not convert more than <tt>cn</tt> characters,</li> <li>does not convert characters after a '\0' encountered in <tt>src</tt>,</li> <li>advances <tt>src</tt> by the number of bytes decoded,</li> <li>and returns the number of bytes written to <tt>dst</tt> unless a '\0' terminator is not encountered in <tt>src</tt> in which case one is artifically written to <tt>dst</tt> but not counted in the return value.</li> </ul> Additionally, if <tt>dst</tt> is NULL this function <ul> <li>does not write to <tt>dst</tt>,</li> <li>does not advance the <tt>src</tt> pointer,</li> <li>and returns the exact number of bytes required to encode a multi-byte string had <tt>dst</tt> not been NULL (i.e. for malloc). This includes the '\0' terminator regardless of wheather one was encountered in <tt>src</tt>.</li> </ul> </desc> </func> <func name="dec_mbscpy"> <pre>size_t dec_mbscpy(char **src, char *dst, const char *fromcode);</pre> <param name="src"/> <param name="dst"/> <param name="fromcode"/> <desc> The <ident>dec_mbscpy</ident> function decodes the string at <tt>src</tt> encoded as <tt>fromcode</tt> to the memory at <tt>dst</tt> as a locale dependent string (possibly UTF-8). The conversion stops when the character '\0' is encountered in <tt>src</tt>. This function is equivalent to <tt>dec_mbsncpy(src, INT_MAX, dst, INT_MAX, INT_MAX, fromcode);</tt>. See <tt>dec_mbscpy</tt> for details. </desc> </func> <func name="dec_mbsndup" wrap="true"> <pre>char *dec_mbsndup(char **src, size_t sn, size_t dn, int wn, const char *fromcode);</pre> <param name="src"/> <param name="sn"/> <param name="dn"/> <param name="wn"/> <param name="fromcode"/> <desc> The <ident>dec_mbsndup</ident> function decodes the string at <tt>src</tt> encoded as <tt>fromcode</tt> and returns a locale dependent string (possibly UTF-8) stored in memory allocated with <ident>malloc</ident>(3). This memory should be freed with <ident>free</ident>(3) when it will no longer be referenced. This function just calls <tt>dec_mbsncpy(src, sn, NULL, dn, wn, fromcode)</tt>, allocates the precise amount of memory, encodes the string in it with <tt>dec_mbsncpy(src, sn, dst, dn, wn, fromcode)</tt>, and returns the new string. </desc> </func> <func name="dec_mbsdup"> <pre>char *dec_mbsdup(char **src, const char *fromcode);</pre> <param name="src"/> <param name="fromcode"/> <desc> The <ident>dec_mbsdup</ident> function decodes the string at <tt>src</tt> encoded as <tt>fromcode</tt> and returns a locale dependent string (possibly UTF-8) stored in memory allocated with <ident>malloc</ident>(3). This memory should be freed with <ident>free</ident>(3) when it will no longer be referenced. This function is equivalent to <tt>dec_mbsndup(src, -1, -1, -1, fromcode)</tt>. See <tt>dec_mbsndup</tt> for details. </desc> </func> </group> </interface>