CDC Badge OS
Firmware for the CDC Badge v1.0 hardware security key
Loading...
Searching...
No Matches
vcard_store.cpp File Reference
#include "mod_vcard/vcard_store.h"
#include "cdc_core/Hash.h"
#include "cdc_log.h"
#include "nvs.h"
#include "nvs_flash.h"
#include "esp_attr.h"
#include <cctype>
#include <cstdio>
#include <cstring>

Go to the source code of this file.

Classes

struct  cdc::mod_vcard::vcard_meta_t

Namespaces

namespace  cdc
namespace  cdc::mod_vcard

Functions

static uint32_t fnv1a_hash (const char *data, size_t len)
 Computes FNV-1a hash for vCard duplicate tracking.
static void vcard_key_for_slot (char *out, size_t out_len, uint16_t slot)
 Formats NVS key name for a card slot.
static void vcard_trim_cr (char *line)
 Trims trailing CR/LF characters from one line.
static bool vcard_line_has_content (const char *line, size_t len)
 Checks whether a vCard line contains meaningful field content.
size_t vcard_filter_empty_fields (char *vcard, size_t len)
 Removes empty optional fields from vCard text in-place.
static bool vcard_extract_line (const char *vcard, const char *prefix, char *out, size_t out_len)
 Extracts value from first vCard line matching prefix.
static void vcard_parse_names (const char *vcard, char *last, size_t last_len, char *display, size_t display_len)
 Derives sortable last-name and display-name fields from vCard.
static void set_err (char *err, size_t err_len, const char *msg)
 Writes error text into bounded output buffer.
static bool vcard_validate (const char *vcard, size_t len, char *err, size_t err_len)
 Validates basic vCard format constraints.
static void vcard_load_own (void)
 Lazily loads local own-vCard from NVS cache.
bool vcard_store_set_own (const char *vcard, size_t len, char *err, size_t err_len)
 Stores local own-vCard after validation and field filtering.
size_t vcard_store_get_own (char *out, size_t max_len)
 Retrieves local own-vCard text.
bool vcard_store_has_own (void)
 Returns whether local own-vCard exists.
bool vcard_store_get_display_own (char *out, size_t max_len)
 Retrieves display name derived from local own-vCard.
bool vcard_store_clear_own (void)
 Deletes local own-vCard from storage.
void vcard_store_init (void)
 Initializes metadata cache for stored peer vCards.
uint16_t vcard_store_count (void)
 Returns number of stored peer vCards.
static bool vcard_is_duplicate (nvs_handle_t nvs, const char *vcard, size_t len, uint32_t hash)
 Checks whether candidate vCard is already stored.
bool vcard_store_contains (const char *vcard, size_t len)
 Reports whether an exact-text vCard is already stored.
bool vcard_store_add (const char *vcard, size_t len, char *err, size_t err_len)
 Adds peer vCard to first free slot after validation and duplicate check.
bool vcard_store_update (uint16_t slot, const char *vcard, size_t len, char *err, size_t err_len)
 Overwrites the vCard stored at slot in place after validation.
bool vcard_store_delete (uint16_t slot)
 Deletes peer vCard at slot index.
size_t vcard_store_get (uint16_t slot, char *out, size_t max_len)
 Retrieves raw vCard text from slot.
bool vcard_store_get_display (uint16_t slot, char *out, size_t max_len)
 Retrieves cached display label for slot.
static void copy_field (char *dst, size_t dst_size, const char *src, size_t src_len)
 Copies a bounded value into a fixed-size destination buffer.
static size_t trim_line_len (const char *line, size_t len)
 Trims trailing CR and LF and whitespace characters from a length-bounded view.
static const char * line_value (const char *line, size_t line_len, size_t *out_len)
 Returns pointer to the value portion of a vCard line and its length. For a line like TEL;TYPE=HOME:1234, this returns the part after the first colon.
static bool match_property (const char *line, size_t line_len, const char *prop, const char *type_value)
 Tests whether one vCard property prefix matches a line, optionally accepting a TYPE=... parameter and a value sub-prefix (for IMPP). Matching is case-insensitive for the property name and parameter value.
static void parse_line_into_struct (const char *line, size_t line_len, vcard_data_t *out)
 Parses a single vCard line into the structured data, when recognized.
bool vcard_parse_to_struct (const char *raw, vcard_data_t *out)
 Parses raw vCard 4.0 text into a structured representation.
