le_safeRef.h File Reference

Go to the source code of this file.

Typedefs
typedef struct le_ref_Map *	le_ref_MapRef_t
typedef struct le_ref_Iter *	le_ref_IterRef_t

Functions
le_ref_MapRef_t	le_ref_CreateMap (const char *name, size_t maxRefs)
void *	le_ref_CreateRef (le_ref_MapRef_t mapRef, void *ptr)
void *	le_ref_Lookup (le_ref_MapRef_t mapRef, void *safeRef)
void	le_ref_DeleteRef (le_ref_MapRef_t mapRef, void *safeRef)
le_ref_IterRef_t	le_ref_GetIterator (le_ref_MapRef_t mapRef)
le_result_t	le_ref_NextNode (le_ref_IterRef_t iteratorRef)
void const *	le_ref_GetSafeRef (le_ref_IterRef_t iteratorRef)
void const *	le_ref_GetValue (le_ref_IterRef_t iteratorRef)

Detailed Description

Legato Safe References API include file.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.

Typedef Documentation

typedef struct le_ref_Iter* le_ref_IterRef_t

Reference to an "iterator" object, used to manage iterating a collection of safe refs.

typedef struct le_ref_Map* le_ref_MapRef_t

Reference to a "Reference Map" object, which stores mappings from Safe References to pointers.

Function Documentation

le_ref_MapRef_t le_ref_CreateMap	(	const char *	name,
		size_t	maxRefs
	)

Create a Reference Map that can hold mappings from Safe References to pointers.

Returns

A reference to the Reference Map object.

Parameters

[in]	name	Name of the map (for diagnostics).
[in]	maxRefs	Maximum number of Safe References expected to be kept in this Reference Map at any one time.

void* le_ref_CreateRef	(	le_ref_MapRef_t	mapRef,
		void *	ptr
	)

Creates a Safe Reference, storing a mapping between that reference and a specified pointer for future lookup.

Returns

The Safe Reference.

Parameters

[in]	mapRef	Reference Map in which the mapping should be kept.
[in]	ptr	Pointer value to which the new Safe Reference will be mapped.

void le_ref_DeleteRef	(	le_ref_MapRef_t	mapRef,
		void *	safeRef
	)

Deletes a Safe Reference.

Parameters

[in]	mapRef	Reference Map to delete the mapping from.
[in]	safeRef	Safe Reference to be deleted (invalidated).

le_ref_IterRef_t le_ref_GetIterator

(

le_ref_MapRef_t

mapRef

)

Gets an interator for step-by-step iteration over the map. In this mode the iteration is controlled by the calling function using the le_ref_NextNode() function. There is one iterator per map, and calling this function resets the iterator position to the start of the map. The iterator is not ready for data access until le_ref_NextNode() has been called at least once.

Returns

Returns A reference to a hashmap iterator which is ready for le_hashmap_NextNode() to be called on it.

Parameters

[in]

mapRef

Reference to the map.

void const* le_ref_GetSafeRef

(

le_ref_IterRef_t

iteratorRef

)

Retrieves a pointer to the safe ref iterator is currently pointing at. If the iterator has just been initialized and le_hashmap_NextNode() has not been called, or if the iterator has been invalidated then this will return NULL.

Returns

A pointer to the current key, or NULL if the iterator has been invalidated or is not ready.

Parameters

[in]

iteratorRef

Reference to the iterator.

void const* le_ref_GetValue

(

le_ref_IterRef_t

iteratorRef

)

Retrieves a pointer to the value which the iterator is currently pointing at. If the iterator has just been initialized and le_ref_NextNode() has not been called, or if the iterator has been invalidated then this will return NULL.

Returns

A pointer to the current value, or NULL if the iterator has been invalidated or is not ready.

Parameters

[in]

iteratorRef

Reference to the iterator.

void* le_ref_Lookup	(	le_ref_MapRef_t	mapRef,
		void *	safeRef
	)

Translates a Safe Reference back to the pointer from when the Safe Reference was created.

Returns

Pointer that the Safe Reference maps to, or NULL if the Safe Reference has been deleted or is invalid.

Parameters

[in]	mapRef	Reference Map to do the lookup in.
[in]	safeRef	Safe Reference to be translated into a pointer.

le_result_t le_ref_NextNode

(

le_ref_IterRef_t

iteratorRef

)

Moves the iterator to the next key/value pair in the map. If the hashmap is modified during iteration then this function will return an error.

Returns

Returns LE_OK unless you go past the end of the map, then returns LE_NOT_FOUND. If the iterator has been invalidated by the map changing or you have previously received a LE_NOT_FOUND then this returns LE_FAULT.

Parameters

[in]

iteratorRef

Reference to the iterator.