include/ntcore_c.h

/*----------------------------------------------------------------------------*/
/* Copyright (c) FIRST 2015. All Rights Reserved.                             */
/* Open Source Software - may be modified and shared by FRC teams. The code   */
/* must be accompanied by the FIRST BSD license file in the root directory of */
/* the project.                                                               */
/*----------------------------------------------------------------------------*/

#ifndef NTCORE_C_H_
#define NTCORE_C_H_

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/** Default network tables port number */
#define NT_DEFAULT_PORT 1735

/** NetworkTables data types. */
enum NT_Type {
  NT_UNASSIGNED = 0,
  NT_BOOLEAN = 0x01,
  NT_DOUBLE = 0x02,
  NT_STRING = 0x04,
  NT_RAW = 0x08,
  NT_BOOLEAN_ARRAY = 0x10,
  NT_DOUBLE_ARRAY = 0x20,
  NT_STRING_ARRAY = 0x40,
  NT_RPC = 0x80
};

/** NetworkTables entry flags. */
enum NT_EntryFlags {
  NT_PERSISTENT = 0x01
};

/** NetworkTables logging levels. */
enum NT_LogLevel {
  NT_LOG_CRITICAL = 50,
  NT_LOG_ERROR = 40,
  NT_LOG_WARNING = 30,
  NT_LOG_INFO = 20,
  NT_LOG_DEBUG = 10,
  NT_LOG_DEBUG1 = 9,
  NT_LOG_DEBUG2 = 8,
  NT_LOG_DEBUG3 = 7,
  NT_LOG_DEBUG4 = 6
};

/** NetworkTables notififier kinds. */
enum NT_NotifyKind {
  NT_NOTIFY_NONE = 0,
  NT_NOTIFY_IMMEDIATE = 0x01, /* initial listener addition */
  NT_NOTIFY_LOCAL = 0x02,     /* changed locally */
  NT_NOTIFY_NEW = 0x04,       /* newly created entry */
  NT_NOTIFY_DELETE = 0x08,    /* deleted */
  NT_NOTIFY_UPDATE = 0x10,    /* value changed */
  NT_NOTIFY_FLAGS = 0x20      /* flags changed */
};

/*
 * Structures
 */

/** A NetworkTables string. */
struct NT_String {
  /** String contents (UTF-8).
   * The string is NOT required to be zero-terminated.
   * When returned by the library, this is zero-terminated and allocated with
   * malloc().
   */
  char *str;

  /** Length of the string in bytes.  If the string happens to be zero
   * terminated, this does not include the zero-termination.
   */
  size_t len;
};

/** NetworkTables Entry Value.  Note this is a typed union. */
struct NT_Value {
  enum NT_Type type;
  unsigned long long last_change;
  union {
    int v_boolean;
    double v_double;
    struct NT_String v_string;
    struct NT_String v_raw;
    struct {
      int *arr;
      size_t size;
    } arr_boolean;
    struct {
      double *arr;
      size_t size;
    } arr_double;
    struct {
      struct NT_String *arr;
      size_t size;
    } arr_string;
  } data;
};

/** NetworkTables Entry Information */
struct NT_EntryInfo {
  /** Entry name */
  struct NT_String name;

  /** Entry type */
  enum NT_Type type;

  /** Entry flags */
  unsigned int flags;

  /** Timestamp of last change to entry (type or value). */
  unsigned long long last_change;
};

/** NetworkTables Connection Information */
struct NT_ConnectionInfo {
  struct NT_String remote_id;
  char *remote_name;
  unsigned int remote_port;
  unsigned long long last_update;
  unsigned int protocol_version;
};

/** NetworkTables RPC Parameter Definition */
struct NT_RpcParamDef {
  struct NT_String name;
  struct NT_Value def_value;
};

/** NetworkTables RPC Result Definition */
struct NT_RpcResultDef {
  struct NT_String name;
  enum NT_Type type;
};

/** NetworkTables RPC Definition */
struct NT_RpcDefinition {
  unsigned int version;
  struct NT_String name;
  size_t num_params;
  NT_RpcParamDef *params;
  size_t num_results;
  NT_RpcResultDef *results;
};

/** NetworkTables RPC Call Data */
struct NT_RpcCallInfo {
  unsigned int rpc_id;
  unsigned int call_uid;
  struct NT_String name;
  struct NT_String params;
};

