diff --git a/include/ntcore_c.h b/include/ntcore_c.h index a5354c9dc1..183350fc36 100644 --- a/include/ntcore_c.h +++ b/include/ntcore_c.h @@ -307,12 +307,53 @@ struct NT_Value **NT_UnpackRpcValues(const char *packed, size_t packed_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); + +/** 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); /* @@ -342,12 +383,38 @@ 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 */ @@ -363,71 +430,454 @@ 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); -double *NT_AllocateDoubleArray(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); -int NT_SetEntryBoolean(const char *name, size_t name_len, int v_boolean, - 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);