Topics
	KeyValue store management

	KeyValue store entries

	KeyValue store watcher

	KeyValue store status

Functions
NATS_EXTERN natsStatus	kvStore_Get (kvEntry *new_entry, kvStore kv, const char *key)
	Returns the latest entry for the key.

NATS_EXTERN natsStatus	kvStore_GetRevision (kvEntry *new_entry, kvStore kv, const char *key, uint64_t revision)
	Returns the entry at the specific revision for the key.

NATS_EXTERN natsStatus	kvStore_Put (uint64_t rev, kvStore kv, const char key, const void data, int len)
	Places the new value for the key into the store.

NATS_EXTERN natsStatus	kvStore_PutString (uint64_t rev, kvStore kv, const char key, const char data)
	Places the new value (as a string) for the key into the store.

NATS_EXTERN natsStatus	kvStore_Create (uint64_t rev, kvStore kv, const char key, const void data, int len)
	Places the value for the key into the store if and only if the key does not exist.

NATS_EXTERN natsStatus	kvStore_CreateString (uint64_t rev, kvStore kv, const char key, const char data)
	Places the value (as a string) for the key into the store if and only if the key does not exist.

NATS_EXTERN natsStatus	kvStore_Update (uint64_t rev, kvStore kv, const char key, const void data, int len, uint64_t last)
	Updates the value for the key into the store if and only if the latest revision matches.

NATS_EXTERN natsStatus	kvStore_UpdateString (uint64_t rev, kvStore kv, const char key, const char data, uint64_t last)
	Updates the value (as a string) for the key into the store if and only if the latest revision matches.

NATS_EXTERN natsStatus	kvStore_Delete (kvStore kv, const char key)
	Deletes a key by placing a delete marker and leaving all revisions.

NATS_EXTERN natsStatus	kvStore_Purge (kvStore kv, const char key, kvPurgeOptions *opts)
	Deletes a key by placing a purge marker and removing all revisions.

NATS_EXTERN natsStatus	kvWatchOptions_Init (kvWatchOptions *opts)
	Initializes a KeyValue watcher options structure.

NATS_EXTERN natsStatus	kvPurgeOptions_Init (kvPurgeOptions *opts)
	Initializes a KeyValue purge options structure.

NATS_EXTERN natsStatus	kvStore_PurgeDeletes (kvStore kv, kvPurgeOptions opts)
	Purge and removes delete markers.

NATS_EXTERN natsStatus	kvStore_Watch (kvWatcher *new_watcher, kvStore kv, const char keys, kvWatchOptions opts)
	Returns a watcher for any updates to keys that match the `keys` argument.

NATS_EXTERN natsStatus	kvStore_WatchAll (kvWatcher *new_watcher, kvStore kv, kvWatchOptions *opts)
	Returns a watcher for any updates to any keys of the KeyValue store bucket.

NATS_EXTERN natsStatus	kvStore_Keys (kvKeysList list, kvStore kv, kvWatchOptions *opts)
	Returns all keys in the bucket.

NATS_EXTERN void	kvKeysList_Destroy (kvKeysList *list)
	Destroys this list of KeyValue store key strings.

NATS_EXTERN natsStatus	kvStore_History (kvEntryList list, kvStore kv, const char key, kvWatchOptions opts)
	Returns all historical entries for the key.

NATS_EXTERN void	kvEntryList_Destroy (kvEntryList *list)
	Destroys this list of KeyValue store entries.

NATS_EXTERN const char *	kvStore_Bucket (kvStore *kv)
	Returns the bucket name of this KeyValue store object.

NATS_EXTERN natsStatus	kvStore_Status (kvStatus *new_status, kvStore kv)
	Returns the status and configuration of a bucket.

Detailed Description

A KeyValue store is a materialized view of JetStream.

Warning: EXPERIMENTAL FEATURE! We reserve the right to change the API without necessarily bumping the major version of the library.

Function Documentation

◆ kvStore_Get()

NATS_EXTERN natsStatus kvStore_Get	(	kvEntry **	new_entry,
		kvStore *	kv,
		const char *	key )

Returns the latest entry for the key.

Note: The entry should be destroyed to release memory using kvEntry_Destroy.

Parameters

new_entry	the location where to store the pointer to the entry associated with the `key`.
kv	the pointer to the kvStore object.
key	the name of the key.

◆ kvStore_GetRevision()

NATS_EXTERN natsStatus kvStore_GetRevision	(	kvEntry **	new_entry,
		kvStore *	kv,
		const char *	key,
		uint64_t	revision )

Returns the entry at the specific revision for the key, or NATS_NOT_FOUND if there is no entry for that key and revision.

Note: The entry should be destroyed to release memory using kvEntry_Destroy.

Parameters

