map.h File Reference

Enumeration specifying the status of calls to various APIs in this module.

Retrieves the complete list of keys and values from the map in values and keys.

Also writes the size of the list in count.

Parameters:

handle	The handle to an existing map.
keys	The location where the list of keys is to be written.
values	The location where the list of values is to be written.
count	The number of stored keys and values is written at the location indicated by this pointer.

Returns:

Returns MAP_OK if the keys and values are retrieved and written successfully or an error code otherwise.

Retrieves the value of a stored key.

Parameters:

handle	The handle to an existing map.
key	The key to be looked up in the map.

Returns:

Returns NULL in case the input arguments are NULL or if the requested key is not found in the map. Returns a pointer to the key's value otherwise.

This function returns true in valueExists if at least one <key,value> pair exists in the map where the entry's value is equal to the parameter value.

Parameters:

handle	The handle to an existing map.
value	The value that the caller wants checked.
valueExists	The function writes true at the address pointed at by this parameter if the value exists in the map and false otherwise.

Returns:

Returns MAP_OK if the check was performed successfully or an error code otherwise.

This function returns a boolean value in keyExists if the map contains a key with the same value the parameter key.

Parameters:

handle	The handle to an existing map.
key	The key that the caller wants checked.
keyExists	The function writes true at the address pointed at by this parameter if the key exists in the map and false otherwise.

Returns:

Returns MAP_OK if the check was performed successfully or an error code otherwise.

Removes a key and its associated value from the map.

Parameters:

handle	The handle to an existing map.
key	The key of the item to be deleted.

Returns:

Returns MAP_OK if the key was deleted successfully or an error code otherwise.

Adds/updates a key/value pair to the map.

Parameters:

handle	The handle to an existing map.
key	The key to be used for this map entry.
value	The value to be associated with key.

This function behaves exactly like Map_Add except that if the key already exists in the map then it overwrites the value with the supplied value instead of returning an error. If a non-NULL pointer to a callback function was supplied via the mapFilterFunc parameter when Map_Create was called then that callback is invoked when a new entry is added or when an existing entry is updated and if the callback returns a non-zero value then the function cancels the add/update operation and returns MAP_FILTER_REJECT.

Returns:

If any of the input parameters are NULL then this function returns MAP_INVALID_ARG. If the filter function associated with the map rejects the entry then MAP_FILTER_REJECT is returned. In case an error occurs when the new key is added/updated in the map the function returns MAP_ERROR. If everything goes well then MAP_OK is returned.

Adds a key/value pair to the map.

Parameters:

handle	The handle to an existing map.
key	The key to be used for this map entry.
value	The value to be associated with key.

If a non-NULL pointer to a callback function was supplied via the mapFilterFunc parameter when Map_Create was called then that callback is invoked when a new entry is added and if the callback returns a non-zero value then the function cancels the add operation and returns MAP_FILTER_REJECT.

Returns:

If any of the input parameters are NULL then this function returns MAP_INVALID_ARG. If the key already exists in the map then MAP_KEYEXISTS is returned. If the filter function associated with the map rejects the entry then MAP_FILTER_REJECT is returned. In case an error occurs when the new key is added to the map the function returns MAP_ERROR. If everything goes well then MAP_OK is returned.

Creates a copy of the map indicated by handle and returns a handle to it.

Parameters:

handle

The handle to an existing map.

Returns:

A valid MAP_HANDLE to the cloned copy of the map or NULL in case an error occurs.

Release all resources associated with the map.

Parameters:

handle

The handle to an existing map.

Creates a new, empty map.

Parameters:

mapFilterFunc

A callback function supplied by the caller that is invoked during calls to Map_Add and Map_AddOrUpdate to provide the caller an opportunity to indicate whether the new entry or the update to an existing entry can be made or not. The callback function can request that the operation be canceled by returning a non-zero value from the callback.

Returns:

A valid MAP_HANDLE or NULL in case an error occurs.