/*
 * Table Functions
 */

/** Get Entry Value.
 * Returns copy of current entry value.
 * Note that one of the type options is "unassigned".
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 * @param value     storage for returned entry value
 *
 * It is the caller's responsibility to free value once it's no longer
 * needed (the utility function NT_DisposeValue() is useful for this
 * purpose).
 */
void NT_GetEntryValue(const char *name, size_t name_len,
                      struct NT_Value *value);

/** Set Entry Value.
 * Sets new entry value.  If type of new value differs from the type of the
 * currently stored entry, returns error and does not update value.
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 * @param value     new entry value
 * @return 0 on error (type mismatch), 1 on success
 */
int NT_SetEntryValue(const char *name, size_t name_len,
                     const struct NT_Value *value);

/** Set Entry Type and Value.
 * Sets new entry value.  If type of new value differs from the type of the
 * currently stored entry, the currently stored entry type is overridden
 * (generally this will generate an Entry Assignment message).
 *
 * This is NOT the preferred method to update a value; generally
 * NT_SetEntryValue() should be used instead, with appropriate error handling.
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 * @param value     new entry value
 */
void NT_SetEntryTypeValue(const char *name, size_t name_len,
                          const struct NT_Value *value);

/** Set Entry Flags.
 */
void NT_SetEntryFlags(const char *name, size_t name_len, unsigned int flags);

/** Get Entry Flags.
 */
unsigned int NT_GetEntryFlags(const char *name, size_t name_len);

/** Delete Entry.
 * Deletes an entry.  This is a new feature in version 3.0 of the protocol,
 * so this may not have an effect if any other node in the network is not
 * version 3.0 or newer.
 *
 * Note: NT_GetConnections() can be used to determine the protocol version
 * of direct remote connection(s), but this is not sufficient to determine
 * if all nodes in the network are version 3.0 or newer.
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 */
void NT_DeleteEntry(const char *name, size_t name_len);

/** Delete All Entries.
 * Deletes ALL table entries.  This is a new feature in version 3.0 of the
 * so this may not have an effect if any other node in the network is not
 * version 3.0 or newer.
 *
 * Note: NT_GetConnections() can be used to determine the protocol version
 * of direct remote connection(s), but this is not sufficient to determine
 * if all nodes in the network are version 3.0 or newer.
 */
void NT_DeleteAllEntries(void);

/** Get Entry Information.
 * Returns an array of entry information (name, entry type,
 * and timestamp of last change to type/value).  The results are optionally
 * filtered by string prefix and entry type to only return a subset of all
 * entries.
 *
 * @param prefix        entry name required prefix; only entries whose name
 *                      starts with this string are returned
 * @param prefix_len    length of prefix in bytes
 * @param types         bitmask of NT_Type values; 0 is treated specially
 *                      as a "don't care"
 * @param count         output parameter; set to length of returned array
 * @return Array of entry information.
 */
struct NT_EntryInfo *NT_GetEntryInfo(const char *prefix, size_t prefix_len,
                                     unsigned int types, size_t *count);

/** Flush Entries.
 * Forces an immediate flush of all local entry changes to network.
 * Normally this is done on a regularly scheduled interval (see
 * NT_SetUpdateRate()).
 *
 * Note: flushes are rate limited to avoid excessive network traffic.  If
 * the time between calls is too short, the flush will occur after the minimum
 * time elapses (rather than immediately).
 */
void NT_Flush(void);

/*
 * Callback Creation Functions
 */

void NT_SetListenerOnStart(void (*on_start)(void *data), void *data);
void NT_SetListenerOnExit(void (*on_exit)(void *data), void *data);

typedef void (*NT_EntryListenerCallback)(
    unsigned int uid, void *data, const char *name, size_t name_len,
    const struct NT_Value *value, unsigned int flags);

typedef void (*NT_ConnectionListenerCallback)(
    unsigned int uid, void *data, int connected,
    const struct NT_ConnectionInfo *conn);

unsigned int NT_AddEntryListener(const char *prefix, size_t prefix_len,
                                 void *data, NT_EntryListenerCallback callback,
                                 unsigned int flags);
