Open Ethernet Networking (OpEN) API Guide and Reference Manual  3.4.4.5
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 {
167  int cmd_socket;
168  int notify_socket;
169  int client_id;
170  pthread_mutex_t client_lock;
171 } syncdbClientHandle_t;
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 
195  int table_type;
196 
200  int num_elements;
201 
205  int num_non_deleted_elements;
206 } syncdbDataTableStatus_t;
207 
210 typedef struct
211 {
212  int client_id;
213  char client_description [SYNCDB_MAX_STR_LEN];
214  int client_pid;
215  int num_commands;
216  int num_table_change_events;
217  int num_table_purges;
218 } syncdbClientStatus_t;
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
265 } syncdbJsonDataType_e;
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;
295  char *default_string;
296  } val;
297 
298 } syncdbJsonNode_t;
299 
302 typedef enum
303 {
304  SYNCDB_SCHEMA_OK = 0,
305  SYNCDB_SCHEMA_TOO_BIG = 1,
306  SYNCDB_SCHEMA_OVERLAP = 2,
307  SYNCDB_SCHEMA_TOO_SHORT = 3,
308  SYNCDB_SCHEMA_GAP = 4,
309  SYNCDB_SCHEMA_INT_OVERFLOW = 5,
310  SYNCDB_SCHEMA_STRING_OVERFLOW = 6,
311  SYNCDB_SCHEMA_INT_SIZE = 7,
312  SYNCDB_SCHEMA_TYPE = 8,
313  SYNCDB_SCHEMA_NO_ZERO_OFFSET = 9,
314  SYNCDB_SCHEMA_ZERO_SIZE = 10,
315  SYNCDB_SCHEMA_DUP_NAME = 11
316 } syncdbSchemaError_e;
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 /*****************************************************************/
425 int syncdbClientDeregister (syncdbClientHandle_t *client_id);
426 
427 /*****************************************************************/
443 int syncdbClientStatusGet (syncdbClientHandle_t *client_id,
444  syncdbClientStatus_t *client_status);
445 
446 /*****************************************************************/
468 int syncdbTableStore (syncdbClientHandle_t *client_id,
469  char *table_name,
470  unsigned int nvram);
471 
472 /*****************************************************************/
505 int syncdbTableChangeCheck (syncdbClientHandle_t *client_id,
506  int timeout_secs);
507 
508 /*****************************************************************/
536 int syncdbTableChangeNotify (syncdbClientHandle_t *client_id,
537  char *table_name);
538 
539 /*****************************************************************/
563 int syncdbTableStatusGet (syncdbClientHandle_t *client_id,
564  int num_tables,
565  syncdbDataTableStatus_t *table_list);
566 
567 /*****************************************************************/
603 int syncdbAvlTableCreate (syncdbClientHandle_t *client_id,
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 /*****************************************************************/
642 int syncdbRecordTableCreate (syncdbClientHandle_t *client_id,
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 /*****************************************************************/
664 int syncdbTableDelete (syncdbClientHandle_t *client_id,
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 /*****************************************************************/
993 int syncdbGetNextChanged (syncdbClientHandle_t *client_id,
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