Typedefs | Functions

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)
 
const void * le_ref_GetSafeRef (le_ref_IterRef_t iteratorRef)
 
void * le_ref_GetValue (le_ref_IterRef_t iteratorRef)
 

Detailed Description

Legato Safe References API include file.

Copyright (C) Sierra Wireless Inc.

Typedef Documentation

◆ le_ref_IterRef_t

typedef struct le_ref_Iter* le_ref_IterRef_t

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

◆ le_ref_MapRef_t

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_CreateMap()

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]nameName of the map (for diagnostics).
[in]maxRefsMaximum number of Safe References expected to be kept in this Reference Map at any one time.

◆ le_ref_CreateRef()

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]mapRefReference Map in which the mapping should be kept.
[in]ptrPointer value to which the new Safe Reference will be mapped.

◆ le_ref_DeleteRef()

void le_ref_DeleteRef ( le_ref_MapRef_t  mapRef,
void *  safeRef 
)

Deletes a Safe Reference.

Parameters
[in]mapRefReference Map to delete the mapping from.
[in]safeRefSafe Reference to be deleted (invalidated).

◆ le_ref_GetIterator()

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]mapRefReference to the map.

◆ le_ref_GetSafeRef()

const void* 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]iteratorRefReference to the iterator.

◆ le_ref_GetValue()

void* 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]iteratorRefReference to the iterator.

◆ le_ref_Lookup()

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]mapRefReference Map to do the lookup in.
[in]safeRefSafe Reference to be translated into a pointer.

◆ le_ref_NextNode()

le_result_t le_ref_NextNode ( le_ref_IterRef_t  iteratorRef)

Moves the iterator to the next key/value pair in the map.

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]iteratorRefReference to the iterator.