void NT_RemoveEntryListener(unsigned int entry_listener_uid);
unsigned int NT_AddConnectionListener(void *data,
                                      NT_ConnectionListenerCallback callback,
                                      int immediate_notify);
void NT_RemoveConnectionListener(unsigned int conn_listener_uid);

int NT_NotifierDestroyed();

/*
 * Remote Procedure Call Functions
 */

typedef char *(*NT_RpcCallback)(void *data, const char *name, size_t name_len,
                                const char *params, size_t params_len,
                                size_t *results_len);

void NT_CreateRpc(const char *name, size_t name_len, const char *def,
                  size_t def_len, void *data, NT_RpcCallback callback);
void NT_CreatePolledRpc(const char *name, size_t name_len, const char *def,
                        size_t def_len);

int NT_PollRpc(int blocking, struct NT_RpcCallInfo* call_info);
void NT_PostRpcResponse(unsigned int rpc_id, unsigned int call_uid,
                        const char *result, size_t result_len);

unsigned int NT_CallRpc(const char *name, size_t name_len, const char *params,
                        size_t params_len);
char *NT_GetRpcResult(int blocking, unsigned int call_uid, size_t *result_len);

char *NT_PackRpcDefinition(const struct NT_RpcDefinition *def,
                           size_t *packed_len);
int NT_UnpackRpcDefinition(const char *packed, size_t packed_len,
                           struct NT_RpcDefinition *def);
char *NT_PackRpcValues(const struct NT_Value **values, size_t values_len,
                       size_t *packed_len);
struct NT_Value **NT_UnpackRpcValues(const char *packed, size_t packed_len,
                                     const NT_Type *types, size_t types_len);

/*
 * Client/Server Functions
 */
void NT_SetNetworkIdentity(const char *name, size_t name_len);

/** Start Server
* Starts a server using the specified filename, listening address, and port.
*
* @param persist_filename  the name of the persist file to use (UTF-8 string, null terminated)
* @param listen_address    the address to listen on, or null to listen on any address. (UTF-8 string, null terminated)
* @param port              port to communicate over.
*/
void NT_StartServer(const char *persist_filename, const char *listen_address,
                    unsigned int port);

/** Stop Server
 * Stops the server if it is running.
*/
void NT_StopServer(void);

/** Starts Client
 * Starts a client using the specified server and port
 *
 * @param server_name server name (UTF-8 string, null terminated)
 * @param port        port to communicate over
 *
*/
void NT_StartClient(const char *server_name, unsigned int port);

/** Stop Client
 * Stops the client if it is running.
*/
void NT_StopClient(void);

/** Stop Rpc Server
 * Stops the Rpc server if it is running.
*/
void NT_StopRpcServer(void);

/** Stop Notifier
 * Stops the Notifier (Entry and Connection Listener) thread if it is running.
*/
void NT_StopNotifier(void);

/** Set Update Rate
 * Sets the update rate of the table
 *
 * @param interval  the interval to update the table at (in seconds)
 *
*/
void NT_SetUpdateRate(double interval);

/** Get Connections
 * Gets an array of all the connections in the table.
 *
 * @param count returns the number of elements in the array
 * @return      an array containing all the connections.
 *
 * It is the caller's responsibility to free the array. The
 * NT_DisposeConnectionInfoArray function is useful for this purpose.
*/
struct NT_ConnectionInfo *NT_GetConnections(size_t *count);

/*
 * Persistent Functions
 */
/* return error string, or NULL if successful */
const char *NT_SavePersistent(const char *filename);
const char *NT_LoadPersistent(const char *filename,
                              void (*warn)(size_t line, const char *msg));

/*
 * Utility Functions
 */

/* frees value memory */
void NT_DisposeValue(struct NT_Value *value);

/* sets type to unassigned and clears rest of struct */
void NT_InitValue(struct NT_Value *value);

/* frees string memory */
void NT_DisposeString(struct NT_String *str);

/* sets length to zero and pointer to null */
void NT_InitString(struct NT_String *str);

/* Gets the type for the specified key, or unassigned if non existent. */
enum NT_Type NT_GetType(const char *name, size_t name_len);

/** Dispose Connection Info Array
 * Disposes a connection info array
 *
 * @param arr   pointer to the array to dispose
 * @param count number of elements in the array
 *
*/
void NT_DisposeConnectionInfoArray(struct NT_ConnectionInfo *arr, size_t count);