static bool append_field (char *buf, size_t buf_size, size_t *pos, const char *prefix, const char *value)
 Appends prefix:value\n to the output buffer if value is non-empty.
size_t vcard_generate_from_struct (const vcard_data_t *data, char *out_buf, size_t buf_len)
 Generates a vCard 4.0 text representation from the structured data.
uint16_t vcard_store_get_sorted (uint16_t *out_slots, uint16_t max_slots)
 Returns slot indices of stored cards sorted by last name.

Variables

static const char * TAG = "VCARD"
static constexpr const char * VCARD_NAMESPACE = "mod_vcard"
static constexpr const char * VCARD_KEY_OWN = "own"
static char g_own_vcard [768+1]
static bool g_own_loaded = false
static bool g_own_present = false
static vcard_meta_t g_cards [100]
static bool g_cards_loaded = false
static uint16_t g_card_count = 0

Function Documentation

◆ append_field()

bool append_field ( char * buf,
size_t buf_size,
size_t * pos,
const char * prefix,
const char * value )
static

Appends prefix:value\n to the output buffer if value is non-empty.

Definition at line 963 of file vcard_store.cpp.

Referenced by vcard_generate_from_struct().

◆ copy_field()

void copy_field ( char * dst,
size_t dst_size,
const char * src,
size_t src_len )
static

Copies a bounded value into a fixed-size destination buffer.

Definition at line 731 of file vcard_store.cpp.

Referenced by parse_line_into_struct().

◆ fnv1a_hash()

uint32_t fnv1a_hash ( const char * data,
size_t len )
static

Computes FNV-1a hash for vCard duplicate tracking.

Parameters
dataInput buffer.
lenInput length.
Returns
32-bit hash value.

Definition at line 47 of file vcard_store.cpp.

References cdc::core::hash::fnv1a_32().

Referenced by vcard_store_add(), vcard_store_contains(), vcard_store_init(), and vcard_store_update().

◆ line_value()

const char * line_value ( const char * line,
size_t line_len,
size_t * out_len )
static

Returns pointer to the value portion of a vCard line and its length. For a line like TEL;TYPE=HOME:1234, this returns the part after the first colon.

Parameters
linePointer to start of line.
line_lenLength of the line (without terminator).
out_lenOutput: length of the value portion.
Returns
Pointer into line at value start, or nullptr if no colon found.

Definition at line 757 of file vcard_store.cpp.

References trim_line_len().

Referenced by parse_line_into_struct().

◆ match_property()

bool match_property ( const char * line,
size_t line_len,
const char * prop,
const char * type_value )
static

Tests whether one vCard property prefix matches a line, optionally accepting a TYPE=... parameter and a value sub-prefix (for IMPP). Matching is case-insensitive for the property name and parameter value.

Parameters
linePointer to line start.
line_lenTotal line length.
propProperty name (e.g. "TEL", "EMAIL").
type_valueOptional TYPE= match (e.g. "HOME"); pass nullptr to skip.
Returns
true if the line matches.

Definition at line 777 of file vcard_store.cpp.

Referenced by parse_line_into_struct().

◆ parse_line_into_struct()

◆ set_err()

void set_err ( char * err,
size_t err_len,
const char * msg )
static

Writes error text into bounded output buffer.

Parameters
errOutput error buffer.
err_lenOutput buffer size.
Message transfer (badge-to-badge)Error message text.

Definition at line 271 of file vcard_store.cpp.

Referenced by vcard_store_add(), vcard_store_set_own(), vcard_store_update(), and vcard_validate().

◆ trim_line_len()

size_t trim_line_len ( const char * line,
size_t len )
static

Trims trailing CR and LF and whitespace characters from a length-bounded view.

Definition at line 741 of file vcard_store.cpp.

Referenced by line_value(), and parse_line_into_struct().

◆ vcard_extract_line()

bool vcard_extract_line ( const char * vcard,
const char * prefix,
char * out,
size_t out_len )
static

Extracts value from first vCard line matching prefix.

Parameters
vcardvCard text.
prefixLine prefix (for example FN:).
outOutput value buffer.
out_lenOutput buffer size.
Returns
true if matching line was found.

Definition at line 170 of file vcard_store.cpp.

References vcard_trim_cr().

Referenced by vcard_parse_names().

