cgul_crc16.h File Reference

CRC-16. More...

#include "cgul_common.h"
#include "cgul_exception.h"

Include dependency graph for cgul_crc16.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef typedefCGUL_BEGIN_C struct cgul_crc16 *	cgul_crc16_t

Functions
CGUL_EXPORT cgul_crc16_t	cgul_crc16__new (cgul_exception_t *cex, unsigned short g, unsigned short init, unsigned short final_xor, int reflected)
CGUL_EXPORT cgul_crc16_t	cgul_crc16__new_appends_size (cgul_exception_t *cex, unsigned short g, unsigned short init, unsigned short final_xor, int reflected, size_t size_xor)
CGUL_EXPORT void	cgul_crc16__delete (cgul_crc16_t crc)
CGUL_EXPORT void	cgul_crc16__assign (cgul_exception_t *cex, cgul_crc16_t lhs, cgul_crc16_t rhs)
CGUL_EXPORT unsigned short	cgul_crc16__crc (cgul_exception_t *cex, cgul_crc16_t crc)
CGUL_EXPORT unsigned short	cgul_crc16__crc_block (cgul_exception_t *cex, cgul_crc16_t crc, const void *block, size_t length)
CGUL_EXPORT unsigned short	cgul_crc16__crc_range_of_block (cgul_exception_t *cex, cgul_crc16_t crc, const void *block, size_t offset, size_t length)
CGUL_EXPORT unsigned long	cgul_crc16__crc_file (cgul_exception_t *cex, cgul_crc16_t crc, FILE *f)
CGUL_EXPORT unsigned long	cgul_crc16__crc_fname (cgul_exception_t *cex, cgul_crc16_t crc, const char *fname)
CGUL_EXPORT void	cgul_crc16__update_byte (cgul_exception_t *cex, cgul_crc16_t crc, unsigned char c)
CGUL_EXPORT void	cgul_crc16__update_block (cgul_exception_t *cex, cgul_crc16_t crc, const void *block, size_t length)
CGUL_EXPORT void	cgul_crc16__update_range_of_block (cgul_exception_t *cex, cgul_crc16_t crc, const void *block, size_t offset, size_t length)
CGUL_EXPORT void	cgul_crc16__update_file (cgul_exception_t *cex, cgul_crc16_t crc, FILE *f)
CGUL_EXPORT void	cgul_crc16__update_fname (cgul_exception_t *cex, cgul_crc16_t crc, const char *fname)
CGUL_EXPORT void	cgul_crc16__reset (cgul_exception_t *cex, cgul_crc16_t crc)
CGUL_EXPORT char *	cgul_crc16__get_table_as_string (cgul_exception_t *cex, cgul_crc16_t crc)

Detailed Description

The cgul_crc16 class is designed to handle any of the different common permutations on the CRC-16 algorithm. This class is parameterized to allow different generator polynomials, initial values of the shift register, final XOR values, whether to append the size, whether to XOR the size before appending, and whether the data stream is reflected.

This class was first written in java, and the naming convention for methods in this class follows what is established by java.security.MessageDigest instead of what is established by java.util.zip.CRC32.

A simple example of how to use this class follows:

    cgul_exception_t* cex = NULL;
    cgul_crc16_t crc =
        cgul_crc16__new(cex, 0x8408, 0, 0, 1);
    unsigned short result =
        cgul_crc16__crc_block(cex, crc, "123456789", 9);
    cgul_libc_printf(&cex, "%#06hx\n", result);

The above code will calculate the CRC16-CCITT CRC for the ASCII text string "123456789". The CRC that is printed to the screen will be 0x2189.

The following is a list of 16-bit CRCs and how to call cgul_crc16__new() to create a new cgul_crc16 objects for each CRC:

 // CRC-16 (aka CRC-IBM, CRC-16/ARC)
 g = 0xa001;
 init = 0;
 final_xor = 0;
 reflected = 1;

 // CRC-CCITT (aka kermit)
 g = 0x8408;
 init = 0;
 final_xor = 0;
 reflected = 1;

 // X.25
 g = 0x8408;
 init = 0xffff;
 final_xor = 0xffff;
 reflected = 1;

 // CRC-16/RFID
 g = 0x1021;
 init = 0xffff;
 final_xor = 0xffff;
 reflected = 0;

 // CRC-16/USB
 g = 0xa001;
 init = 0xffff;
 final_xor = 0xffff;
 reflected = 1;

 // xmodem (aka zmodem)
 g = 0x1021;
 init = 0;
 final_xor = 0;
 reflected = 0;

