share_hash.h File Reference

Manage hashing algorithms provided by protocol plugins and applied to locally shared files. More...

Go to the source code of this file.

Classes
struct	HashAlgo
struct	Hash
Typedefs
typedef unsigned char *(*	HashFn )(const char *path, size_t *len)
typedef char *(*	HashDspFn )(unsigned char *hash, size_t len)
Functions
EXTERN_C_BEGIN LIBGIFTPROTO_EXPORT Hash *	hash_new (HashAlgo *algo, unsigned char *data, size_t len, BOOL copy)
LIBGIFTPROTO_EXPORT void	hash_free (Hash *hash)
LIBGIFTPROTO_EXPORT Hash *	hash_dup (Hash *hash)
LIBGIFTPROTO_EXPORT Hash *	hash_calc (HashAlgo *algo, const char *path)
LIBGIFTPROTO_EXPORT char *	hash_dsp (Hash *hash)
LIBGIFTPROTO_EXPORT unsigned int	hash_algo_register (struct protocol *p, const char *type, int opt, HashFn algofn, HashDspFn dspfn)
LIBGIFTPROTO_EXPORT unsigned int	hash_algo_unregister (struct protocol *p, const char *type)
LIBGIFTPROTO_EXPORT HashAlgo *	hash_algo_lookup (const char *type)
LIBGIFTPROTO_EXPORT BOOL	share_set_hash (struct file_share *file, const char *type, unsigned char *data, size_t len, BOOL copy)
LIBGIFTPROTO_EXPORT Hash *	share_get_hash (struct file_share *file, const char *type)
LIBGIFTPROTO_EXPORT void	share_clear_hash (struct file_share *file)
LIBGIFTPROTO_EXPORT void	share_foreach_hash (struct file_share *file, DatasetForeachFn func, void *udata)
LIBGIFTPROTO_EXPORT unsigned int	share_run_hash (struct file_share *file)
LIBGIFTPROTO_EXPORT char *	share_dsp_hash (struct file_share *file, const char *type)
LIBGIFTPROTO_EXPORT char *	hashstr_algo (const char *hashstr)
LIBGIFTPROTO_EXPORT char *	hashstr_data (const char *hashstr)

---

Detailed Description

Manage hashing algorithms provided by protocol plugins and applied to locally shared files.

There are really multiple interfaces defined here. The supplementary share interface should be moved into share.[ch] at some time.

---

Function Documentation

LIBGIFTPROTO_EXPORT HashAlgo* hash_algo_lookup (  const char *  type  )

Lookup a currently registered algorithm by name.

LIBGIFTPROTO_EXPORT unsigned int hash_algo_register (  struct protocol *  p, const char *  type, int  opt, HashFn  algofn, HashDspFn  dspfn )

Register a new hashing algorithm. See the documentation available at Protocol::hash_handler. Returns: Number of references to the supplied hashing algorithm or zero on error.

LIBGIFTPROTO_EXPORT unsigned int hash_algo_unregister (  struct protocol *  p, const char *  type )

Unregister a hashing algorithm. This is used when a protocol is unloaded so that we can gracefully update the internal data structure without interfering with currently loaded protocols. Returns: Number of references remaining. If zero, the algorithm has been completely removed and it's memory free'd.

LIBGIFTPROTO_EXPORT Hash* hash_calc (  HashAlgo *  algo, const char *  path )

Calculate a new hash from the supplied algorithm and file path. This is used as a work-around to the structured share_hash API, which requires a constructed FileShare to operate.

LIBGIFTPROTO_EXPORT char* hash_dsp (  Hash *  hash  )

Convert a calculated hash (see hash_calc) into a NUL-terminated ASCII representation. Returns: Dynamically allocated string in the form TYPE:ASCII_DATA.

LIBGIFTPROTO_EXPORT Hash* hash_dup (  Hash *  hash  )

Duplicate all entries in a hash object. This includes the original data argument.

LIBGIFTPROTO_EXPORT void hash_free (  Hash *  hash  )

Destroy the result from hash_new. Please note that this will free the original data argument.

EXTERN_C_BEGIN LIBGIFTPROTO_EXPORT Hash* hash_new (  HashAlgo *  algo, unsigned char *  data, size_t  len, BOOL  copy )

Raw interface to allocate a new hash object. Please avoid using this directly at all costs. Parameters: algo  data  Pointer to the beginning of a hash at least `len' bytes long. This data must be allocated, and will not be copied by this function call. len  Length of `data'. copy  If TRUE, Makes a copy of `data' before storage in the hash object. Returns: Dynamically allocated hash object.

LIBGIFTPROTO_EXPORT char* hashstr_algo (  const char *  hashstr  )

Given a giFT-specific hash string return a static reference to ALGOTYPE. The protocol has no awareness of this hack, and it is only used to serialize hashes over the interface protocol. Parameters: hashstr  Serialized hash string in the form ALGOTYPE:ASCIIDATA Returns: Pointer to a static NUL-terminated string representation of the algorithm name or NULL on error.

LIBGIFTPROTO_EXPORT char* hashstr_data (  const char *  hashstr  )

Access the data portion of the hash string. See hashstr_algo. Returns: Pointer into the supplied hashstr object.

LIBGIFTPROTO_EXPORT void share_clear_hash (  struct file_share *  file  )

Clear all hashes associated with the given file. Management of the internal hash memory is dependent on the parameters given to share_set_hash.

LIBGIFTPROTO_EXPORT char* share_dsp_hash (  struct file_share *  file, const char *  type )

Return the ASCII representation of the hash described after lookup. See share_get_hash. Note: This operation must query the protocol plugin which owns the registration of the described hashing algorithm. Returns: Pointer to a dynamically allocated NUL-terminated string or NULL on error.

LIBGIFTPROTO_EXPORT void share_foreach_hash (  struct file_share *  file, DatasetForeachFn  func, void *  udata )

Iterate through all hashes currently associated with this file. Internally uses ::dataset_foreach.

LIBGIFTPROTO_EXPORT Hash* share_get_hash (  struct file_share *  file, const char *  type )

Access the previously set hash. See ::share_hash_set.

LIBGIFTPROTO_EXPORT unsigned int share_run_hash (  struct file_share *  file  )

Build a hash of the supplied file for all currently registered hashing algorithms. Keep in mind that only those primary or local algos will be used here. Secondary algorithms will be used mainly for data integrity. Returns: Number of hashes successfully created.

LIBGIFTPROTO_EXPORT BOOL share_set_hash (  struct file_share *  file, const char *  type, unsigned char *  data, size_t  len, BOOL  copy )

Associate a predetermined hashed value with a share object. Parameters: file  Share object. type  Hashing algorithm's formal name as registered by the plugin. data  Hash data. Memory management within the share object is conditionally dependent on `copy'. len  Length of `data'. copy  Specifies whether or not a copy of the data parameter should be used for local storage and management within the share object. See hash_new for more details. Returns: Boolean success or failure. Successful completion of this operation is defined by the final placement of the specified hash parameter in the internal share object's hash, regardless of whether or not this required an overwrite of the previous data. Use share_get_hash if you need to know if there is already an associated hash.

---