alias_mappings.c File Reference

Implementation of the CAN alias / Node ID mapping buffer. More...

Functions
void	AliasMappings_initialize (void)
	Initializes the alias mapping buffer, clearing all entries and flags.
alias_mapping_info_t *	AliasMappings_get_alias_mapping_info (void)
	Returns a pointer to the internal alias mapping info structure.
void	AliasMappings_set_has_duplicate_alias_flag (void)
	Sets the has_duplicate_alias flag to signal an alias conflict.
void	AliasMappings_clear_has_duplicate_alias_flag (void)
	Clears the has_duplicate_alias flag after conflict resolution.
alias_mapping_t *	AliasMappings_register (uint16_t alias, node_id_t node_id)
	Registers a CAN alias / Node ID pair in the buffer.
void	AliasMappings_unregister (uint16_t alias)
	Removes the entry matching the given alias from the buffer.
alias_mapping_t *	AliasMappings_find_mapping_by_alias (uint16_t alias)
	Finds the mapping entry for the given alias.
alias_mapping_t *	AliasMappings_find_mapping_by_node_id (node_id_t node_id)
	Finds the mapping entry for the given Node ID.
void	AliasMappings_flush (void)
	Clears all alias mappings and resets all flags. Runtime equivalent of initialize().

Detailed Description

Implementation of the CAN alias / Node ID mapping buffer.

Copyright

Copyright (c) 2024, Jim Kueneman All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Single static buffer instance using a linear array. Empty slots are marked by alias = 0 and node_id = 0. First-fit allocation. One alias per Node ID enforced. NOT thread-safe.

Author

Jim Kueneman

Date

4 Mar 2026

Function Documentation

AliasMappings_initialize()

void AliasMappings_initialize

(

void

)

Initializes the alias mapping buffer, clearing all entries and flags.

Warning

Calling during active operation loses all existing mappings and will cause communication failures.

See also

AliasMappings_flush - Runtime equivalent

AliasMappings_get_alias_mapping_info()

alias_mapping_info_t * AliasMappings_get_alias_mapping_info

(

void

)

Returns a pointer to the internal alias mapping info structure.

Returns

Pointer to the alias_mapping_info_t structure (never NULL).

AliasMappings_set_has_duplicate_alias_flag()

void AliasMappings_set_has_duplicate_alias_flag

(

void

)

Sets the has_duplicate_alias flag to signal an alias conflict.

Signals the main loop that an incoming message used one of our reserved aliases.

AliasMappings_clear_has_duplicate_alias_flag()

void AliasMappings_clear_has_duplicate_alias_flag

(

void

)

Clears the has_duplicate_alias flag after conflict resolution.

Clears the duplicate alias flag after the conflict has been resolved.

AliasMappings_register()

alias_mapping_t * AliasMappings_register	(	uint16_t	alias,
		node_id_t	node_id )

Registers a CAN alias / Node ID pair in the buffer.

Algorithm:

1. Validate alias is in range 0x001–0xFFF, return NULL if not
2. Validate node_id is in range 0x000000000001–0xFFFFFFFFFFFF, return NULL if not
3. Iterate through all ALIAS_MAPPING_BUFFER_DEPTH entries
4. On first empty slot (alias == 0) or matching Node ID: store alias and node_id, return pointer to that entry
5. If no slot found, return NULL (buffer full)

Use cases:

• Storing a newly allocated alias during node login
• Updating an alias after conflict resolution
• Recording remote node aliases learned from AMD frames

* @param alias    12-bit CAN alias (valid range: 0x001–0xFFF).
* @param node_id  48-bit OpenLCB Node ID (valid range: 0x000000000001–0xFFFFFFFFFFFF).
* 

Returns

Pointer to the registered alias_mapping_t entry, or NULL on failure.

Warning

Returns NULL when the buffer is full — caller MUST check before use.

Out-of-range alias or node_id values return NULL.

An existing Node ID entry will have its alias silently replaced.

See also

AliasMappings_unregister

AliasMappings_find_mapping_by_alias

AliasMappings_find_mapping_by_node_id

AliasMappings_unregister()

void AliasMappings_unregister

(

uint16_t

alias

)

Removes the entry matching the given alias from the buffer.

Algorithm:

1. Iterate through all ALIAS_MAPPING_BUFFER_DEPTH entries
2. On matching alias: clear all four fields and break
3. If no match found, return without action

* @param alias  12-bit CAN alias to remove.
* 

See also

AliasMappings_register

AliasMappings_flush

AliasMappings_find_mapping_by_alias()

alias_mapping_t * AliasMappings_find_mapping_by_alias

(

uint16_t

alias

)

Finds the mapping entry for the given alias.

Algorithm:

1. Validate alias is in range 0x001–0xFFF, return NULL if not
2. Iterate through all entries; return pointer on first match
3. Return NULL if no match found

* @param alias  12-bit CAN alias to search for.
* 

Returns

Pointer to the matching alias_mapping_t entry, or NULL if not found.

Warning

NULL is returned when not found — caller MUST check before use.

See also

AliasMappings_find_mapping_by_node_id

AliasMappings_find_mapping_by_node_id()

alias_mapping_t * AliasMappings_find_mapping_by_node_id

(

node_id_t

node_id

)

Finds the mapping entry for the given Node ID.

Algorithm:

1. Validate node_id is in range 0x000000000001–0xFFFFFFFFFFFF, return NULL if not
2. Iterate through all entries; return pointer on first match
3. Return NULL if no match found

* @param node_id  48-bit OpenLCB Node ID to search for.
* 

Returns

Pointer to the matching alias_mapping_t entry, or NULL if not found.

Warning

NULL is returned when not found — caller MUST check before use.

See also

AliasMappings_find_mapping_by_alias

AliasMappings_flush()

void AliasMappings_flush

(

void

)

Clears all alias mappings and resets all flags. Runtime equivalent of initialize().

Clears all alias mappings and resets all flags.