API functions for vdsf hash maps.

Detailed Description

Hash maps use unique keys - the data items are not sorted.

Functions

VDSF_EXPORT int vdsHashMapClose (VDS_HANDLE objectHandle)

Close a Hash Map.

VDSF_EXPORT int vdsHashMapDelete (VDS_HANDLE objectHandle, const void *key, size_t keyLength)

Remove the data item identified by the given key from the hash map.

VDSF_EXPORT int vdsHashMapGet (VDS_HANDLE objectHandle, const void *key, size_t keyLength, void *buffer, size_t bufferLength, size_t *returnedLength)

Retrieve the data item identified by the given key from the hash map.

VDSF_EXPORT int vdsHashMapGetFirst (VDS_HANDLE objectHandle, void *key, size_t keyLength, void *buffer, size_t bufferLength, size_t *retKeyLength, size_t *retDataLength)

Iterate through the hash map.

VDSF_EXPORT int vdsHashMapGetNext (VDS_HANDLE objectHandle, void *key, size_t keyLength, void *buffer, size_t bufferLength, size_t *retKeyLength, size_t *retDataLength)

Iterate through the hash map.

VDSF_EXPORT int vdsHashMapInsert (VDS_HANDLE objectHandle, const void *key, size_t keyLength, const void *data, size_t dataLength)

Insert a data element in the hash map.

VDSF_EXPORT int vdsHashMapOpen (VDS_HANDLE sessionHandle, const char *hashMapName, size_t nameLengthInBytes, VDS_HANDLE *objectHandle)

Open an existing hash map (see vdsCreateObject to create a new object).

VDSF_EXPORT int vdsHashMapReplace (VDS_HANDLE objectHandle, const void *key, size_t keyLength, const void *data, size_t dataLength)

Replace a data element in the hash map.

VDSF_EXPORT int vdsHashMapStatus (VDS_HANDLE objectHandle, vdsObjStatus *pStatus)

Return the status of the hash map.

Function Documentation

VDSF_EXPORT int vdsHashMapClose ( VDS_HANDLE objectHandle )

Close a Hash Map.

This function terminates the current access to the hash map in shared memory (the hash map itself is untouched).

Warning:: Closing an object does not automatically commit or rollback data items that were inserted or removed. You still must use either vdsCommit or vdsRollback to end the current unit of work.

Parameters:

[in] objectHandle The handle to the hash map (see vdsHashMapOpen).

Returns:: 0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsHashMapDelete	(	VDS_HANDLE	objectHandle,
		const void *	key,
		size_t	keyLength
	)

Remove the data item identified by the given key from the hash map.

Data items which were added by another session and are not yet committed will not be seen by this function and cannot be removed. Likewise, destroyed data items (even if not yet committed) are invisible.

The removals only become permanent after a call to vdsCommit.

Parameters:

`[in]`	objectHandle	The handle to the hash map (see vdsHashMapOpen).
`[in]`	key	The key of the item to be removed.
`[in]`	keyLength	The length of the key buffer (in bytes).

Returns:: 0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsHashMapGet	(	VDS_HANDLE	objectHandle,
		const void *	key,
		size_t	keyLength,
		void *	buffer,
		size_t	bufferLength,
		size_t *	returnedLength
	)

Retrieve the data item identified by the given key from the hash map.

Data items which were added by another session and are not yet committed will not be seen by this function. Likewise, destroyed data items (even if not yet committed) are invisible.

Parameters:

`[in]`	objectHandle	The handle to the hash map (see vdsHashMapOpen).
`[in]`	key	The key of the item to be retrieved.
`[in]`	keyLength	The length of the key buffer (in bytes).
`[out]`	buffer	The buffer provided by the user to hold the content of the data item. Memory allocation for this buffer is the responsability of the caller.
`[in]`	bufferLength	The length of buffer (in bytes).
`[out]`	returnedLength	The actual number of bytes in the data item.

Returns:: 0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsHashMapGetFirst	(	VDS_HANDLE	objectHandle,
		void *	key,
		size_t	keyLength,
		void *	buffer,
		size_t	bufferLength,
		size_t *	retKeyLength,
		size_t *	retDataLength
	)

Iterate through the hash map.

Data items which were added by another session and are not yet committed will not be seen by the iterator. Likewise, destroyed data items (even if not yet committed) are invisible.

Data items retrieved this way will not be sorted.

Parameters:

`[in]`	objectHandle	The handle to the hash map (see vdsHashMapOpen).
`[out]`	key	The key buffer provided by the user to hold the content of the key associated with the first element. Memory allocation for this buffer is the responsability of the caller.
`[in]`	keyLength	The length of the key buffer (in bytes).
`[out]`	buffer	The buffer provided by the user to hold the content of the first element. Memory allocation for this buffer is the responsability of the caller.
`[in]`	bufferLength	The length of buffer (in bytes).
`[out]`	retKeyLength	The actual number of bytes in the key
`[out]`	retDataLength	The actual number of bytes in the data item.

Returns:: 0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsHashMapGetNext	(	VDS_HANDLE	objectHandle,
		void *	key,
		size_t	keyLength,
		void *	buffer,
		size_t	bufferLength,
		size_t *	retKeyLength,
		size_t *	retDataLength
	)

