fret.h File Reference

API header file for the FRET library. More...

#include <stdbool.h>
#include <stddef.h>

Include dependency graph for fret.h:

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

Data Structures
struct	Gram
	Describes a data structure that is found in a raw data buffer. More...
struct	FBuffer
	Struct describes a buffer in memory. More...
struct	GramReport
	Struct holds an array of Grams that are a response to a query. More...
struct	ScanOptions
	Structure holds options that affect scanning which are specified by the client. More...
Typedefs
typedef size_t	BufferId
	Uniquely identifies a Buffer.
typedef unsigned long	HashValue
	The hash value of the raw data that makes up a Gram.
typedef void(*	fret_sendProgressFunc )(unsigned char progress)
	A callback function used to notify the client of the progress of the current scans.
Enumerations
enum	FretReturn
	Indicates the failure or success of a FRET API call.
enum	FretError {   NO_ERROR, INCORRECT_PARAM, NULL_PARAM, NON_NULL_PARAM,   LIB_NOT_INIT, LIB_DEINIT, NO_BUFFERS, NO_SCANS,   CALLBACK_SET, CALLBACK_NULL, INTERNAL_ERROR }
	Describes the failure mode of the last called API function. More...
enum	PhaseId {   NO_PHASE = 0, PHASE1, PHASE2, PHASE3,   PHASE4, PHASE5, PHASE6 }
	Identifies the Phase of scanning the raw data. More...
enum	ScanId { ,   SCAN_ASCII, SCAN_FILL, SCAN_OFFSETS_BYTE, SCAN_OFFSETS_SHORT,   SCAN_OFFSETS_LONG, SCAN_GRIND, SCAN_COMMON_OFFSET, SCAN_COMMON_HASH,   SCAN_AMALG_OFFHASH, SCAN_PURGE_OVERLAP }
	Identifies an individual scan. More...
enum	GramClass
	Class of a Gram. Class if a high level way of grouping Grams. More...
enum	GramType
	Describes the exact type of a Gram. Several types of Gram may exist within the same class of Gram. More...
Functions
bool	fret_init (void)
bool	fret_deinit (void)
bool	fret_getError (FretError *const pError)
bool	fret_setOptions (const ScanOptions *const pOpts)
bool	fret_putBuffer (FBuffer *pBuffer)
	Pass a buffer containing data to be analysed to the library.
bool	fret_deleteBuffer (BufferId bufferId)
	Remove a buffer from the data set that may be examined by the library.
bool	fret_deleteAll (void)
	Delete all stored Buffers.
bool	fret_runScan (BufferId bufferId, PhaseId phaseId, ScanId scanId)
	Run a scan or batch of scans on a buffer or all of the buffers.
bool	fret_getReport (BufferId bufferId, size_t offset, size_t length, GramReport *pReport)
	Retrieve an array of Grams that describe the data structure in a buffer(s).
bool	fret_freeReport (GramReport *pReport)
	Frees the memory that is dynamically allocated to a GramReport.
bool	fret_setProgressCallback (fret_sendProgressFunc pCallback)
	Passes a pointer to a callback function which is used to notify the client about the progress of the current operation.
bool	fret_cancelScan (void)
	Passes a pointer to a callback function which is used to notify the client about the progress of the current operation.

---

Detailed Description

API header file for the FRET library.

The FRET library provides functionality to aid the identification of the structure and layout of all types of data buffers. It requires no previous knowledge of the buffers data format. It bases its conclusions on a series of heuristic tests or Scans of the data. Each discovered structure within a buffer is called a Gram and each Gram is described by its Type, Position, Length and Risk. A Grams Risk is a measure of the probability that it is a randomly occuring pattern within the data. The lower a Gram´s Risk, the higher the confidence that it is correctly detected.

---

Typedef Documentation

typedef void(* fret_sendProgressFunc)(unsigned char progress)

A callback function used to notify the client of the progress of the current scans. The current progress is sent as a value in the range 0-255, with 0 indicating none of the current scan has been completed. Parameters: progress  is a value in the range 0-255 that indicates how much of the current scan(s) has been completed. Returns: true if function completed successfully. false if the library couldn´t return any Grams. Query cause with fret_getError(). See also: fret_getError fret_setProgressCallback

typedef unsigned long HashValue