/** Dispose Entry Info Array
 * Disposes an entry info array
 *
 * @param arr   pointer to the array to dispose
 * @param count number of elements in the array
 *
*/
void NT_DisposeEntryInfoArray(struct NT_EntryInfo *arr, size_t count);

/** Dispose Rpc Definition
 * Disposes a Rpc Definition structure
 *
 * @param def  pointer to the struct to dispose
 *
*/
void NT_DisposeRpcDefinition(struct NT_RpcDefinition *def);

/** Dispose Rpc Call Info
 * Disposes a Rpc Call Info structure
 *
 * @param def  pointer to the struct to dispose
 *
*/
void NT_DisposeRpcCallInfo(struct NT_RpcCallInfo *call_info);

/* timestamp */
unsigned long long NT_Now(void);

/* logging */
typedef void (*NT_LogFunc)(unsigned int level, const char *file,
                           unsigned int line, const char *msg);
void NT_SetLogger(NT_LogFunc func, unsigned int min_level);

/*
Interop Utility Functions
*/

/* Memory Allocators */

/** Allocate Character Array
 * Allocates an array of chars.
 * Note that the size is the number of elements, and not the
 * specific number of bytes to allocate. That is calculated internally.
 *
 * @param size  the number of elements the array will contain
 * @return      the allocated char array
 *
 * After use, the array should be freed using the NT_FreeCharArray()
 * function.
*/
char *NT_AllocateCharArray(size_t size);

/** Allocate Boolean Array
 * Allocates an array of booleans.
 * Note that the size is the number of elements, and not the
 * specific number of bytes to allocate. That is calculated internally.
 *
 * @param size  the number of elements the array will contain
 * @return      the allocated boolean array
 *
 * After use, the array should be freed using the NT_FreeBooleanArray()
 * function.
*/
int *NT_AllocateBooleanArray(size_t size);

/** Allocate Double Array
 * Allocates an array of doubles.
 * Note that the size is the number of elements, and not the
 * specific number of bytes to allocate. That is calculated internally.
 *
 * @param size  the number of elements the array will contain
 * @return      the allocated double array
 *
 * After use, the array should be freed using the NT_FreeDoubleArray()
 * function.
*/
double *NT_AllocateDoubleArray(size_t size);

/** Allocate NT_String Array
 * Allocates an array of NT_Strings.
 * Note that the size is the number of elements, and not the
 * specific number of bytes to allocate. That is calculated internally.
 *
 * @param size  the number of elements the array will contain
 * @return      the allocated NT_String array
 *
 * After use, the array should be freed using the NT_FreeStringArray()
 * function.
*/
struct NT_String *NT_AllocateStringArray(size_t size);

/** Free Char Array
 * Frees an array of chars.
 *
 * @param v_boolean  pointer to the char array to free
*/
void NT_FreeCharArray(char *v_char);

/** Free Double Array
 * Frees an array of doubles.
 *
 * @param v_boolean  pointer to the double array to free
*/
void NT_FreeDoubleArray(double *v_double);

/** Free Boolean Array
 * Frees an array of booleans.
 *
 * @param v_boolean  pointer to the boolean array to free
*/
void NT_FreeBooleanArray(int *v_boolean);

/** Free String Array
 * Frees an array of NT_Strings.
 *
 * @param v_string  pointer to the string array to free
 * @param arr_size  size of the string array to free
 *
 * Note that the individual NT_Strings in the array should NOT be
 * freed before calling this. This function will free all the strings
 * individually.
*/
void NT_FreeStringArray(struct NT_String *v_string, size_t arr_size);

/** Get Value Type
 * Returns the type of an NT_Value struct.
 * Note that one of the type options is "unassigned".
 *
 * @param value  The NT_Value struct to get the type from.
 * @return       The type of the value, or unassigned if null.
 *
*/
enum NT_Type NT_GetValueType(const struct NT_Value *value);

/** Get Value Boolean
 * Returns the boolean from the NT_Value.
 * If the NT_Value is null, or is assigned to a
 * different type, returns 0.
 *
 * @param value       NT_Value struct to get the boolean from
 * @param last_change returns time in ms since the last change in the value
 * @param v_boolean   returns the boolean assigned to the name
 * @return            1 if successful, or 0 if value is null or not a boolean
 *
*/
int NT_GetValueBoolean(const struct NT_Value *value,
                       unsigned long long *last_change, int *v_boolean);