Iterate through the hash map.

Data items which were added by another session and are not yet committed will not be seen by the iterator. Likewise, destroyed data items (even if not yet committed) are invisible.

Evidently, you must call vdsHashMapGetFirst to initialize the iterator. Not so evident - calling vdsHashMapGet will reset the iteration to the data item retrieved by this function (they use the same internal storage). If this cause a problem, please let us know.

Data items retrieved this way will not be sorted.

Parameters:

`[in]`	objectHandle	The handle to the hash map (see vdsHashMapOpen).
`[out]`	key	The key buffer provided by the user to hold the content of the key associated with the data element. Memory allocation for this buffer is the responsability of the caller.
`[in]`	keyLength	The length of the key buffer (in bytes).
`[out]`	buffer	The buffer provided by the user to hold the content of the data element. Memory allocation for this buffer is the responsability of the caller.
`[in]`	bufferLength	The length of buffer (in bytes).
`[out]`	retKeyLength	The actual number of bytes in the key
`[out]`	retDataLength	The actual number of bytes in the data item.

Returns:: 0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsHashMapInsert	(	VDS_HANDLE	objectHandle,
		const void *	key,
		size_t	keyLength,
		const void *	data,
		size_t	dataLength
	)

Insert a data element in the hash map.

The additions only become permanent after a call to vdsCommit.

Parameters:

`[in]`	objectHandle	The handle to the hash map (see vdsHashMapOpen).
`[in]`	key	The key of the item to be inserted.
`[in]`	keyLength	The length of the key buffer (in bytes).
`[in]`	data	The data item to be inserted.
`[in]`	dataLength	The length of data (in bytes).

Returns:: 0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsHashMapOpen	(	VDS_HANDLE	sessionHandle,
		const char *	hashMapName,
		size_t	nameLengthInBytes,
		VDS_HANDLE *	objectHandle
	)

Open an existing hash map (see vdsCreateObject to create a new object).

Parameters:

`[in]`	sessionHandle	The handle to the current session.
`[in]`	hashMapName	The fully qualified name of the hash map.
`[in]`	nameLengthInBytes	The length of hashMapName (in bytes) not counting the null terminator (null-terminators are not used by the vdsf engine).
`[out]`	objectHandle	The handle to the hash map, allowing us access to the map in shared memory. On error, this handle will be set to zero (NULL) unless the objectHandle pointer itself is NULL.

Returns:: 0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsHashMapReplace	(	VDS_HANDLE	objectHandle,
		const void *	key,
		size_t	keyLength,
		const void *	data,
		size_t	dataLength
	)

Replace a data element in the hash map.

The replacements only become permanent after a call to vdsCommit.

Parameters:

`[in]`	objectHandle	The handle to the hash map (see vdsHashMapOpen).
`[in]`	key	The key of the item to be replaced.
`[in]`	keyLength	The length of the key buffer (in bytes).
`[in]`	data	The new data item that will replace the previous data.
`[in]`	dataLength	The length of data (in bytes).

Returns:: 0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsHashMapStatus	(	VDS_HANDLE	objectHandle,
		vdsObjStatus *	pStatus
	)

Return the status of the hash map.

Parameters:

`[in]`	objectHandle	The handle to the hash map (see vdsHashMapOpen).
`[out]`	pStatus	A pointer to the status structure.

Returns:: 0 on success or a vdsErrors on error.

Last updated on April 07, 2008.


Functions
VDSF_EXPORT int	vdsHashMapClose (VDS_HANDLE objectHandle)
	Close a Hash Map.
VDSF_EXPORT int	vdsHashMapDelete (VDS_HANDLE objectHandle, const void *key, size_t keyLength)
	Remove the data item identified by the given key from the hash map.
VDSF_EXPORT int	vdsHashMapGet (VDS_HANDLE objectHandle, const void key, size_t keyLength, void buffer, size_t bufferLength, size_t *returnedLength)
	Retrieve the data item identified by the given key from the hash map.
VDSF_EXPORT int	vdsHashMapGetFirst (VDS_HANDLE objectHandle, void key, size_t keyLength, void buffer, size_t bufferLength, size_t retKeyLength, size_t retDataLength)
	Iterate through the hash map.
VDSF_EXPORT int	vdsHashMapGetNext (VDS_HANDLE objectHandle, void key, size_t keyLength, void buffer, size_t bufferLength, size_t retKeyLength, size_t retDataLength)
	Iterate through the hash map.
VDSF_EXPORT int	vdsHashMapInsert (VDS_HANDLE objectHandle, const void key, size_t keyLength, const void data, size_t dataLength)
	Insert a data element in the hash map.
VDSF_EXPORT int	vdsHashMapOpen (VDS_HANDLE sessionHandle, const char hashMapName, size_t nameLengthInBytes, VDS_HANDLE objectHandle)
	Open an existing hash map (see vdsCreateObject to create a new object).
VDSF_EXPORT int	vdsHashMapReplace (VDS_HANDLE objectHandle, const void key, size_t keyLength, const void data, size_t dataLength)
	Replace a data element in the hash map.
VDSF_EXPORT int	vdsHashMapStatus (VDS_HANDLE objectHandle, vdsObjStatus *pStatus)
	Return the status of the hash map.