NATS C Client with JetStream and Streaming support 3.9.0-beta The nats.io C Client, Supported by Synadia Communications Inc.

Modules | Functions
KeyValue store
Functions

## Modules
| 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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
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. More...
NATS_EXTERN natsStatus | kvStore_Delete (kvStore *kv, const char *key)
| Deletes a key by placing a delete marker and leaving all revisions. More...
NATS_EXTERN natsStatus | kvStore_Purge (kvStore *kv, const char *key, kvPurgeOptions *opts)
| Deletes a key by placing a purge marker and removing all revisions. More...
NATS_EXTERN natsStatus | kvWatchOptions_Init (kvWatchOptions *opts)
| Initializes a KeyValue watcher options structure. More...
NATS_EXTERN natsStatus | kvPurgeOptions_Init (kvPurgeOptions *opts)
| Initializes a KeyValue purge options structure. More...
NATS_EXTERN natsStatus | kvStore_PurgeDeletes (kvStore *kv, kvPurgeOptions *opts)
| Purge and removes delete markers. More...
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. More...
NATS_EXTERN natsStatus | kvStore_WatchMulti (kvWatcher **new_watcher, kvStore *kv, const char **keys, int numKeys, kvWatchOptions *opts)
| Returns a watcher for any updates to keys that match one of the `keys` argument. More...
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. More...
NATS_EXTERN natsStatus | kvStore_Keys (kvKeysList *list, kvStore *kv, kvWatchOptions *opts)
| Returns all keys in the bucket. More...
NATS_EXTERN natsStatus | kvStore_KeysWithFilters (kvKeysList *list, kvStore *kv, const char **filters, int numFilters, kvWatchOptions *opts)
| Returns all keys in the bucket which matches the list of subject like filters. More...
NATS_EXTERN void | kvKeysList_Destroy (kvKeysList *list)
| Destroys this list of KeyValue store key strings. More...
NATS_EXTERN natsStatus | kvStore_History (kvEntryList *list, kvStore *kv, const char *key, kvWatchOptions *opts)
| Returns all historical entries for the key. More...
NATS_EXTERN void | kvEntryList_Destroy (kvEntryList *list)
| Destroys this list of KeyValue store entries. More...
NATS_EXTERN const char * | kvStore_Bucket (kvStore *kv)
| Returns the bucket name of this KeyValue store object. More...
NATS_EXTERN natsStatus | kvStore_Status (kvStatus **new_status, kvStore *kv)
| Returns the status and configuration of a bucket. More...

## 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_WatchMulti()

NATS_EXTERN natsStatus kvStore_WatchMulti | ( | kvWatcher ** | new_watcher,
|  | kvStore * | kv,
|  | const char ** | keys,
|  | int | numKeys,
|  | kvWatchOptions * | opts
| ) |  |

Returns a watcher for any updates to keys that match the one of `keys` argument, which could include wildcards.

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.
  numKeys | the number of keys in the `keys` array.
  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`.

## ◆ kvStore_KeysWithFilters()

NATS_EXTERN natsStatus kvStore_KeysWithFilters | ( | kvKeysList * | list,
|  | kvStore * | kv,
|  | const char ** | filters,
|  | int | numFilters,
|  | kvWatchOptions * | opts
| ) |  |

Get a list of the keys in a bucket filtered by a subject-like string, for instance "key" or "key.foo.*" or "key.>" Any deleted or purged keys will not be returned.

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
  kvStore_WatchMulti

Parameters

  list | the pointer to a kvKeysList that will be initialized and filled with resulting key strings.
  kv | the pointer to the kvStore object.
  filters | the list of subject filters. Cannot be `NULL`.
  numFilters | number of filters. Cannot be 0.
  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.