new_entry	the location where to store the pointer to the entry associated with the `key`.
kv	the pointer to the kvStore object.
key	the name of the key.
revision	the revision of the entry (must be > 0).

◆ kvStore_Put()

NATS_EXTERN natsStatus kvStore_Put	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const void *	data,
		int	len )

Places the new value for the key into the store.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the data in memory.
len	the number of bytes to copy from the data's memory location.

◆ kvStore_PutString()

NATS_EXTERN natsStatus kvStore_PutString	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const char *	data )

Places the new value, as a string, for the key into the store.

Note: This is equivalent of calling kvStore_Put with (int) strlen(data).

Warning: The NULL terminating character is not included in the number of bytes stored in the KeyValue store.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the string to store.

◆ kvStore_Create()

NATS_EXTERN natsStatus kvStore_Create	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const void *	data,
		int	len )

Places the value for the key into the store if and only if the key does not exist.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the data in memory.
len	the number of bytes to copy from the data's memory location.

◆ kvStore_CreateString()

NATS_EXTERN natsStatus kvStore_CreateString	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const char *	data )

Places the value (as a string) for the key into the store if and only if the key does not exist.

Note: This is equivalent of calling kvStore_Create with (int) strlen(data).

Warning: The NULL terminating character is not included in the number of bytes stored in the KeyValue store.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the string.

◆ kvStore_Update()

NATS_EXTERN natsStatus kvStore_Update	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const void *	data,
		int	len,
		uint64_t	last )

Updates the value for the key into the store if and only if the latest revision matches.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the data in memory.
len	the number of bytes to copy from the data's memory location.
last	the expected latest revision prior to the update.

◆ kvStore_UpdateString()

NATS_EXTERN natsStatus kvStore_UpdateString	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const char *	data,
		uint64_t	last )

Updates the value (as a string) for the key into the store if and only if the latest revision matches.

Note: This is equivalent of calling kvStore_Update with (int) strlen(data).

Warning: The NULL terminating character is not included in the number of bytes stored in the KeyValue store.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the string.
last	the expected latest revision prior to the update.

◆ kvStore_Delete()

NATS_EXTERN natsStatus kvStore_Delete	(	kvStore *	kv,
		const char *	key )

Deletes a key by placing a delete marker and leaving all revisions.

Parameters

kv	the pointer to the kvStore object.
key	the name of the key.

◆ kvStore_Purge()

NATS_EXTERN natsStatus kvStore_Purge	(	kvStore *	kv,
		const char *	key,
		kvPurgeOptions *	opts )

Deletes a key by placing a purge marker and removing all revisions.

Parameters

kv	the pointer to the kvStore object.
key	the name of the key.
opts	the pointer to the kvPurgeOptions, possibly `NULL`.

◆ kvWatchOptions_Init()

NATS_EXTERN natsStatus kvWatchOptions_Init ( kvWatchOptions * opts )

Use this before setting specific watcher options and passing it to kvStore_Watch.

Parameters

opts	the pointer to the kvWatchOptions to initialize.

◆ kvPurgeOptions_Init()

NATS_EXTERN natsStatus kvPurgeOptions_Init ( kvPurgeOptions * opts )

Use this before setting specific purge options and passing it to kvStore_Purge or kvStore_PurgeDeletes.

Parameters

opts	the pointer to the kvPurgeOptions to initialize.

◆ kvStore_PurgeDeletes()

NATS_EXTERN natsStatus kvStore_PurgeDeletes	(	kvStore *	kv,
		kvPurgeOptions *	opts )

Removes data and delete markers, but may keep the markers that are considered more recent than a certain threshold (default is 30 minutes).

This is a maintenance option if there is a larger buildup of delete markers.

Note: Use kvPurgeOptions.Timeout to specify how long to wait (in milliseconds) in gathering all keys that have purge markers. This function will still purge some of the keys and return NATS_TIMEOUT to indicate that it may not have deleted them all.

See also: kvPurgeOptions_Init

Parameters

kv	the pointer to the kvStore object.
opts	the pointer to the kvPurgeOptions, possibly `NULL`.

◆ kvStore_Watch()

NATS_EXTERN natsStatus kvStore_Watch	(	kvWatcher **	new_watcher,
		kvStore *	kv,
		const char *	keys,
		kvWatchOptions *	opts )

Returns a watcher for any updates to keys that match the keys argument, which could include wildcard.

A NULL entry will be posted when the watcher has received all initial values.

Call kvWatcher_Next to get the next kvEntry.

Note: The watcher should be destroyed to release memory using kvWatcher_Destroy.

Parameters

new_watcher	the location where to store the pointer to the new kvWatcher object.
kv	the pointer to the kvStore object.
keys	the keys (wildcard possible) to create the watcher for.
opts	the watcher options, possibly `NULL`.