/** Get Value Double
 * Returns the double from the NT_Value.
 * If the NT_Value is null, or is assigned to a
 * different type, returns 0.
 *
 * @param value       NT_Value struct to get the double from
 * @param last_change returns time in ms since the last change in the value
 * @param v_double    returns the boolean assigned to the name
 * @return            1 if successful, or 0 if value is null or not a double
 *
*/
int NT_GetValueDouble(const struct NT_Value *value,
                      unsigned long long *last_change, double *v_double);

/** Get Value String
 * Returns a copy of the string from the NT_Value.
 * If the NT_Value is null, or is assigned to a
 * different type, returns 0.
 *
 * @param value       NT_Value struct to get the string from
 * @param last_change returns time in ms since the last change in the value
 * @param str_len     returns the length of the string
 * @return            pointer to the string (UTF-8), or null if error
 *
 * It is the caller's responsibility to free the string once its no longer
 * needed. The NT_FreeCharArray() function is useful for this purpose. The returned
 * string is a copy of the string in the value, and must be freed seperately.
 *
*/
char *NT_GetValueString(const struct NT_Value *value,
                        unsigned long long *last_change, size_t *str_len);

/** Get Value Raw
 * Returns a copy of the raw value from the NT_Value.
 * If the NT_Value is null, or is assigned to a
 * different type, returns null.
 *
 * @param value       NT_Value struct to get the string from
 * @param last_change returns time in ms since the last change in the value
 * @param raw_len     returns the length of the string
 * @return            pointer to the raw value (UTF-8), or null if error
 *
 * It is the caller's responsibility to free the raw value once its no longer
 * needed. The NT_FreeCharArray() function is useful for this purpose. The returned
 * string is a copy of the string in the value, and must be freed seperately.
 *
*/
char *NT_GetValueRaw(const struct NT_Value *value,
                     unsigned long long *last_change, size_t *raw_len);

/** Get Value Boolean Array
 * Returns a copy of the boolean array from the NT_Value.
 * If the NT_Value is null, or is assigned to a
 * different type, returns null.
 *
 * @param value       NT_Value struct to get the boolean array from
 * @param last_change returns time in ms since the last change in the value
 * @param arr_size    returns the number of elements in the array
 * @return            pointer to the boolean array, or null if error
 *
 * It is the caller's responsibility to free the array once its no longer
 * needed. The NT_FreeBooleanArray() function is useful for this purpose.
 * The returned array is a copy of the array in the value, and must be
 * freed seperately.
 *
*/
int *NT_GetValueBooleanArray(const struct NT_Value *value,
                             unsigned long long *last_change, size_t *arr_size);

/** Get Value Double Array
 * Returns a copy of the double array from the NT_Value.
 * If the NT_Value is null, or is assigned to a
 * different type, returns null.
 *
 * @param value       NT_Value struct to get the double array from
 * @param last_change returns time in ms since the last change in the value
 * @param arr_size    returns the number of elements in the array
 * @return            pointer to the double array, or null if error
 *
 * It is the caller's responsibility to free the array once its no longer
 * needed. The NT_FreeDoubleArray() function is useful for this purpose.
 * The returned array is a copy of the array in the value, and must be
 * freed seperately.
 *
*/
double *NT_GetValueDoubleArray(const struct NT_Value *value,
                               unsigned long long *last_change,
                               size_t *arr_size);

/** Get Value String Array
 * Returns a copy of the NT_String array from the NT_Value.
 * If the NT_Value is null, or is assigned to a
 * different type, returns null.
 *
 * @param value       NT_Value struct to get the NT_String array from
 * @param last_change returns time in ms since the last change in the value
 * @param arr_size    returns the number of elements in the array
 * @return            pointer to the NT_String array, or null if error
 *
 * It is the caller's responsibility to free the array once its no longer
 * needed. The NT_FreeStringArray() function is useful for this purpose.
 * The returned array is a copy of the array in the value, and must be
 * freed seperately. Note that the individual NT_Strings should not be freed, 
 * but the entire array should be freed at once. The NT_FreeStringArray() function 
 * will free all the NT_Strings.
 *
*/
NT_String *NT_GetValueStringArray(const struct NT_Value *value,
                                  unsigned long long *last_change,
                                  size_t *arr_size);