◆ vcard_filter_empty_fields()

size_t vcard_filter_empty_fields ( char * vcard,
size_t len )

Removes empty optional fields from vCard text in-place.

Parameters
vcardMutable vCard buffer.
lenInput length.
Returns
New filtered length.

Definition at line 126 of file vcard_store.cpp.

References vcard_line_has_content(), and VCARD_MAX_LEN.

Referenced by vcard_store_add(), vcard_store_set_own(), and vcard_store_update().

◆ vcard_generate_from_struct()

size_t vcard_generate_from_struct ( const vcard_data_t * data,
char * out_buf,
size_t buf_len )

◆ vcard_is_duplicate()

bool vcard_is_duplicate ( nvs_handle_t nvs,
const char * vcard,
size_t len,
uint32_t hash )
static

Checks whether candidate vCard is already stored.

Parameters
NVS (plugin-namespaced)Open NVS handle.
vcardCandidate vCard text.
lenCandidate length.
hashCandidate hash (currently unused optimization hint).
Returns
true if duplicate exists.

Definition at line 498 of file vcard_store.cpp.

References vcard_key_for_slot(), VCARD_MAX_CARDS, and VCARD_MAX_LEN.

Referenced by vcard_store_add(), and vcard_store_contains().

◆ vcard_key_for_slot()

void vcard_key_for_slot ( char * out,
size_t out_len,
uint16_t slot )
static

Formats NVS key name for a card slot.

Parameters
outOutput key buffer.
out_lenOutput buffer size.
slotSlot index.

Definition at line 57 of file vcard_store.cpp.

Referenced by vcard_is_duplicate(), vcard_store_add(), vcard_store_delete(), vcard_store_get(), vcard_store_init(), and vcard_store_update().

◆ vcard_line_has_content()

bool vcard_line_has_content ( const char * line,
size_t len )
static

Checks whether a vCard line contains meaningful field content.

Parameters
lineLine pointer.
lenLine length.
Returns
true if line should be retained.

Definition at line 79 of file vcard_store.cpp.

Referenced by vcard_filter_empty_fields().

◆ vcard_load_own()

void vcard_load_own ( void )
static

Lazily loads local own-vCard from NVS cache.

Definition at line 316 of file vcard_store.cpp.

References g_own_loaded, g_own_present, g_own_vcard, VCARD_KEY_OWN, and VCARD_NAMESPACE.

Referenced by vcard_store_get_display_own(), vcard_store_get_own(), and vcard_store_has_own().

◆ vcard_parse_names()

void vcard_parse_names ( const char * vcard,
char * last,
size_t last_len,
char * display,
size_t display_len )
static

Derives sortable last-name and display-name fields from vCard.

Parameters
vcardvCard text.
lastOutput last-name buffer.
last_lenLast-name buffer size.
displayOutput display-name buffer.
display_lenDisplay-name buffer size.

Definition at line 203 of file vcard_store.cpp.

References vcard_extract_line().

Referenced by vcard_store_add(), vcard_store_get_display_own(), vcard_store_init(), and vcard_store_update().

◆ vcard_parse_to_struct()

bool vcard_parse_to_struct ( const char * raw,
vcard_data_t * out )

Parses raw vCard 4.0 text into a structured representation.

Parses vCard 4.0 raw text into a structured vcard_data_t.

Definition at line 935 of file vcard_store.cpp.

References parse_line_into_struct().

Referenced by cdc::mod_vcard::VcardWizard::edit(), cdc::mod_vcard::VcardWizard::editReceived(), cdc::mod_vcard::showVcardDetails(), and cdc::mod_vcard::showVcardQr().

◆ vcard_store_add()

bool vcard_store_add ( const char * vcard,
size_t len,
char * err,
size_t err_len )

Adds peer vCard to first free slot after validation and duplicate check.

Parameters
vcardvCard text.
lenInput length.
errOutput error buffer.
err_lenError buffer size.
Returns
true on successful storage.

Definition at line 539 of file vcard_store.cpp.

References fnv1a_hash(), g_card_count, g_cards, set_err(), vcard_filter_empty_fields(), vcard_is_duplicate(), vcard_key_for_slot(), VCARD_MAX_CARDS, VCARD_MAX_LEN, VCARD_NAMESPACE, vcard_parse_names(), vcard_store_init(), and vcard_validate().