◆ kvStore_WatchAll()

NATS_EXTERN natsStatus kvStore_WatchAll	(	kvWatcher **	new_watcher,
		kvStore *	kv,
		kvWatchOptions *	opts )

Returns a watcher for any updates to any keys of the KeyValue store bucket.

A NULL entry will be posted when the watcher has received all initial values.

Call kvWatcher_Next to get the next kvEntry.

Note: The watcher should be destroyed to release memory using kvWatcher_Destroy.

Parameters

new_watcher	the location where to store the pointer to the new kvWatcher object.
kv	the pointer to the kvStore object.
opts	the watcher options, possibly `NULL`.

◆ kvStore_Keys()

NATS_EXTERN natsStatus kvStore_Keys	(	kvKeysList *	list,
		kvStore *	kv,
		kvWatchOptions *	opts )

Returns all keys in the bucket.

Note: Use kvWatchOptions.Timeout to specify how long to wait (in milliseconds) to gather all keys for this bucket. If the deadline is reached, this function will return NATS_TIMEOUT and no keys.

Warning: The user should call kvKeysList_Destroy to release memory allocated for the entries list.

See also: kvWatchOptions_Init; kvKeysList_Destroy

Parameters

list	list the pointer to a kvKeysList that will be initialized and filled with resulting key strings.
kv	the pointer to the kvStore object.
opts	the history options, possibly `NULL`.

◆ kvKeysList_Destroy()

NATS_EXTERN void kvKeysList_Destroy ( kvKeysList * list )

This function iterates through the list of all key strings and free them. It then frees the array that was allocated to hold pointers to those keys.

Note: The kvKeysList object itself is not freed since it is expected that users will pass a pointer to a stack object. Should the user create its own object, it will be the user responsibility to free this object.

Parameters

list	the kvKeysList list of key strings to destroy.

◆ kvStore_History()

NATS_EXTERN natsStatus kvStore_History	(	kvEntryList *	list,
		kvStore *	kv,
		const char *	key,
		kvWatchOptions *	opts )

Returns all historical entries for the key

Use the options to alter the behavior. For instance, if delete markers are not desired, option kvWatchOptions.IgnoreDeletes should be specified.

Note: Use kvWatchOptions.Timeout to specify how long to wait (in milliseconds) to gather all entries for this key. If the deadline is reached, this function will return NATS_TIMEOUT and no entries.

Warning: The user should call kvEntryList_Destroy to release memory allocated for the entries list.

See also: kvWatchOptions_Init; kvEntryList_Destroy

Parameters

list	the pointer to a kvEntryList that will be initialized and filled with resulting entries.
kv	the pointer to the kvStore object.
key	the key for which the history is requested.
opts	the history options, possibly `NULL`.

◆ kvEntryList_Destroy()

NATS_EXTERN void kvEntryList_Destroy ( kvEntryList * list )

This function iterates through the list of all entries and call kvEntry_Destroy. It then frees the array that was allocated to hold pointers to those entries.

Note: The kvEntryList object itself is not freed since it is expected that users will pass a pointer to a stack object. Should the user create its own object, it will be the user responsibility to free this object.

Parameters

list	the kvEntryList list of kvEntry objects to destroy.

◆ kvStore_Bucket()

NATS_EXTERN const char * kvStore_Bucket ( kvStore * kv )

Returns the bucket name of this KeyValue store object, or NULL if kv itself is NULL.

Warning: Do not free the string returned by this function.

Parameters

kv	the pointer to the kvStore object.

◆ kvStore_Status()

NATS_EXTERN natsStatus kvStore_Status	(	kvStatus **	new_status,
		kvStore *	kv )

Returns the status and configuration of a bucket.

Note: The status should be destroyed to release memory using kvStatus_Destroy.

Parameters

new_status	the location where to store the status of this KeyValue store.
kv	the pointer to the kvStore object.

Topics

Functions

Detailed Description

Function Documentation

◆ kvStore_Get()

◆ kvStore_GetRevision()

◆ kvStore_Put()

◆ kvStore_PutString()

◆ kvStore_Create()

◆ kvStore_CreateString()

◆ kvStore_Update()

◆ kvStore_UpdateString()

◆ kvStore_Delete()

◆ kvStore_Purge()

◆ kvWatchOptions_Init()

◆ kvPurgeOptions_Init()

◆ kvStore_PurgeDeletes()

◆ kvStore_Watch()

◆ kvStore_WatchAll()

◆ kvStore_Keys()

◆ kvKeysList_Destroy()

◆ kvStore_History()

◆ kvEntryList_Destroy()

◆ kvStore_Bucket()

◆ kvStore_Status()