Note

If you use this class from multiple threads, you MUST provide external synchronization to all methods so that you do not corrupt internal data structures.

Author

Paul Serice

See also

cgul_crc16_incr

Typedef Documentation

cgul_crc16_t

typedef typedefCGUL_BEGIN_C struct cgul_crc16* cgul_crc16_t

Opaque pointer to cgul_crc16 instance.

Function Documentation

cgul_crc16__new()

CGUL_EXPORT cgul_crc16_t cgul_crc16__new	(	cgul_exception_t *	cex,
		unsigned short	g,
		unsigned short	init,
		unsigned short	final_xor,
		int	reflected
	)

Create a new cgul_crc16 object. Objects created with this constructor do not append the size to the data stream that is CRCed. The caller is responsible for freeing the object by calling cgul_crc16__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	g	generator polynomial
[in]	init	initial value loaded into the accumulator
[in]	final_xor	value to xor with the calculated crc
[in]	reflected	whether to use the reflected algorithm

Returns

new cgul_crc16 instance

Referenced by cgul_crc16_cxx::cgul_crc16_cxx().

cgul_crc16__new_appends_size()

CGUL_EXPORT cgul_crc16_t cgul_crc16__new_appends_size	(	cgul_exception_t *	cex,
		unsigned short	g,
		unsigned short	init,
		unsigned short	final_xor,
		int	reflected,
		size_t	size_xor
	)

Create a new cgul_crc16 object. Objects created with this constructor append the size to the data stream that is CRCed. The caller is responsible for freeing the object by calling cgul_crc16__delete(). If memory cannot be allocated, NULL is returned and an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	g	polynomial
[in]	init	initial value loaded into the accumulator
[in]	final_xor	value to xor with the calculated crc
[in]	reflected	whether to use the reflected algorithm
[in]	size_xor	value to xor with the size before appending

Returns

new cgul_crc16 instance

Referenced by cgul_crc16_cxx::cgul_crc16_cxx().

cgul_crc16__delete()

CGUL_EXPORT void cgul_crc16__delete

(

cgul_crc16_t

crc

)

This method frees all internally allocated memory. Do not try to access crc after calling this method.

Parameters

[in]

crc

cgul_crc16 instance

Referenced by cgul_crc16_cxx::set_obj(), and cgul_crc16_cxx::~cgul_crc16_cxx().

cgul_crc16__assign()

CGUL_EXPORT void cgul_crc16__assign	(	cgul_exception_t *	cex,
		cgul_crc16_t	lhs,
		cgul_crc16_t	rhs
	)

Assign the current accumulator and size of rhs to lhs. This operation probably only makes sense if lhs and rhs have been constructed identically. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	lhs	left-hand side
[in]	rhs	right-hand side

Referenced by cgul_crc16_cxx::assign().

cgul_crc16__crc()

CGUL_EXPORT unsigned short cgul_crc16__crc	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc
	)

This method completes the CRC calculation by performing the size XOR and the final XOR. You will generally call one of the update() methods before calling this method. When this method returns, the internal state of the object is reset so that it is ready to calculate the next CRC. The return value is the final value for the CRC.

Parameters

[in]	cex	c-style exception
[in]	crc	cgul_crc16 instance

Returns

final crc value

Referenced by cgul_crc16_cxx::crc().

cgul_crc16__crc_block()

CGUL_EXPORT unsigned short cgul_crc16__crc_block	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc,
		const void *	block,
		size_t	length
	)

This is the method to call when you only have one block for which you want to calculate a CRC. You can also call this if you have called one of the update() methods before, and you know that block is your last block. When this method returns, the internal state of the object is reset so that it is ready to calculate the next CRC. length is the number of bytes inside of block that you want to add to the CRC calculation. The return value is the final value for the CRC.

Parameters

[in]	cex	c-style exception
[in]	crc	cgul_crc16 instance
[in]	block	block of data to add to the crc
[in]	length	length of block

Returns

final crc value

Referenced by cgul_crc16_cxx::crc_block().

cgul_crc16__crc_range_of_block()

CGUL_EXPORT unsigned short cgul_crc16__crc_range_of_block	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc,
		const void *	block,
		size_t	offset,
		size_t	length
	)

This is the method to call when you want to calculate the CRC from a range of bytes from one block. You can also call this if you have called one of the update() methods before, and you know that block is your last block. When this method returns, the internal state of the object is reset so that it is ready to calculate the next CRC. offset is the index into block where you want to add length bytes to the CRC calculation. The return value is the final value for the CRC.