/** Get Entry Boolean
 * Returns the boolean currently assigned to the entry name.
 * If the entry name is not currently assigned, or is assigned to a
 * different type, returns 0.
 *
 * @param name        entry name (UTF-8 string)
 * @param name_len    length of name in bytes
 * @param last_change returns time in ms since the last change in the value
 * @param v_boolean   returns the boolean assigned to the name
 * @return            1 if successful, or 0 if value is unassigned or not a boolean
 *
*/
int NT_GetEntryBoolean(const char *name, size_t name_len,
                       unsigned long long *last_change, int *v_boolean);

/** Get Entry Double
 * Returns the double currently assigned to the entry name.
 * If the entry name is not currently assigned, or is assigned to a
 * different type, returns 0.
 *
 * @param name        entry name (UTF-8 string)
 * @param name_len    length of name in bytes
 * @param last_change returns time in ms since the last change in the value
 * @param v_double    returns the double assigned to the name
 * @return            1 if successful, or 0 if value is unassigned or not a double
 *
*/
int NT_GetEntryDouble(const char *name, size_t name_len,
                      unsigned long long *last_change, double *v_double);

/** Get Entry String
 * Returns a copy of the string assigned to the entry name.
 * If the entry name is not currently assigned, or is assigned to a
 * different type, returns null.
 *
 * @param name        entry name (UTF-8 string)
 * @param name_len    length of name in bytes
 * @param last_change returns time in ms since the last change in the value
 * @param str_len     returns the length of the string
 * @return            pointer to the string (UTF-8), or null if error
 *
 * It is the caller's responsibility to free the string once its no longer
 * needed. The NT_FreeCharArray() function is useful for this purpose.
 *
*/
char *NT_GetEntryString(const char *name, size_t name_len,
                        unsigned long long *last_change, size_t *str_len);

/** Get Entry Raw
 * Returns a copy of the raw value assigned to the entry name.
 * If the entry name is not currently assigned, or is assigned to a
 * different type, returns null.
 *
 * @param name        entry name (UTF-8 string)
 * @param name_len    length of name in bytes
 * @param last_change returns time in ms since the last change in the value
 * @param raw_len     returns the length of the string
 * @return            pointer to the raw value (UTF-8), or null if error
 *
 * It is the caller's responsibility to free the raw value once its no longer
 * needed. The NT_FreeCharArray() function is useful for this purpose.
 *
*/
char *NT_GetEntryRaw(const char *name, size_t name_len,
                     unsigned long long *last_change, size_t *raw_len);

/** Get Entry Boolean Array
 * Returns a copy of the boolean array assigned to the entry name.
 * If the entry name is not currently assigned, or is assigned to a
 * different type, returns null.
 *
 * @param name        entry name (UTF-8 string)
 * @param name_len    length of name in bytes
 * @param last_change returns time in ms since the last change in the value
 * @param arr_size    returns the number of elements in the array
 * @return            pointer to the boolean array, or null if error
 *
 * It is the caller's responsibility to free the array once its no longer
 * needed. The NT_FreeBooleanArray() function is useful for this purpose.
 *
*/
int *NT_GetEntryBooleanArray(const char *name, size_t name_len,
                             unsigned long long *last_change, size_t *arr_size);

/** Get Entry Double Array
 * Returns a copy of the double array assigned to the entry name.
 * If the entry name is not currently assigned, or is assigned to a
 * different type, returns null.
 *
 * @param name        entry name (UTF-8 string)
 * @param name_len    length of name in bytes
 * @param last_change returns time in ms since the last change in the value
 * @param arr_size    returns the number of elements in the array
 * @return            pointer to the double array, or null if error
 *
 * It is the caller's responsibility to free the array once its no longer
 * needed. The NT_FreeDoubleArray() function is useful for this purpose.
 *
*/
double *NT_GetEntryDoubleArray(const char *name, size_t name_len,
                               unsigned long long *last_change,
                               size_t *arr_size);