Referenced by cdc::mod_vcard::deliverVcard(), cdc::mod_vcard::importReceivedVcard(), and cdc::mod_vcard::wizardFinish().

◆ vcard_store_clear_own()

bool vcard_store_clear_own ( void )

Deletes local own-vCard from storage.

Returns
true on successful deletion.

Definition at line 429 of file vcard_store.cpp.

References g_own_loaded, g_own_present, g_own_vcard, VCARD_KEY_OWN, and VCARD_NAMESPACE.

Referenced by cdc::mod_vcard::cmdVcardDelete().

◆ vcard_store_contains()

bool vcard_store_contains ( const char * vcard,
size_t len )

Reports whether an exact-text vCard is already stored.

Parameters
vcardCandidate vCard text.
lenCandidate length.
Returns
true if a stored card matches vcard byte for byte.

Definition at line 518 of file vcard_store.cpp.

References fnv1a_hash(), vcard_is_duplicate(), VCARD_NAMESPACE, and vcard_store_init().

Referenced by cdc::mod_vcard::importReceivedVcard().

◆ vcard_store_count()

uint16_t vcard_store_count ( void )

Returns number of stored peer vCards.

Returns
Peer vCard count.

Definition at line 485 of file vcard_store.cpp.

References g_card_count, and vcard_store_init().

◆ vcard_store_delete()

bool vcard_store_delete ( uint16_t slot)

Deletes peer vCard at slot index.

Parameters
slotSlot index.
Returns
true on successful deletion.

Definition at line 654 of file vcard_store.cpp.

References g_card_count, g_cards, vcard_key_for_slot(), VCARD_MAX_CARDS, VCARD_NAMESPACE, and vcard_store_init().

Referenced by cdc::mod_vcard::cmdVcardDelete(), and cdc::mod_vcard::onReceivedDeleteConfirm().

◆ vcard_store_get()

size_t vcard_store_get ( uint16_t slot,
char * out,
size_t max_len )

Retrieves raw vCard text from slot.

Parameters
slotSlot index.
outOutput buffer.
max_lenOutput buffer size.
Returns
Number of copied bytes.

Definition at line 683 of file vcard_store.cpp.

References g_cards, vcard_key_for_slot(), VCARD_MAX_CARDS, VCARD_NAMESPACE, and vcard_store_init().

Referenced by cdc::mod_vcard::cmdVcardGet(), cdc::mod_vcard::ctxReceivedForward(), cdc::mod_vcard::ctxReceivedQr(), cdc::mod_vcard::VcardWizard::editReceived(), cdc::mod_vcard::VcardModule::exportBackup(), and cdc::mod_vcard::onReceivedSelect().

◆ vcard_store_get_display()

bool vcard_store_get_display ( uint16_t slot,
char * out,
size_t max_len )

Retrieves cached display label for slot.

Parameters
slotSlot index.
outOutput label buffer.
max_lenOutput buffer size.
Returns
true on success.

Definition at line 717 of file vcard_store.cpp.

References g_cards, VCARD_MAX_CARDS, and vcard_store_init().

Referenced by cdc::mod_vcard::cmdVcardList(), cdc::mod_vcard::cmdVcardSet(), and cdc::mod_vcard::rebuildReceivedList().

◆ vcard_store_get_display_own()

bool vcard_store_get_display_own ( char * out,
size_t max_len )

Retrieves display name derived from local own-vCard.

Parameters
outOutput buffer.
max_lenOutput buffer size.
Returns
true on success.

Definition at line 413 of file vcard_store.cpp.

References g_own_present, g_own_vcard, vcard_load_own(), and vcard_parse_names().

◆ vcard_store_get_own()

size_t vcard_store_get_own ( char * out,
size_t max_len )

Retrieves local own-vCard text.

Parameters
outOutput buffer.
max_lenOutput buffer size.
Returns
Number of copied bytes.

Definition at line 387 of file vcard_store.cpp.

References g_own_present, g_own_vcard, and vcard_load_own().

Referenced by cdc::mod_vcard::cmdVcardGet(), cdc::mod_vcard::VcardWizard::edit(), cdc::mod_vcard::VcardModule::exportBackup(), cdc::mod_vcard::onMainMenuSelect(), and cdc::mod_vcard::onMyVcardLockscreenSelect().

◆ vcard_store_get_sorted()

