Data Structures | Macros | Typedefs | Functions

le_safeRef.h File Reference

Go to the source code of this file.

Data Structures

struct  le_ref_MapRef_t
 

Macros

#define LIMIT_MAX_SAFE_REF_NAME_LEN   31
 
#define LIMIT_MAX_SAFE_REF_NAME_BYTES   (LIMIT_MAX_SAFE_REF_NAME_LEN + 1)
 
#define LE_REF_BLOCK_SIZE(numRefs)   (1 + (numRefs))
 
#define LE_REF_DEFINE_STATIC_MAP(name, maxRefs)
 
#define le_ref_InitStaticMap(name, maxRefs)
 

Typedefs

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)
 
void le_ref_EnableTrace (le_ref_MapRef_t mapRef)
 

Detailed Description

Legato Safe References API include file.

Copyright (C) Sierra Wireless Inc.

Macro Definition Documentation

◆ LE_REF_DEFINE_STATIC_MAP

#define LE_REF_DEFINE_STATIC_MAP (   name,
  maxRefs 
)
Value:
static struct le_ref_Map     _ref_##name##Map;                              \
    static void                 *_ref_##name##Data[LE_REF_BLOCK_SIZE(maxRefs)]
le_ref_Map::name
char name[LIMIT_MAX_SAFE_REF_NAME_BYTES]
Descriptive name for debugging. 
Definition: le_safeRef.h:234


le_ref_Map
Definition: le_safeRef.h:229


le_ref_Map::maxRefs
size_t maxRefs
Nominal maximum number of safe references. 
Definition: le_safeRef.h:241

Declare variables for a static safe reference map.

In a static safe reference map the space for the maximum number of references is allocated at compile time.

◆ le_ref_InitStaticMap

#define le_ref_InitStaticMap (   name,
  maxRefs 
)
Value:
(inline_static_assert(                                                              \
        sizeof(_ref_##name##Data) ==                                                    \
            sizeof(void *[LE_REF_BLOCK_SIZE(maxRefs)]),                                 \
        "initial map size does not match definition"),                                  \
    _le_ref_InitStaticMap(#name, (maxRefs), &_ref_##name##Map, _ref_##name##Data))
le_ref_Map::name
char name[LIMIT_MAX_SAFE_REF_NAME_BYTES]
Descriptive name for debugging. 
Definition: le_safeRef.h:234


le_ref_Map::maxRefs
size_t maxRefs
Nominal maximum number of safe references. 
Definition: le_safeRef.h:241

Initialize an already allocated Reference Map that can hold mappings from Safe References to pointers.

Parameters
[in]nameName of the map as specified in LE_REF_DEFINE_STATIC_MAP().
[in]maxRefsMaximum number of Safe References expected to be kept in this Reference Map at any one time.
Returns
The initialized reference map.

◆ LIMIT_MAX_SAFE_REF_NAME_LEN

#define LIMIT_MAX_SAFE_REF_NAME_LEN   31

Maximum string length and byte storage size of safe reference map names.

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.

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.

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.
Returns
A reference to the Reference Map object.

◆ 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_EnableTrace()

void le_ref_EnableTrace ( le_ref_MapRef_t  mapRef)

Immediately enables tracing on a particular safe reference map object.

Parameters
[in]mapRefReference to the map

◆ 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.