Parameters

[in]	cex	c-style exception
[in]	crc	cgul_crc16 instance
[in]	block	block of data to add to the crc
[in]	offset	offset into block
[in]	length	length of block

Returns

final crc value

Referenced by cgul_crc16_cxx::crc_range_of_block().

cgul_crc16__crc_file()

CGUL_EXPORT unsigned long cgul_crc16__crc_file	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc,
		FILE *	f
	)

This is the method to call when you only have one file for which you want to calculate a CRC. You can also call this if you have called one of the update() methods before (like cgul_crc16__update_file()), and you know that f is your last file. When this method returns, the internal state of the object is reset so that it is ready to calculate the next CRC. The return value is the final value for the CRC.

Parameters

[in,out]	cex	c-style exception
[in]	crc	cgul_crc16 instance
[in]	f	input file

Returns

final crc value

Referenced by cgul_crc16_cxx::crc_file().

cgul_crc16__crc_fname()

CGUL_EXPORT unsigned long cgul_crc16__crc_fname	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc,
		const char *	fname
	)

This is the method to call when you only have one file for which you want to calculate a CRC. You can also call this if you have called one of the update() methods before (like cgul_crc16__update_fname()), and you know that fname is your last file. When this method returns, the internal state of the object is reset so that it is ready to calculate the next CRC. The return value is the final value for the CRC.

Parameters

[in,out]	cex	c-style exception
[in]	crc	cgul_crc16 instance
[in]	fname	input file name

Returns

final crc value

Referenced by cgul_crc16_cxx::crc_fname().

cgul_crc16__update_byte()

CGUL_EXPORT void cgul_crc16__update_byte	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc,
		unsigned char	c
	)

This method updates the CRC by adding the byte c to the CRC calculation.

Parameters

[in]	cex	c-style exception
[in]	crc	cgul_crc16 instance
[in]	c	byte to add to crc

Referenced by cgul_crc16_cxx::update_byte().

cgul_crc16__update_block()

CGUL_EXPORT void cgul_crc16__update_block	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc,
		const void *	block,
		size_t	length
	)

This method updates the CRC by adding all the bytes in block to the calculation.

Parameters

[in]	cex	c-style exception
[in]	crc	cgul_crc16 instance
[in]	block	block of data to add to the crc
[in]	length	length of block

Referenced by cgul_crc16_cxx::update_block().

cgul_crc16__update_range_of_block()

CGUL_EXPORT void cgul_crc16__update_range_of_block	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc,
		const void *	block,
		size_t	offset,
		size_t	length
	)

This method updates the CRC by adding a range of bytes in block to the calculation. The range starts at offset and extends length bytes.

Parameters

[in]	cex	c-style exception
[in]	crc	cgul_crc16 instance
[in]	block	block of data to add to the crc
[in]	offset	offset into block
[in]	length	length of block

Referenced by cgul_crc16_cxx::update_range_of_block().

cgul_crc16__update_file()

CGUL_EXPORT void cgul_crc16__update_file	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc,
		FILE *	f
	)

This method updates the CRC by adding all the bytes (starting at the current offset) in the file f to the calculation. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	crc	cgul_crc16 instance
[in]	f	input file

Referenced by cgul_crc16_cxx::update_file().

cgul_crc16__update_fname()

CGUL_EXPORT void cgul_crc16__update_fname	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc,
		const char *	fname
	)

This method updates the CRC by adding all the bytes in the file with name fname to the calculation. If an error occurs, an exception is thrown.

Parameters

[in,out]	cex	c-style exception
[in]	crc	cgul_crc16 instance
[in]	fname	input file name

Referenced by cgul_crc16_cxx::update_fname().

cgul_crc16__reset()

CGUL_EXPORT void cgul_crc16__reset	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc
	)

Reset the cgul_crc16 object for further use.

Parameters

[in]	cex	c-style exception
[in]	crc	cgul_crc16 instance

Referenced by cgul_crc16_cxx::reset().

cgul_crc16__get_table_as_string()

CGUL_EXPORT char* cgul_crc16__get_table_as_string	(	cgul_exception_t *	cex,
		cgul_crc16_t	crc
	)

You can use this method to see the CRC lookup table that is being used. The returned value is the CRC lookup table for this object as a string. The caller is responsible for calling free() on the string that is returned.

Parameters

[in,out]	cex	c-style exception
[in]	crc	cgul_crc16 instance

Returns

crc lookup table as a string

Referenced by cgul_crc16_cxx::get_table_as_string().