/** Get Entry String Array
 * Returns a copy of the NT_String array assigned to the entry name. 
 * If the entry name is not currently assigned, or is assigned to a 
 * different type, returns null.
 *
 * @param name        entry name (UTF-8 string)
 * @param name_len    length of name in bytes
 * @param last_change returns time in ms since the last change in the value
 * @param arr_size    returns the number of elements in the array
 * @return            pointer to the NT_String array, or null if error
 *
 * It is the caller's responsibility to free the array once its no longer
 * needed. The NT_FreeStringArray() function is useful for this purpose. Note
 * that the individual NT_Strings should not be freed, but the entire array
 * should be freed at once. The NT_FreeStringArray() function will free all the
 * NT_Strings.
 *
*/
NT_String *NT_GetEntryStringArray(const char *name, size_t name_len,
                                  unsigned long long *last_change,
                                  size_t *arr_size);

/* Entry Value Setters */

/** Set Entry Boolean
 * Sets an entry boolean. If the entry name is not currently assigned to a boolean,
 * returns error unless the force parameter is set.
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 * @param v_boolean boolean value to set
 * @param force     1 to force the entry to get overwritten, otherwise 0
 * @return          0 on error (type mismatch), 1 on success
 *
*/
int NT_SetEntryBoolean(const char *name, size_t name_len, int v_boolean,
  int force);

/** Set Entry Double
 * Sets an entry double. If the entry name is not currently assigned to a double,
 * returns error unless the force parameter is set.
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 * @param v_double  double value to set
 * @param force     1 to force the entry to get overwritten, otherwise 0
 * @return          0 on error (type mismatch), 1 on success
 *
*/
int NT_SetEntryDouble(const char *name, size_t name_len, double v_double,
                      int force);

/** Set Entry String
 * Sets an entry string. If the entry name is not currently assigned to a string,
 * returns error unless the force parameter is set.
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 * @param str       string to set (UTF-8 string)
 * @param str_len   length of string to write in bytes
 * @param force     1 to force the entry to get overwritten, otherwise 0
 * @return          0 on error (type mismatch), 1 on success
 *
*/
int NT_SetEntryString(const char *name, size_t name_len, const char *str,
                      size_t str_len, int force);

/** Set Entry Raw
 * Sets the raw value of an entry. If the entry name is not currently assigned
 * to a raw value, returns error unless the force parameter is set.
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 * @param raw       raw string to set (UTF-8 string)
 * @param raw_len   length of raw string to write in bytes
 * @param force     1 to force the entry to get overwritten, otherwise 0
 * @return          0 on error (type mismatch), 1 on success
 *
*/
int NT_SetEntryRaw(const char *name, size_t name_len, const char *raw,
                   size_t raw_len, int force);

/** Set Entry Boolean Array
 * Sets an entry boolean array. If the entry name is not currently assigned to a boolean
 * array, returns error unless the force parameter is set.
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 * @param arr       boolean array to write
 * @param size      number of elements in the array
 * @param force     1 to force the entry to get overwritten, otherwise 0
 * @return          0 on error (type mismatch), 1 on success
 *
*/
int NT_SetEntryBooleanArray(const char *name, size_t name_len, const int *arr,
                            size_t size, int force);

/** Set Entry Double Array
 * Sets an entry double array. If the entry name is not currently assigned to a double
 * array, returns error unless the force parameter is set.
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 * @param arr       double array to write
 * @param size      number of elements in the array
 * @param force     1 to force the entry to get overwritten, otherwise 0
 * @return          0 on error (type mismatch), 1 on success
 *
*/
int NT_SetEntryDoubleArray(const char *name, size_t name_len, const double *arr,
                           size_t size, int force);

/** Set Entry String Array
 * Sets an entry string array. If the entry name is not currently assigned to a string
 * array, returns error unless the force parameter is set.
 *
 * @param name      entry name (UTF-8 string)
 * @param name_len  length of name in bytes
 * @param arr       NT_String array to write
 * @param size      number of elements in the array
 * @param force     1 to force the entry to get overwritten, otherwise 0
 * @return          0 on error (type mismatch), 1 on success
 *
 */
int NT_SetEntryStringArray(const char *name, size_t name_len,
                           const struct NT_String *arr, size_t size, int force);

#ifdef __cplusplus
}
#endif

#endif /* NTCORE_C_H_ */