uint16_t vcard_store_get_sorted ( uint16_t * out_slots,
uint16_t max_slots )

Returns slot indices of stored cards sorted by last name.

Parameters
out_slotsOutput slot-index array.
max_slotsMaximum writable entries.
Returns
Number of returned slot indices.

Definition at line 1048 of file vcard_store.cpp.

References g_cards, VCARD_MAX_CARDS, and vcard_store_init().

Referenced by cdc::mod_vcard::cmdVcardList(), cdc::mod_vcard::VcardModule::exportBackup(), and cdc::mod_vcard::rebuildReceivedList().

◆ vcard_store_has_own()

bool vcard_store_has_own ( void )

Returns whether local own-vCard exists.

Returns
true if own-vCard is present.

Definition at line 402 of file vcard_store.cpp.

References g_own_present, and vcard_load_own().

Referenced by cdc::mod_vcard::onMainMenuSelect().

◆ vcard_store_init()

◆ vcard_store_set_own()

bool vcard_store_set_own ( const char * vcard,
size_t len,
char * err,
size_t err_len )

Stores local own-vCard after validation and field filtering.

Parameters
vcardvCard text.
lenInput length.
errOutput error buffer.
err_lenError buffer size.
Returns
true on successful persistence.

Definition at line 343 of file vcard_store.cpp.

References g_own_loaded, g_own_present, g_own_vcard, LOG_I, set_err(), TAG, vcard_filter_empty_fields(), VCARD_KEY_OWN, VCARD_MAX_LEN, VCARD_NAMESPACE, and vcard_validate().

Referenced by cdc::mod_vcard::VcardModule::importBackup(), cdc::mod_vcard::vcardLineInterceptor(), and cdc::mod_vcard::wizardFinish().

◆ vcard_store_update()

bool vcard_store_update ( uint16_t slot,
const char * vcard,
size_t len,
char * err,
size_t err_len )

Overwrites the vCard stored at slot in place after validation.

Overwrites the vCard stored at slot in place after validation.

Parameters
slotSlot index of an existing stored card.
vcardNew vCard text.
lenNew vCard length.
errOutput error buffer.
err_lenError buffer size.
Returns
true on successful update.

Definition at line 610 of file vcard_store.cpp.

References fnv1a_hash(), g_cards, set_err(), vcard_filter_empty_fields(), vcard_key_for_slot(), VCARD_MAX_CARDS, VCARD_MAX_LEN, VCARD_NAMESPACE, vcard_parse_names(), vcard_store_init(), and vcard_validate().

Referenced by cdc::mod_vcard::vcardLineInterceptor(), and cdc::mod_vcard::wizardFinish().

◆ vcard_trim_cr()

void vcard_trim_cr ( char * line)
static

Trims trailing CR/LF characters from one line.

Parameters
lineMutable line buffer.

Definition at line 65 of file vcard_store.cpp.

Referenced by vcard_extract_line().

◆ vcard_validate()

bool vcard_validate ( const char * vcard,
size_t len,
char * err,
size_t err_len )
static

Validates basic vCard format constraints.

Parameters
vcardvCard text buffer.
lenInput length.
errOutput error buffer.
err_lenError buffer size.
Returns
true if vCard is acceptable.

Definition at line 285 of file vcard_store.cpp.

References set_err(), and VCARD_MAX_LEN.

Referenced by vcard_store_add(), vcard_store_set_own(), and vcard_store_update().

Variable Documentation

◆ g_card_count

uint16_t g_card_count = 0
static

◆ g_cards

◆ g_cards_loaded

bool g_cards_loaded = false
static

Definition at line 38 of file vcard_store.cpp.

Referenced by vcard_store_init().

◆ g_own_loaded

bool g_own_loaded = false
static

Definition at line 19 of file vcard_store.cpp.

Referenced by vcard_load_own(), vcard_store_clear_own(), and vcard_store_set_own().

◆ g_own_present

◆ g_own_vcard

char g_own_vcard[768+1]
static

◆ TAG

const char* TAG = "VCARD"
static

Definition at line 13 of file vcard_store.cpp.

◆ VCARD_KEY_OWN

const char* VCARD_KEY_OWN = "own"
staticconstexpr

Definition at line 16 of file vcard_store.cpp.

Referenced by vcard_load_own(), vcard_store_clear_own(), and vcard_store_set_own().

◆ VCARD_NAMESPACE