vCard store

Read and manage the badge's own vCard and received vCards. More...

Macros
#define	HOST_VCARD_MAX_LEN   768
	Maximum length of a single vCard text including the NUL.

Functions
int	host_vcard_get_own (char *out, size_t out_size)
	Copy the badge's own vCard text into out.
int	host_vcard_received_count (void)
	Number of received vCards in the store.
int	host_vcard_received_get (uint16_t index, char *out, size_t out_size)
	Copy the received vCard at sorted position index into out.
int	host_vcard_received_display (uint16_t index, char *out, size_t out_size)
	Copy the display name of the received vCard at sorted position index into out (for list rows).
int	host_vcard_set_own (const char *vcard, size_t len)
	Set / replace the badge's own vCard.
int	host_vcard_received_add (const char *vcard, size_t len)
	Store a new received vCard.
int	host_vcard_received_update (uint16_t index, const char *vcard, size_t len)
	Overwrite the received vCard at sorted position index.
int	host_vcard_received_delete (uint16_t index)
	Delete the received vCard at sorted position index.

Detailed Description

Read and manage the badge's own vCard and received vCards.

Requires the manifest capability vCard store: true. All strings are vCard 4.0 UTF-8 text as stored; display strings are the parsed formatted names used by the firmware's own contact list. Received cards are addressed by their sorted position (the order the firmware lists them in), 0-based; write operations re-sort, so re-read positions after any mutation.

Macro Definition Documentation

HOST_VCARD_MAX_LEN

#define HOST_VCARD_MAX_LEN   768

Maximum length of a single vCard text including the NUL.

Definition at line 2010 of file host_api.h.

Referenced by host_vcard_received_add(), host_vcard_received_update(), and host_vcard_set_own().

Function Documentation

host_vcard_get_own()

int host_vcard_get_own	(	char *	out,
		size_t	out_size )

Copy the badge's own vCard text into out.

Parameters

out	Caller buffer; the result is NUL-terminated.
out_size	Capacity of out (HOST_VCARD_MAX_LEN + 1 always fits).

Returns

Bytes copied (> 0), HOST_ERR_NOT_FOUND when no own card is set, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY.

Definition at line 41 of file host_api_vcard.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and vcard_store_get_own().

Referenced by cdc::plugin_manager::w_host_vcard_get_own().

host_vcard_received_add()

int host_vcard_received_add	(	const char *	vcard,
		size_t	len )

Store a new received vCard.

Parameters

vCard store	vCard 4.0 UTF-8 text, at most HOST_VCARD_MAX_LEN - 1 bytes.
len	Text length.

Returns

HOST_OK, HOST_ERR_INVALID_ARG (validation failed), HOST_ERR_BUSY (duplicate already stored), HOST_ERR_NO_MEMORY (store full), HOST_ERR_NO_CAPABILITY.

Definition at line 84 of file host_api_vcard.cpp.

References HOST_ERR_BUSY, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NO_MEMORY, HOST_OK, HOST_VCARD_MAX_LEN, LOG_W, VCARD_MAX_CARDS, vcard_store_add(), vcard_store_contains(), and vcard_store_count().

Referenced by cdc::plugin_manager::w_host_vcard_received_add().

host_vcard_received_count()

int host_vcard_received_count

(

void

)

Number of received vCards in the store.

Returns

Count >= 0, or HOST_ERR_NO_CAPABILITY.

Definition at line 48 of file host_api_vcard.cpp.

References HOST_ERR_NO_CAPABILITY, and vcard_store_count().

Referenced by cdc::plugin_manager::w_host_vcard_received_count().

host_vcard_received_delete()

int host_vcard_received_delete

(

uint16_t

index

)

Delete the received vCard at sorted position index.

Returns

HOST_OK, HOST_ERR_NOT_FOUND on a bad index, HOST_ERR_NO_CAPABILITY.

Definition at line 110 of file host_api_vcard.cpp.

References HOST_ERR_GENERIC, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_OK, and vcard_store_delete().

Referenced by cdc::plugin_manager::w_host_vcard_received_delete().

host_vcard_received_display()

int host_vcard_received_display	(	uint16_t	index,
		char *	out,
		size_t	out_size )

Copy the display name of the received vCard at sorted position index into out (for list rows).

Returns

Bytes copied (> 0), HOST_ERR_NOT_FOUND on a bad index, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY.

Definition at line 62 of file host_api_vcard.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and vcard_store_get_display().

Referenced by cdc::plugin_manager::w_host_vcard_received_display().

host_vcard_received_get()

int host_vcard_received_get	(	uint16_t	index,
		char *	out,
		size_t	out_size )

Copy the received vCard at sorted position index into out.

Parameters

index	0-based sorted position, < host_vcard_received_count().
out	Caller buffer; the result is NUL-terminated.
out_size	Capacity of out.

Returns

Bytes copied (> 0), HOST_ERR_NOT_FOUND on a bad index, HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY.

Definition at line 53 of file host_api_vcard.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, and vcard_store_get().

Referenced by cdc::plugin_manager::w_host_vcard_received_get().

host_vcard_received_update()

int host_vcard_received_update	(	uint16_t	index,
		const char *	vcard,
		size_t	len )

Overwrite the received vCard at sorted position index.

Returns

HOST_OK, HOST_ERR_NOT_FOUND on a bad index, HOST_ERR_INVALID_ARG (validation failed), HOST_ERR_NO_CAPABILITY.

Definition at line 97 of file host_api_vcard.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_ERR_NOT_FOUND, HOST_OK, HOST_VCARD_MAX_LEN, LOG_W, and vcard_store_update().

Referenced by cdc::plugin_manager::w_host_vcard_received_update().

host_vcard_set_own()

int host_vcard_set_own	(	const char *	vcard,
		size_t	len )

Set / replace the badge's own vCard.

Parameters

vCard store	vCard 4.0 UTF-8 text, at most HOST_VCARD_MAX_LEN - 1 bytes.
len	Text length.

Returns

HOST_OK, HOST_ERR_INVALID_ARG (validation failed - see log), HOST_ERR_NO_CAPABILITY.

Definition at line 73 of file host_api_vcard.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_CAPABILITY, HOST_OK, HOST_VCARD_MAX_LEN, LOG_W, and vcard_store_set_own().

Referenced by cdc::plugin_manager::w_host_vcard_set_own().