The hash value of the raw data that makes up a Gram. A 4 byte hash value that represents the data in a Gram. This can be used for the analysis and comparison of Grams.

---

Enumeration Type Documentation

enum FretError

Describes the failure mode of the last called API function. Enumerator: NO_ERROR  There is no error state in the library. INCORRECT_PARAM  An incorret parameter is passed in the API call. NULL_PARAM  A NULL parameter is passed when a non-NULL value is expected. NON_NULL_PARAM  A non-NULL parameter is passed when a NULL value is expected. LIB_NOT_INIT  libfret has not been initialized correctly. LIB_DEINIT  A call is made after libfret is de-initialized. NO_BUFFERS  No Buffers to analyse. NO_SCANS  No valid Scans were specified. CALLBACK_SET  Callback function already registered. CALLBACK_NULL  Callback function not registered. INTERNAL_ERROR  library got a bit confused!

enum GramClass

Class of a Gram. Class if a high level way of grouping Grams. The Class of a Gram tells you the general type of Gram it is and also indicates what type of Scan detected the Gram.

enum GramType

Describes the exact type of a Gram. Several types of Gram may exist within the same class of Gram. The type of a Gram indicates the type of raw data that in the Gram. It does not indicate how the Gram is detected as more than one Scan may detect the same type of Gram or a single Scan may detect multiple types of Gram.

enum PhaseId

Identifies the Phase of scanning the raw data. Enumerator: NO_PHASE  No Phase specified. PHASE1  Preprocess the data in a Buffer before scanning. PHASE2  Parse the raw data for isolated data structures in a Buffer. PHASE3  Compare the raw data of a Buffer vs. its identified Grams. PHASE4  Identify commonalities between raw data Buffers. PHASE5  Create Generic Grams based on multiple Buffer Grams. PHASE6  Process Generic Grams to identify redundancy or incorrectness.

enum ScanId

Identifies an individual scan. Enumerator: SCAN_ASCII  Scan for 1-byte ASCII strings. SCAN_FILL  Scan for 1-byte fill sequences. SCAN_OFFSETS_BYTE  Scan for offsets to other structures within a Buffer. SCAN_OFFSETS_SHORT  Scan for offsets to other structures within a Buffer. SCAN_OFFSETS_LONG  Scan for offsets to other structures within a Buffer. SCAN_GRIND  Compare all Buffers looking for patterns of bytes that are the same between Buffers. SCAN_COMMON_OFFSET  Scan for Buffer Grams that have the same type and offset. SCAN_COMMON_HASH  Scan for Buffer Grams that have the same type and hash. SCAN_AMALG_OFFHASH  Amalgamate Generic Grams if they have same offset & hash. SCAN_PURGE_OVERLAP  Remove all overlapping generic Grams that have the highest Risk.

---

Function Documentation

bool fret_cancelScan (  void   )

Passes a pointer to a callback function which is used to notify the client about the progress of the current operation. Passes a pointer to a callback function, which is provided by the client, that is used by the library to send updates on the progress of the current scan. The current scan must have been initiated using a call to fret_runScan(). fret_runScan is not atomic i.e. Grams that have already been generated will remain after the scans are cancelled. Returns: true if current scan(s) were stopped and cancelled. false if the function could not be registered. Query cause with fret_getError(). See also: fret_getError fret_runScan

bool fret_deinit (  void   )

De-initializes the FRET library and deallocates internal resources. Returns: true if all resources were freed correctly. false if resource deallocation failed. The failure mode can be retrieved using the function fret_getError(). See also: fret_getError

bool fret_deleteAll (  void   )

Delete all stored Buffers. Delete all memory that has been allocated to Buffer storage. Allocated Buffer identifiers cannot be used again. Parameters: void  Returns: true if function completed successfully. false if library could not free the buffers. Query cause with fret_getError(). See also: fret_putBuffer fret_getError

bool fret_deleteBuffer (  BufferId  bufferId  )

Remove a buffer from the data set that may be examined by the library. Passes the identifier of a buffer. This buffer will be removed from the list of buffers that may be scanned. The identifier of this buffer can never be used again. Memory allocated to the buffer will also be deallocated. Parameters: bufferId  identifies the buffer to delete. Returns: true if function completed successfully. false if library could not free the buffer. Query cause with fret_getError(). See also: fret_putBuffer fret_getError

