Open Ethernet Networking (OpEN) API Guide and Reference Manual  3.6.0.3
openapi_syncdb.h
Go to the documentation of this file.
1 
9 /*********************************************************************
10 *
11 * Copyright 2016-2017 Broadcom.
12 *
13 * Licensed under the Apache License, Version 2.0 (the "License");
14 * you may not use this file except in compliance with the License.
15 * You may obtain a copy of the License at
16 *
17 * http://www.apache.org/licenses/LICENSE-2.0
18 *
19 * Unless required by applicable law or agreed to in writing, software
20 * distributed under the License is distributed on an "AS IS" BASIS,
21 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22 * See the License for the specific language governing permissions and
23 * limitations under the License.
24 *
25 **********************************************************************
26 *
27 * @filename syncdb_api.h
28 *
29 * @purpose API for the Synchronization Database
30 *
31 * @component
32 *
33 * @note
34 *
35 * @create 7/5/2012
36 *
37 * @end
38 *
39 **********************************************************************/
40 #ifndef SYNCDB_API_H_INCLUDED
41 #define SYNCDB_API_H_INCLUDED
42 
43 #include <pthread.h>
44 
49 #define SYNCDB_AGENT_MAX_MSG_SIZE 8000
50 
55 #define SYNCDB_TABLE_NAME_SIZE 32
56 
60 #define SYNCDB_MAX_STR_LEN 256
61 
65 #define SYNCDB_RECORD_MAX_SIZE (1024*64)
66 
67 /* Supported Data Table Types.
68 */
69 #define SYNCDB_TABLE_TYPE_RECORD 0
70 #define SYNCDB_TABLE_TYPE_STORABLE_RECORD 1
71 #define SYNCDB_TABLE_TYPE_AVL_TREE 2
72 #define SYNCDB_TABLE_TYPE_QUEUE 3
73 
74 /* Return Codes from the syncdb API functions.
75 */
76 #define SYNCDB_OK (0)
77 #define SYNCDB_ERROR (-1)
78 #define SYNCDB_MAX_CLIENTS (-2)
79 #define SYNCDB_DUPNAME (-3)
80 #define SYNCDB_NO_TABLE (-4)
81 #define SYNCDB_FULL (-5)
82 #define SYNCDB_SIZE (-6)
83 #define SYNCDB_NOT_FOUND (-7)
84 #define SYNCDB_SCHEMA_ERROR (-8)
85 #define SYNCDB_ENTRY_EXISTS (-9)
87 /* Data Table Status.
88 ** The status is a bit mask returned by the syncdbTableStatusGet() function.
89 ** The status is maintained per client.
90 */
91 
95 #define SYNCDB_TABLE_STAT_EXISTS (1 << 0)
96 
104 #define SYNCDB_TABLE_STAT_CHANGED (1 << 1)
105 
115 #define SYNCDB_TABLE_STAT_AVL_TREE_PURGED (1 << 2)
116 
125 #define SYNCDB_TABLE_STAT_NEW_TABLE (1 << 3)
126 
127 /******** Data Table Creation Flags
128 ** The flags specified on the table create call.
129 ** The flags is a bit mask returned by the syncdbTableStatusGet() function.
130 ********/
136 #define SYNCDB_TABLE_FLAG_STORABLE (1 << 0)
137 
142 #define SYNCDB_TABLE_FLAG_NVRAM (1 << 1)
143 
148 #define SYNCDB_TABLE_FLAG_FILE_LOAD (1 << 2)
149 
150 
155 #define SYNCDB_TABLE_FLAG_EXISTS (1 << 3)
156 
162 #define SYNCDB_TABLE_FLAG_NSF (1 << 4)
163 
165 typedef struct
166 {
169  int client_id;
170  pthread_mutex_t client_lock;
172 
175 typedef struct
176 {
177  char table_name [SYNCDB_TABLE_NAME_SIZE];
182  unsigned int table_version;
183 
186  unsigned int table_flags;
187 
190  unsigned int table_status;
191 
196 
201 
207 
210 typedef struct
211 {
212  int client_id;
213  char client_description [SYNCDB_MAX_STR_LEN];
219 
220 /********************************
221 ** Storable Record Schema
222 ********************************/
223 
224 /* The AVL trees and records can be stored in a file system using JSON notation.
225 ** In order to store information in the file system the table creator must tell syncdb how
226 ** the data is formatted. Also to facilitate data format changes the table creator must
227 ** tell syncdb the default values of fields that are not present in the file.
228 */
229 
235 #define SYNCDB_JSON_MAX_SCHEMA_SIZE (SYNCDB_RECORD_MAX_SIZE)
236 
260 typedef enum
261 {
262  SYNCDB_JSON_NUMBER = 1,
263  SYNCDB_JSON_STRING = 2,
264  SYNCDB_JSON_ARRAY = 3
266 
269 typedef struct syncdbJsonNode_s
270 {
271  syncdbJsonDataType_e data_type;
272 
280  char *data_name;
281 
287  unsigned int data_offset;
288 
291  unsigned int data_size;
292 
293  union {
294  unsigned long long default_number;
296  } val;
297 
299 
302 typedef enum
303 {
317 
318 /********************************
319 ** syncdb API Functions
320 *********************************/
321 
322 /*****************************************************************/
351 int syncdbUtilSchemaCreate (syncdbJsonNode_t *element_node,
352  unsigned int node_schema_size,
353  char *schema_buf,
354  unsigned int buf_size,
355  unsigned int *schema_size,
356  unsigned int data_element_size,
357  syncdbSchemaError_e *schema_error
358  );
359 
360 /*****************************************************************/
407 int syncdbClientRegister (char *client_name,
408  syncdbClientHandle_t *client_id);
409 
410 /*****************************************************************/
426 
427 /*****************************************************************/
444  syncdbClientStatus_t *client_status);
445 
446 /*****************************************************************/
468 int syncdbTableStore (syncdbClientHandle_t *client_id,
469  char *table_name,
470  unsigned int nvram);
471 
472 /*****************************************************************/
506  int timeout_secs);
507 
508 /*****************************************************************/
537  char *table_name);
538 
539 /*****************************************************************/
564  int num_tables,
565  syncdbDataTableStatus_t *table_list);
566 
567 /*****************************************************************/
604  char *table_name,
605  unsigned int table_version,
606  unsigned int max_elements,
607  unsigned int max_live_elements,
608  unsigned int node_size,
609  unsigned int key_size,
610  unsigned int flags,
611  char * schema,
612  unsigned int schema_size);
613 
614 /*****************************************************************/
643  char *table_name,
644  unsigned int table_version,
645  unsigned int node_size,
646  unsigned int flags,
647  char * schema,
648  unsigned int schema_size);
649 
650 /*****************************************************************/
665  char *table_name);
666 
667 /*****************************************************************/
702 int syncdbInsert (syncdbClientHandle_t *client_id,
703  char *table_name,
704  void *element,
705  unsigned int size);
706 
707 /*****************************************************************/
733 int syncdbDelete (syncdbClientHandle_t *client_id,
734  char *table_name,
735  void *element,
736  unsigned int size);
737 
738 /*****************************************************************/
766 int syncdbSet (syncdbClientHandle_t *client_id,
767  char *table_name,
768  void *element,
769  unsigned int size);
770 
771 /*****************************************************************/
813 int syncdbFieldSet (syncdbClientHandle_t *client_id,
814  char *table_name,
815  void *element,
816  unsigned int size,
817  unsigned int field_offset,
818  unsigned int field_size);
819 
820 /*****************************************************************/
854 int syncdbGet (syncdbClientHandle_t *client_id,
855  char *table_name,
856  void *element,
857  unsigned int size,
858  int *delete_pending);
859 
860 /*****************************************************************/
910 int syncdbFieldGet (syncdbClientHandle_t *client_id,
911  char *table_name,
912  void *element,
913  unsigned int size,
914  unsigned int field_offset,
915  unsigned int field_size,
916  int flags_unchanged,
917  int *delete_pending);
918 
919 /*****************************************************************/
952 int syncdbGetNext (syncdbClientHandle_t *client_id,
953  char *table_name,
954  void *element,
955  unsigned int size,
956  int *delete_pending);
957 
958 /*****************************************************************/
994  char *table_name,
995  void *element,
996  unsigned int size,
997  int *delete_pending);
998 
999 /*****************************************************************/
1014 int syncdbNsfModeSet (syncdbClientHandle_t *client_id,
1015  unsigned int sync_mode,
1016  unsigned int max_msg_size);
1017 
1018 #endif /* SYNCDB_API_H_INCLUDED */
1019 
int num_non_deleted_elements
Number of records that are not in delete-pending state.
Client Table Status.
int client_id
Unique Syncdb client identifier.
int table_type
If the table exists then this specifies the table type.
Integer size is not 1, 2, 4, or 8.
Data element has 8 or more bytes beyond last schema node.
int num_elements
Number of records in the table.
int syncdbTableDelete(syncdbClientHandle_t *client_id, char *table_name)
Delete specified table or all tables.
int syncdbAvlTableCreate(syncdbClientHandle_t *client_id, char *table_name, unsigned int table_version, unsigned int max_elements, unsigned int max_live_elements, unsigned int node_size, unsigned int key_size, unsigned int flags, char *schema, unsigned int schema_size)
Create AVL Table.
int syncdbUtilSchemaCreate(syncdbJsonNode_t *element_node, unsigned int node_schema_size, char *schema_buf, unsigned int buf_size, unsigned int *schema_size, unsigned int data_element_size, syncdbSchemaError_e *schema_error)
Generate a storable record schema.
int cmd_socket
Socket for sending commands to Syncdb process.
int client_id
syncdb client ID of the client for which to retrieve the status
The element has the same name as another element in the schema.
int syncdbTableStore(syncdbClientHandle_t *client_id, char *table_name, unsigned int nvram)
Store specified table or all tables into the file system.
int syncdbInsert(syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size)
Insert a new entry into the AVL table.
Default value for an integer does not fit into size.
int syncdbClientStatusGet(syncdbClientHandle_t *client_id, syncdbClientStatus_t *client_status)
Get client information for the specified client ID.
struct syncdbJsonNode_s syncdbJsonNode_t
The JSON node definition.
int syncdbGet(syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size, int *delete_pending)
Get an entry from the table.
int syncdbGetNextChanged(syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size, int *delete_pending)
Get the Next Changed entry from the table.
unsigned int data_size
The size of this data element in bytes.
#define SYNCDB_MAX_STR_LEN
Maximum length for string fields used by syncdb.
syncdbSchemaError_e
The following errors may be reported during schema validation.
int syncdbClientRegister(char *client_name, syncdbClientHandle_t *client_id)
Register a new client with the syncdb.
int syncdbFieldGet(syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size, unsigned int field_offset, unsigned int field_size, int flags_unchanged, int *delete_pending)
Get the specified field in an entry from the table.
#define SYNCDB_TABLE_NAME_SIZE
Maximum size of the text string that uniquely identifies a database table.
int syncdbNsfModeSet(syncdbClientHandle_t *client_id, unsigned int sync_mode, unsigned int max_msg_size)
Tell SyncDB that it should start or stop data sync with the backup manager.
unsigned int table_version
The version of the table.
unsigned int data_offset
Offset of this element from the beginning of the data buffer.
Data type is not Number, String or Array.
int syncdbFieldSet(syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size, unsigned int field_offset, unsigned int field_size)
Set the specified field in an entry in the table.
int num_table_purges
Number of AVL tree purge events sent to the client.
int notify_socket
Socket for waiting on events from Syncdb process.
unsigned long long default_number
Default value for SYNCDB_JSON_NUMBER object.
The JSON node definition.
char * data_name
The unique identifier for this variable.
int num_commands
Total number of commands issued by this client.
Schema nodes overlap each other.
int syncdbGetNext(syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size, int *delete_pending)
Get the Next entry from the table.
No node with offset set to 0.
char * default_string
Default value for SYNCDB_JSON_STRING object.
int syncdbClientDeregister(syncdbClientHandle_t *client_id)
Deregister a client from the syncdb.
int num_table_change_events
Total number of table-change notifications sent to the client.
Found an element with size equal to 0.
Default value for a string does not fit into size.
syncdbJsonDataType_e
The syncdb supports the following JSON data types: SYNCDB_JSON_NUMBER - A numeric value...
int syncdbRecordTableCreate(syncdbClientHandle_t *client_id, char *table_name, unsigned int table_version, unsigned int node_size, unsigned int flags, char *schema, unsigned int schema_size)
Create a Record Table.
int syncdbTableStatusGet(syncdbClientHandle_t *client_id, int num_tables, syncdbDataTableStatus_t *table_list)
Get Table Status as it pertains to the specified client.
int syncdbTableChangeNotify(syncdbClientHandle_t *client_id, char *table_name)
Notify this client about changes to the specified table.
pthread_mutex_t client_lock
Per-client semaphore.
Two schema nodes have an 8 or more byte gap between them.
Schema node offset plus size is larger than data element.
int syncdbTableChangeCheck(syncdbClientHandle_t *client_id, int timeout_secs)
Check whether any change notifications are pending for this client.
Data Table Status.
int syncdbSet(syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size)
Set an entry in the table.
syncdb Client Handle.
unsigned int table_status
Bit Mask.
unsigned int table_flags
Flags specified on table creation.
int syncdbDelete(syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size)
Delete an entry from the AVL table.
int client_pid
Linux Process ID for this client.