openapi_syncdb.h

Go to the documentation of this file.

/*********************************************************************
*
* Copyright 2016-2023 Broadcom.
*
*  Licensed under the Apache License, Version 2.0 (the "License");
*  you may not use this file except in compliance with the License.
*  You may obtain a copy of the License at
*
*      http://www.apache.org/licenses/LICENSE-2.0
*
*  Unless required by applicable law or agreed to in writing, software
*  distributed under the License is distributed on an "AS IS" BASIS,
*  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
*  See the License for the specific language governing permissions and
*  limitations under the License.
*
**********************************************************************
*
* @filename    syncdb_api.h
*
* @purpose     API for the Synchronization Database
*
* @component 
*
* @note    
*
* @create      7/5/2012
*
* @end
*
**********************************************************************/
#ifndef SYNCDB_API_H_INCLUDED
#define SYNCDB_API_H_INCLUDED

#include <pthread.h>

#define SYNCDB_AGENT_MAX_MSG_SIZE 8000

#define SYNCDB_TABLE_NAME_SIZE  32

#define SYNCDB_MAX_STR_LEN  256

#define SYNCDB_RECORD_MAX_SIZE (1024*64)

/* Supported Data Table Types.
*/
#define SYNCDB_TABLE_TYPE_RECORD 0
#define SYNCDB_TABLE_TYPE_STORABLE_RECORD 1
#define SYNCDB_TABLE_TYPE_AVL_TREE 2
#define SYNCDB_TABLE_TYPE_QUEUE 3

/* Return Codes from the syncdb API functions.
*/
#define SYNCDB_OK   (0)    
#define SYNCDB_ERROR (-1)        
#define SYNCDB_MAX_CLIENTS (-2)  
#define SYNCDB_DUPNAME (-3) 
#define SYNCDB_NO_TABLE (-4) 
#define SYNCDB_FULL (-5) 
#define SYNCDB_SIZE (-6) 
#define SYNCDB_NOT_FOUND (-7) 
#define SYNCDB_SCHEMA_ERROR (-8) 
#define SYNCDB_ENTRY_EXISTS (-9) 
#define SYNCDB_TIMEOUT (-10) 
/* Data Table Status.
** The status is a bit mask returned by the syncdbTableStatusGet() function. 
** The status is maintained per client.  
*/

#define SYNCDB_TABLE_STAT_EXISTS (1 << 0) 

#define SYNCDB_TABLE_STAT_CHANGED (1 << 1) 

#define SYNCDB_TABLE_STAT_AVL_TREE_PURGED (1 << 2) 

#define SYNCDB_TABLE_STAT_NEW_TABLE (1 << 3) 

/********  Data Table Creation Flags
** The flags specified on the table create call.
** The flags is a bit mask returned by the syncdbTableStatusGet() function. 
********/
#define SYNCDB_TABLE_FLAG_STORABLE (1 << 0)

#define SYNCDB_TABLE_FLAG_NVRAM (1 << 1)

#define SYNCDB_TABLE_FLAG_FILE_LOAD (1 << 2)


#define SYNCDB_TABLE_FLAG_EXISTS (1 << 3)

#define SYNCDB_TABLE_FLAG_NSF (1 << 4)

typedef struct 
{
    int cmd_socket;       
    int notify_socket;  
    int client_id;  
    unsigned long long seqNum; 
    pthread_mutex_t client_lock; 
    unsigned int rxTimeout;  
} syncdbClientHandle_t;

typedef struct
{
    char table_name [SYNCDB_TABLE_NAME_SIZE]; 
    unsigned int table_version;

    unsigned int table_flags;

    unsigned int table_status; 

    int table_type; 

    int num_elements; 

    int num_non_deleted_elements;
} syncdbDataTableStatus_t;

typedef struct 
{
    int client_id; 
    char client_description [SYNCDB_MAX_STR_LEN]; 
    int  client_pid;  
    int  num_commands; 
    int  num_table_change_events; 
    int  num_table_purges; 
} syncdbClientStatus_t;

/******************************** 
** Storable Record Schema 
********************************/ 

/* The AVL trees and records can be stored in a file system using JSON notation.
** In order to store information in the file system the table creator must tell syncdb how 
** the data is formatted. Also to facilitate data format changes the table creator must 
** tell syncdb the default values of fields that are not present in the file. 
*/