bool fret_freeReport (  GramReport *  pReport  )

Frees the memory that is dynamically allocated to a GramReport. Deallocates the memory that is allocated to the Gram array attached to a Gram report. This function should be passed a pointer to a GramReport object that was previously allocated using the function fret_getReport. Parameters: pReport  is a pointer to a GramReport object. Returns: true if function completed successfully. false if the library couldn´t deallocate the memory. Query cause with fret_getError(). See also: fret_getReport fret_getError

bool fret_getError (  FretError *const   pError  )

Get an error code describing the cause of the last known error. Parameters: pError  is a pointer to a FretError variable that will store the error identifier. Returns: true if there is an error to report. false if there is no known error to report. It may be that another API function was called and reset the state. See also: FretError

bool fret_getReport (  BufferId  bufferId, size_t  offset, size_t  length, GramReport *  pReport )

Retrieve an array of Grams that describe the data structure in a buffer(s). Passes a Buffer Id to the library. If there are available Grams for this buffer, the data is returned as an array of Grams. If no Buffer Id is passed, the Grams for all Buffers are returned. There is also the option of specifying that only Grams for a range within a buffer or buffers are required using the offset and length. Parameters: bufferId  identifies an individual buffer using its Buffer Id. If it is 0x0 then all Grams mustbe returned. offset  is start of range in buffer for which results will be returned. length  length is the length of the range within the buffer for which Grams will be returned. If the value is zero then results for the whole buffer will be returned and the previous parameter offset will be ignored. pReport  is a pointer to a struct that will hold the returned array of Grams. The client allocates the GramReport object and the library will allocate the memory for an array of Grams. The client must later call fret_freeReport to deallocate the array memory. Returns: true if function completed successfully. false if the library couldn´t return any Grams. Query cause with fret_getError(). See also: fret_freeReport fret_getError

bool fret_init (  void   )

Initialize the FRET library and allocate internal resources. Returns: true if library can be used. false if resource allocation failed. the failure mode can be retrieved using the function fret_getError(). See also: fret_getError

bool fret_putBuffer (  FBuffer *  pBuffer  )

Pass a buffer containing data to be analysed to the library. Passes a pointer to a data buffer to the library. The length of the buffer (in bytes) is also passed. A Buffer ID is allocated to the buffer if it is accepted. The library makes a private copy of the buffer and is responsible for its deletion when not required. Therefore, the client´s copy of the buffer can be safely deleted. Parameters: pBuffer  is a pointer to structure containing the location and length of the buffer. The member bufferId of the structure is set to the new Buffer ID. Returns: true if function completed successfully. false if library didn´t accept the buffer. Query cause with fret_getError(). See also: FBuffer fret_deleteBuffer fret_getError

bool fret_runScan (  BufferId  bufferId, PhaseId  phaseId, ScanId  scanId )

Run a scan or batch of scans on a buffer or all of the buffers. If a Buffer ID is passed, then only that Buffer is scanned, otherwise all Buffers are scanned. If a Phase Id is specified then only the scans for that phase are applied. If a specific Scan Id is passed then only that scan is applied to the buffer(s). Parameters: bufferId  identifies an individual buffer using its Buffer Id. If it is zero then scan all buffers. phaseId  identifies the phase of scans to apply. If the value is zero then a Scan Id can be passed or else all scans will be applied. scanId  identifies the scan to apply. If it is zero then a Phase Id must be passed as a parameter or else all scans are applied. Returns: true if function completed successfully. false if the library couldn´t complete the scans. Query cause with fret_getError(). See also: fret_getError

bool fret_setOptions (  const ScanOptions *const   pOpts  )

Passes client specified options, which affecting scanning behaviour, to the library. Returns: true if there is no error to report. false if an incorrect option is passed to the library. The failure mode can be retrieved using the function fret_getError(). See also: ScanOptions fret_getError

bool fret_setProgressCallback (  fret_sendProgressFunc  pCallback  )

Passes a pointer to a callback function which is used to notify the client about the progress of the current operation. Passes a pointer to a callback function, which is provided by the client, that is used by the library to send updates on the progress of the current scan. Parameters: pCallback  is a pointer to the callback function. Returns: true if function is registered correctly. false if the function could not be registered. Query cause with fret_getError(). See also: fret_getError fret_sendProgressFunc

---