#define SYNCDB_JSON_MAX_SCHEMA_SIZE  (SYNCDB_RECORD_MAX_SIZE)

typedef enum
{
  SYNCDB_JSON_NUMBER = 1,
  SYNCDB_JSON_STRING = 2,
  SYNCDB_JSON_ARRAY = 3
} syncdbJsonDataType_e;

typedef struct syncdbJsonNode_s
{
    syncdbJsonDataType_e data_type;

    char *data_name;

    unsigned int data_offset; 

    unsigned int  data_size; 

    union {
        unsigned long long default_number; 
        char *default_string; 
    } val;

} syncdbJsonNode_t;

typedef enum 
{
    SYNCDB_SCHEMA_OK = 0,   
    SYNCDB_SCHEMA_TOO_BIG = 1, 
    SYNCDB_SCHEMA_OVERLAP = 2, 
    SYNCDB_SCHEMA_TOO_SHORT = 3, 
    SYNCDB_SCHEMA_GAP = 4, 
    SYNCDB_SCHEMA_INT_OVERFLOW = 5, 
    SYNCDB_SCHEMA_STRING_OVERFLOW = 6, 
    SYNCDB_SCHEMA_INT_SIZE = 7, 
    SYNCDB_SCHEMA_TYPE = 8, 
    SYNCDB_SCHEMA_NO_ZERO_OFFSET = 9, 
    SYNCDB_SCHEMA_ZERO_SIZE = 10, 
    SYNCDB_SCHEMA_DUP_NAME = 11 
} syncdbSchemaError_e;

/******************************** 
** syncdb API Functions 
*********************************/ 

/*****************************************************************/
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
                            );

/*****************************************************************/
int syncdbClientRegister (char *client_name,
                          syncdbClientHandle_t  *client_id);

/*****************************************************************/
int syncdbClientDeregister (syncdbClientHandle_t  *client_id);

/*****************************************************************/
int syncdbClientStatusGet (syncdbClientHandle_t  *client_id,
                          syncdbClientStatus_t *client_status);

/*****************************************************************/
int syncdbTableStore (syncdbClientHandle_t  *client_id,
                          char *table_name,
                          unsigned int nvram);

/*****************************************************************/
int syncdbTableChangeCheck (syncdbClientHandle_t  *client_id,
                          int  timeout_secs);

/*****************************************************************/
int syncdbTableChangeNotify (syncdbClientHandle_t  *client_id,
                          char  *table_name);

/*****************************************************************/
int syncdbTableStatusGet (syncdbClientHandle_t  *client_id,
                          int num_tables,
                          syncdbDataTableStatus_t *table_list);

/*****************************************************************/
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);

/*****************************************************************/
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);

/*****************************************************************/
int syncdbTableDelete (syncdbClientHandle_t  *client_id,
                          char *table_name);

/*****************************************************************/
int syncdbInsert (syncdbClientHandle_t  *client_id,
                          char  *table_name,
                          void *element,
                          unsigned int   size);

/*****************************************************************/
int syncdbDelete (syncdbClientHandle_t  *client_id,
                          char  *table_name,
                          void *element,
                          unsigned int   size);

/*****************************************************************/
int syncdbSet (syncdbClientHandle_t  *client_id,
                          char  *table_name,
                          void *element,
                          unsigned int   size);

/*****************************************************************/
int syncdbFieldSet (syncdbClientHandle_t  *client_id,
                          char  *table_name,
                          void *element,
                          unsigned int   size,
                          unsigned int field_offset,
                          unsigned int field_size);

/*****************************************************************/
int syncdbGet (syncdbClientHandle_t  *client_id,
                          char  *table_name,
                          void *element,
                          unsigned int   size,
                          int *delete_pending);

/*****************************************************************/
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);

/*****************************************************************/
int syncdbGetNext (syncdbClientHandle_t  *client_id,
                          char  *table_name,
                          void *element,
                          unsigned int   size,
                          int *delete_pending);

/*****************************************************************/
int syncdbGetNextChanged (syncdbClientHandle_t  *client_id,
                          char  *table_name,
                          void *element,
                          unsigned int   size,
                          int *delete_pending);

/*****************************************************************/
int syncdbNsfModeSet (syncdbClientHandle_t  *client_id,
                          unsigned int sync_mode,
                          unsigned int max_msg_size);

#endif /* SYNCDB_API_H_INCLUDED */