Open Ethernet Networking (OpEN) API Guide and Reference Manual  3.6.0.3
Data Structures | Macros | Typedefs | Enumerations | Functions
Synchronization Database [OPENAPI_SYNCDB]

Data Structures

struct  syncdbClientHandle_t
 syncdb Client Handle. More...
 
struct  syncdbClientStatus_t
 Client Table Status. More...
 
struct  syncdbDataTableStatus_t
 Data Table Status. More...
 
struct  syncdbJsonNode_s
 The JSON node definition. More...
 

Macros

#define SYNCDB_AGENT_MAX_MSG_SIZE   8000
 Maximum size of the message buffer between the SyncDB process and the SyncDB Agent. More...
 
#define SYNCDB_DUPNAME   (-3)
 Table exists with duplicate name.
 
#define SYNCDB_ENTRY_EXISTS   (-9)
 AVL entry with the specified key already exists.
 
#define SYNCDB_ERROR   (-1)
 General Error.
 
#define SYNCDB_FULL   (-5)
 Specified table is full.
 
#define SYNCDB_JSON_MAX_SCHEMA_SIZE   (SYNCDB_RECORD_MAX_SIZE)
 The schema for storable records is also defined using JSON format. More...
 
#define SYNCDB_MAX_CLIENTS   (-2)
 Reached maximum number of clients.
 
#define SYNCDB_MAX_STR_LEN   256
 Maximum length for string fields used by syncdb. More...
 
#define SYNCDB_NO_TABLE   (-4)
 Specified table does not exist.
 
#define SYNCDB_NOT_FOUND   (-7)
 Specified record is not in the table. More...
 
#define SYNCDB_OK   (0)
 Operation is Successful.
 
#define SYNCDB_RECORD_MAX_SIZE   (1024*64)
 Maximum size of a single data record. More...
 
#define SYNCDB_SCHEMA_ERROR   (-8)
 Schema validation error.
 
#define SYNCDB_SIZE   (-6)
 Specified record size is invalid for this table. More...
 
#define SYNCDB_TABLE_FLAG_EXISTS   (1 << 3)
 When this flag is set, the syncdbInsert() function returns an error if an entry with the specified key already exists. More...
 
#define SYNCDB_TABLE_FLAG_FILE_LOAD   (1 << 2)
 If this flag is enabled then the syncdb tries to populate the table from a file when creating the table. More...
 
#define SYNCDB_TABLE_FLAG_NSF   (1 << 4)
 When this flag is set, the content of the table is synchronized with the backup manager. More...
 
#define SYNCDB_TABLE_FLAG_NVRAM   (1 << 1)
 This table is copied to NVRAM when the table-store command is received. More...
 
#define SYNCDB_TABLE_FLAG_STORABLE   (1 << 0)
 This table can be stored in a file. More...
 
#define SYNCDB_TABLE_NAME_SIZE   32
 Maximum size of the text string that uniquely identifies a database table. More...
 
#define SYNCDB_TABLE_STAT_AVL_TREE_PURGED   (1 << 2)
 AVL Tree Purged (Cleared on Read) This bit indicates that all delete-pending entries have been removed from the AVL tree since the last call to the syncdbTableStatusGet() function. More...
 
#define SYNCDB_TABLE_STAT_CHANGED   (1 << 1)
 Changes pending for this client. More...
 
#define SYNCDB_TABLE_STAT_EXISTS   (1 << 0)
 Specified Table Exist If this bit is not set to 1 then all other bits are meaningless.
 
#define SYNCDB_TABLE_STAT_NEW_TABLE   (1 << 3)
 New Table (Cleared on Read) This bit indicates that the syncdbTableStatusGet() function is called for the first time since the table has been created. More...
 
#define SYNCDB_TABLE_TYPE_AVL_TREE   2
 
#define SYNCDB_TABLE_TYPE_QUEUE   3
 
#define SYNCDB_TABLE_TYPE_RECORD   0
 
#define SYNCDB_TABLE_TYPE_STORABLE_RECORD   1
 

Typedefs

typedef struct syncdbJsonNode_s syncdbJsonNode_t
 The JSON node definition.
 

Enumerations

enum  syncdbJsonDataType_e { SYNCDB_JSON_NUMBER = 1, SYNCDB_JSON_STRING = 2, SYNCDB_JSON_ARRAY = 3 }
 The syncdb supports the following JSON data types: SYNCDB_JSON_NUMBER - A numeric value. More...
 
enum  syncdbSchemaError_e {
  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
}
 The following errors may be reported during schema validation. More...
 

Functions

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. More...
 
int syncdbClientDeregister (syncdbClientHandle_t *client_id)
 Deregister a client from the syncdb. More...
 
int syncdbClientRegister (char *client_name, syncdbClientHandle_t *client_id)
 Register a new client with the syncdb. More...
 
int syncdbClientStatusGet (syncdbClientHandle_t *client_id, syncdbClientStatus_t *client_status)
 Get client information for the specified client ID. More...
 
int syncdbDelete (syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size)
 Delete an entry from the AVL table. More...
 
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. More...
 
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. More...
 
int syncdbGet (syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size, int *delete_pending)
 Get an entry from the table. More...
 
int syncdbGetNext (syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size, int *delete_pending)
 Get the Next entry from the table. More...
 
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. More...
 
int syncdbInsert (syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size)
 Insert a new entry into the AVL table. More...
 
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. More...
 
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. More...
 
int syncdbSet (syncdbClientHandle_t *client_id, char *table_name, void *element, unsigned int size)
 Set an entry in the table. More...
 
int syncdbTableChangeCheck (syncdbClientHandle_t *client_id, int timeout_secs)
 Check whether any change notifications are pending for this client. More...
 
int syncdbTableChangeNotify (syncdbClientHandle_t *client_id, char *table_name)
 Notify this client about changes to the specified table. More...
 
int syncdbTableDelete (syncdbClientHandle_t *client_id, char *table_name)
 Delete specified table or all tables. More...
 
int syncdbTableStatusGet (syncdbClientHandle_t *client_id, int num_tables, syncdbDataTableStatus_t *table_list)
 Get Table Status as it pertains to the specified client. More...
 
int syncdbTableStore (syncdbClientHandle_t *client_id, char *table_name, unsigned int nvram)
 Store specified table or all tables into the file system. More...
 
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. More...
 

Detailed Description

Macro Definition Documentation

#define SYNCDB_AGENT_MAX_MSG_SIZE   8000

Maximum size of the message buffer between the SyncDB process and the SyncDB Agent.

The actual message size may be smaller, and is limited by the transport message size.

Definition at line 49 of file openapi_syncdb.h.

#define SYNCDB_JSON_MAX_SCHEMA_SIZE   (SYNCDB_RECORD_MAX_SIZE)

The schema for storable records is also defined using JSON format.

This compiler constant defines the maximum length of the schema. The constant may be changed to be smaller than the maximum record size, but never bigger.

Definition at line 235 of file openapi_syncdb.h.

#define SYNCDB_MAX_STR_LEN   256

Maximum length for string fields used by syncdb.

This includes client names, file names and various descriptions.

Definition at line 60 of file openapi_syncdb.h.

#define SYNCDB_NOT_FOUND   (-7)

Specified record is not in the table.

Definition at line 83 of file openapi_syncdb.h.

#define SYNCDB_RECORD_MAX_SIZE   (1024*64)

Maximum size of a single data record.

In case of AVL trees and Queues this is the maximum size of each AVL or Queue node.

Definition at line 65 of file openapi_syncdb.h.

#define SYNCDB_SIZE   (-6)

Specified record size is invalid for this table.

Definition at line 82 of file openapi_syncdb.h.

#define SYNCDB_TABLE_FLAG_EXISTS   (1 << 3)

When this flag is set, the syncdbInsert() function returns an error if an entry with the specified key already exists.

When this flag is not set the old entry is overwriten with the new content.

Definition at line 155 of file openapi_syncdb.h.

#define SYNCDB_TABLE_FLAG_FILE_LOAD   (1 << 2)

If this flag is enabled then the syncdb tries to populate the table from a file when creating the table.

The flag is allowed only if the SYNCDB_TABLE_FLAG_STORABLE is also set.

Definition at line 148 of file openapi_syncdb.h.

#define SYNCDB_TABLE_FLAG_NSF   (1 << 4)

When this flag is set, the content of the table is synchronized with the backup manager.

On non-stacking platform the flag has no effect. Applications that use SyncDB for the Non Stop Forwarding feature should store the data in the table using the big-endian format.

Definition at line 162 of file openapi_syncdb.h.

#define SYNCDB_TABLE_FLAG_NVRAM   (1 << 1)

This table is copied to NVRAM when the table-store command is received.

The flag is allowed only if the SYNCDB_TABLE_FLAGS_STORABLE is also set.

Definition at line 142 of file openapi_syncdb.h.

#define SYNCDB_TABLE_FLAG_STORABLE   (1 << 0)

This table can be stored in a file.

When this flag is set the table creation function must be given the schema and the schema size.

Definition at line 136 of file openapi_syncdb.h.

#define SYNCDB_TABLE_NAME_SIZE   32

Maximum size of the text string that uniquely identifies a database table.

The size includes the 0 terminator. This value must be divisible by 2.

Definition at line 55 of file openapi_syncdb.h.

#define SYNCDB_TABLE_STAT_AVL_TREE_PURGED   (1 << 2)

AVL Tree Purged (Cleared on Read) This bit indicates that all delete-pending entries have been removed from the AVL tree since the last call to the syncdbTableStatusGet() function.

This means that some record delete notifications may have been missed by this client. The client needs to completely resynchronize with the AVL tree if it needs to know the exact content. If the table is not an AVL tree then this bit is always set to 0.

Definition at line 115 of file openapi_syncdb.h.

#define SYNCDB_TABLE_STAT_CHANGED   (1 << 1)

Changes pending for this client.

(Cleared on Read) This bit is set whenever something changes in the table. The bit is cleared when the syncdbTableStatusGet() function is invoked by the client for the table. When a client gets a table change notification, this bit can be used to determine which table has changed. However the client does not need to be registered for change notifications. The bit is set for all clients when the table changes.

Definition at line 104 of file openapi_syncdb.h.

#define SYNCDB_TABLE_STAT_NEW_TABLE   (1 << 3)

New Table (Cleared on Read) This bit indicates that the syncdbTableStatusGet() function is called for the first time since the table has been created.

This flag can be used to detect that a table has been deleted and recreated. Normally applications do not delete tables, even when they are restarted. If a table needs to be deleted then all applications using this table should be restarted.

Definition at line 125 of file openapi_syncdb.h.

Enumeration Type Documentation

The syncdb supports the following JSON data types: SYNCDB_JSON_NUMBER - A numeric value.

Syncdb supports only unsigned integers. SYNCDB_JSON_STRING - Zero-terminated array of characters. SYNCDB_JSON_ARRAY - Syncdb supports only arrays of bytes. The default value is 0.

SYNCDB Data Type Limitations: The syncdb supports only a subset of JSON data types. The most important limitation is the limited support for arrays. Arrays are difficult to handle during data format migration, so should be avoided when defining storable records. Syncdb does support arrays of bytes. The table creator cannot provide default values for the byte arrays. The default for array content is always zero.

The syncdb supports only unsigned integer values for SYNCDB_JSON_NUMBER type. The supported integer sizes are 1, 2, 4, and 8 bytes. Floating point numbers and exponential notation is not supported. Signed integers are also not supported. If a signed integer is used in the node definition then the data migration may not work properly.

The syncdb also does not support "true", "false", and "null" values. These can be represented with an integer.

Definition at line 260 of file openapi_syncdb.h.

The following errors may be reported during schema validation.

Enumerator
SYNCDB_SCHEMA_OK 

No error.

SYNCDB_SCHEMA_TOO_BIG 

Schema node offset plus size is larger than data element.

SYNCDB_SCHEMA_OVERLAP 

Schema nodes overlap each other.

SYNCDB_SCHEMA_TOO_SHORT 

Data element has 8 or more bytes beyond last schema node.

SYNCDB_SCHEMA_GAP 

Two schema nodes have an 8 or more byte gap between them.

SYNCDB_SCHEMA_INT_OVERFLOW 

Default value for an integer does not fit into size.

SYNCDB_SCHEMA_STRING_OVERFLOW 

Default value for a string does not fit into size.

SYNCDB_SCHEMA_INT_SIZE 

Integer size is not 1, 2, 4, or 8.

SYNCDB_SCHEMA_TYPE 

Data type is not Number, String or Array.

SYNCDB_SCHEMA_NO_ZERO_OFFSET 

No node with offset set to 0.

SYNCDB_SCHEMA_ZERO_SIZE 

Found an element with size equal to 0.

SYNCDB_SCHEMA_DUP_NAME 

The element has the same name as another element in the schema.

Definition at line 302 of file openapi_syncdb.h.

Function Documentation

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.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for this table.
[in]table_versionVersion of this table.
[in]max_elementsMaximum number of nodes in the AVL tree.
[in]max_live_elementsMaximum number of nodes in the AVL tree that are not pending for removal. This value must be greater than 0 and less or equal to max_elements.
[in]node_sizeUser data number of bytes in each table element. The size includes the key field. The maximum node size is: SYNCDB_RECORD_MAX_SIZE
[in]key_sizeNumber of bytes in the key element. The first 'key_size' bytes are treated as the key. The maximum key size is: SYNCDB_RECORD_MAX_SIZE
[in]flagsTable Creation Flags SYNCDB_TABLE_FLAG_STORABLE - Schema is present. SYNCDB_TABLE_FLAG_FILE_LOAD - Load the table from file if file exists. SYNCDB_TABLE_FLAG_NVRAM - Copy to NVRAM when storing the table.
[in]schemaJSON schema create using the syncdbUtilSchemaCreate(). Must be set to 0 for non-storable tables. Must be non-zero for storable tables.
[in]schema_sizeJSON schema size returned by the syncdbUtilSchemaCreate(). Must be 0 for non-storable tables. The maximum schema size is: SYNCDB_JSON_MAX_SCHEMA_SIZE
Returns
SYNCDB_OK - The table is created.
SYNCDB_ERROR - Can't create the table.
SYNCDB_DUPNAME - The table is not created because another table already exists with the same name.

OpEN API Version: 1.10

int syncdbClientDeregister ( syncdbClientHandle_t client_id)

Deregister a client from the syncdb.

Parameters
[in]client_idClient ID to deregister.
Returns
SYNCDB_OK - Client is registered.
SYNCDB_ERROR - Can't create socket.
Note
The syncdb automatically deregisters clients whose process is terminated.

OpEN API Version: 1.10

int syncdbClientRegister ( char *  client_name,
syncdbClientHandle_t client_id 
)

Register a new client with the syncdb.

Parameters
[in]client_nameDescriptive name for this client.
[out]client_idID used on subsequent transactions. The client_id contains the command socket, the notification socket and unique syncdb client ID.
Returns
SYNCDB_OK - Client is registered.
SYNCDB_ERROR - Can't create socket.
SYNCDB_MAX_CLIENTS - Too many clients already registered.
Note
The client may deregister using the syncdbClientDeregister(). The syncdb automatically deregisters clients whose process is terminated.
The client_id.client_id returned parameter is a unique identifier for the client within the system. The client ID is an integer between 0 and 65535. The client IDs are assigned in the incrementing order. When the maximum value is reached the client ID is wrapped to 0. This means that client IDs are not reused immediately.
The list of active clients is maintained by syncdb in the internal AVL table "syncdb-client-table". The applications can register to be notified about changes to this table and perform Get/GetNext/GetNextChanged operations on that table. The client table in conjunction with the client ID re-use policy allows applications to detect when any other application fails.
Multiple clients may register with the same client_name.
The function may be called from a process or a pthread. Multiple registrations by the same process or by the same pthread are allowed.
The return client handle includes socket descriptors. The returned client handle can only be used by the process that registered with the syncdb. A pthread can pass the handle to another pthread, but only one pthread can invoke a syncdb API call on the same client handle at any one time.

OpEN API Version: 1.10

Examples:
bfd_monitor.c.
int syncdbClientStatusGet ( syncdbClientHandle_t client_id,
syncdbClientStatus_t client_status 
)

Get client information for the specified client ID.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in,out]client_statusInformation about this client.
Returns
SYNCDB_OK - Status is returned.
SYNCDB_ERROR - The status request failed.
SYNCDB_NOT_FOUND - The client does not exist.
Note
The caller must set the client_status->client_id to the syncdb client ID for which to retrieve status.

OpEN API Version: 1.10

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

Delete an entry from the AVL table.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for this table.
[in]elementPointer to the data element to be deleted.
[in]sizeNumber of bytes in the element.
Returns
SYNCDB_OK - Entry is deleted.
SYNCDB_ERROR - Unspecified error.
SYNCDB_NO_TABLE - Specified table does not exist.
SYNCDB_SIZE - The specified size is invalid.
SYNCDB_NOT_FOUND - Entry is not found in the table.
Note
The Delete operation is supported only on AVL trees. If the specified table is not an AVL tree then the SYCNDB_ERROR error code is returned.
The 'size' must be exactly the same as the record size specified on table creation. If the size is invalid then SYNCDB_SIZE error code is returned.

OpEN API Version: 1.10

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.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for this table.
[in,out]elementCaller must pass a buffer where the data is written. The buffer must be big enough to contain 'size' bytes.
[in]sizeNumber of bytes in the element.
[in]field_offsetStart of the field to retrieve from the table. The value represents the number of bytes from the start of the table.
[in]field_sizeSize of the field to get.
[in]flags_unchangedDo not clear the notification-pending and the delete-pending flags.
[out]delete_pendingFor AVL Trees this indicates whether the record is pending for deletion. The field is unused for records and queues.
Returns
SYNCDB_OK - Entry is found. Need to check delete_pending flag for AVL trees.
SYNCDB_ERROR - Unspecified error.
SYNCDB_NO_TABLE - Specified table does not exist.
SYNCDB_SIZE - The specified size is invalid.
SYNCDB_NOT_FOUND - Entry is not found in the table.
Note
This command works for Records and AVL Trees. For AVL Trees the command retrieves the element which matches the key.
The 'size' must be exactly the same as the record size specified on the table creation. If the size is invalid then SYNCDB_SIZE error code is returned.
The field offset plus the field size must be less or equal to the "size". Note that multiple adjacent fields can be retrieved at the same time. The whole record can be retrieved by setting the "field_offset" to 0 and "field_size" to "size".
The function may be used to retrieve data without clearing the change notification and delete-pending flags by setting the "flags_unchanged" parameter to 1.

OpEN API Version: 1.10

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.

The remaining fields in the entry are unchanged.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for this table.
[in]elementCaller must pass a buffer where the data is located.
[in]sizeNumber of bytes in the element.
[in]field_offsetStart of the field to set in the table. The value represents the number of bytes from the start of the element.
[in]field_sizeSize of the field to set.
Returns
SYNCDB_OK - Entry is modified.
SYNCDB_ERROR - Unspecified error.
SYNCDB_NO_TABLE - Specified table does not exist.
SYNCDB_SIZE - The specified size is invalid.
SYNCDB_NOT_FOUND - Entry is not found in the table.
Note
This command works for Records and AVL Trees. For AVL Trees the command modifies the element which matches the key.
The command is useful when multiple processes modify different fields in the same record.
The 'size' must be exactly the same as the record size specified on the table creation. If the size is invalid then SYNCDB_SIZE error code is returned.
The field offset plus the field size must be less or equal to the "size". Note that multiple adjacent fields can be set at the same time. The whole record can be set by setting the "field_offset" to 0 and "field_size" to "size".

OpEN API Version: 1.10

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

Get an entry from the table.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for this table.
[in,out]elementCaller must pass a buffer where the data is written. The buffer must be big enough to contain 'size' bytes.
[in]sizeNumber of bytes in the element.
[out]delete_pendingFor AVL Trees this indicates whether the record is pending for deletion. The field is unused for records and queues.
Returns
SYNCDB_OK - Entry is found. Need to check delete_pending flag for AVL trees.
SYNCDB_ERROR - Unspecified error.
SYNCDB_NO_TABLE - Specified table does not exist.
SYNCDB_SIZE - The specified size is invalid.
SYNCDB_NOT_FOUND - Entry is not found in the table.
Note
This command works for Records and AVL Trees. For AVL Trees the command retrieves the element which matches the key. For Records the command retrieves the whole record.
The 'size' must be exactly the same as the record size specified on the table creation. If the size is invalid then SYNCDB_SIZE error code is returned.

OpEN API Version: 1.10

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

Get the Next entry from the table.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for this table.
[in,out]elementCaller must pass a buffer where the data is written. The buffer must be big enough to contain 'size' bytes.
[in]sizeNumber of bytes in the element.
[out]delete_pendingFor AVL Trees this indicates whether the record is pending for deletion. The field is unused for records and queues.
Returns
SYNCDB_OK - Entry is found.
SYNCDB_ERROR - Unspecified error.
SYNCDB_NO_TABLE - Specified table does not exist.
SYNCDB_SIZE - The specified size is invalid.
SYNCDB_NOT_FOUND - Entry is not found in the table.
Note
This command works only for AVL Trees. The command does not work for other table types. For AVL Trees the command retrieves the element which matches the next higher key.
The 'size' must be exactly the same as the record size specified on the table creation. If the size is invalid then SYNCDB_SIZE error code is returned.

OpEN API Version: 1.10

Examples:
bfd_monitor.c.
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.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for this table.
[in,out]elementCaller must pass a buffer where the data is written. The buffer must be big enough to contain 'size' bytes.
[in]sizeNumber of bytes in the element.
[out]delete_pendingFor AVL Trees this indicates whether the record is pending for deletion. The field is unused for records and queues.
Returns
SYNCDB_OK - Entry is found.
SYNCDB_ERROR - Unspecified error.
SYNCDB_NO_TABLE - Specified table does not exist.
SYNCDB_SIZE - The specified size is invalid.
SYNCDB_NOT_FOUND - Entry is not found in the table.
Note
This command works only for AVL Trees. The command does not work for other table types. For AVL Trees the command retrieves the element which matches the next higher key and which has changed since this client performed the last Get/GetNext/GetNextChanged operation for this record.
The 'size' must be exactly the same as the record size specified on the table creation. If the size is invalid then SYNCDB_SIZE error code is returned.

OpEN API Version: 1.10

Examples:
bfd_monitor.c.
int syncdbInsert ( syncdbClientHandle_t client_id,
char *  table_name,
void *  element,
unsigned int  size 
)

Insert a new entry into the AVL table.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for this table.
[in]elementPointer to the data element to be inserted.
[in]sizeNumber of bytes in the element.
Returns
SYNCDB_OK - Entry is inserted.
SYNCDB_ERROR - Unspecified error.
SYNCDB_NO_TABLE - Specified table does not exist.
SYNCDB_FULL - Specified table is already full.
SYNCDB_SIZE - The specified size is invalid.
SYNCDB_ENTRY_EXISTS - The specified entry already exists and the SYNCDB_TABLE_FLAG_EXISTS is enabled for the table.
Note
The Insert operation is supported only on AVL trees. If the specified table is not an AVL then the SYCNDB_ERROR error code is returned.
The 'size' must be exactly the same as the record size specified on table creation. If the size is invalid then SYNCDB_SIZE error code is returned.
If the element with the same key already exists in the tree then the existing element is updated with the new content. If the table is created with the SYNCDB_TABLE_FLAG_EXISTS then the syncdbInsert() fails for an entry with the duplicate key and returns the SYNCDB_ENTRY_EXISTS error.

OpEN API Version: 1.10

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.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]sync_mode1 - Enable Sync. 0 - Disable Sync.
[in]max_msg_sizeMaximum number of bytes in the sync message.
Returns
SYNCDB_OK - Command is successful.
SYNCDB_ERROR - Error.

OpEN API Version: 1.10

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.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for this table.
[in]table_versionVersion of this table.
[in]node_sizeUser data number of bytes in the table element. The maximum node size is: SYNCDB_RECORD_MAX_SIZE
[in]flagsTable Creation Flags SYNCDB_TABLE_FLAG_STORABLE - Schema is present. SYNCDB_TABLE_FLAG_FILE_LOAD - Load the table from file if file exists. SYNCDB_TABLE_FLAG_NVRAM - Copy to NVRAM when storing the table.
[in]schemaJSON schema create using the syncdbUtilSchemaCreate(). Must be set to 0 for non-storable tables. Must be non-zero for storable tables.
[in]schema_sizeJSON schema size returned by the syncdbUtilSchemaCreate(). Must be 0 for non-storable tables. The maximum schema size is: SYNCDB_JSON_MAX_SCHEMA_SIZE
Returns
SYNCDB_OK - The table is created.
SYNCDB_ERROR - Can't create the table.
SYNCDB_DUPNAME - The table is not created because another table already exists with the same name.

OpEN API Version: 1.10

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

Set an entry in the table.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for this table.
[in]elementPointer to the data buffer to be set in the table.
[in]sizeNumber of bytes in the element.
Returns
SYNCDB_OK - Entry is modified.
SYNCDB_ERROR - Unspecified error.
SYNCDB_NO_TABLE - Specified table does not exist.
SYNCDB_SIZE - The specified size is invalid.
SYNCDB_NOT_FOUND - Entry is not found in the table.
Note
This command works for Records and AVL Trees. For AVL Trees the command modifies the element which matches the key. For Records the command modifies the whole record.
For AVL Trees and Records the 'size' must be exactly the same as the record size specified on table creation.
If the size is invalid then SYNCDB_SIZE error code is returned.

OpEN API Version: 1.10

int syncdbTableChangeCheck ( syncdbClientHandle_t client_id,
int  timeout_secs 
)

Check whether any change notifications are pending for this client.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]timeout_secsHow many seconds to wait. 0 - Do not wait. Return immediately. < 0 - Wait forever. > 0 - Wait specified number of seconds.
Returns
SYNCDB_OK - Change notifications are pending.
SYNCDB_ERROR - No pending notifications.
Note
This function checks the event socket and returns immediately or waits for an event.
If the user application needs to handle other socket events then it can explicitly add the client_id->notify_socket to the select() statement which it uses to wait for other sockets. The syncdbTableChaneCheck() can then be called with 0 timeout to check for events and drain the event socket.
If the process receives a signal, and the wait is with a timeout then the function exits.
If the wait is "forever" then signals do not cause the function to exit.

OpEN API Version: 1.10

Examples:
bfd_monitor.c.
int syncdbTableChangeNotify ( syncdbClientHandle_t client_id,
char *  table_name 
)

Notify this client about changes to the specified table.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameUnique name for the table.
Returns
SYNCDB_OK - Table notification is enabled.
SYNCDB_ERROR - Table notification is not enabled.
SYNCDB_NO_NAME - Specified table does not exist.
Note
The function works for every table type. Note that there is no API to disable table notifications. When a process that created the client ID dies, the syncdb automatically disables table change notifications for that client.
The table changes made after the registration cause events to be generated to the client. To make sure that the client does not miss any events, the client should read the content of whole table after registering for notifications.
The change notifications are NOT sent to the client which is making the table change.

OpEN API Version: 1.10

Examples:
bfd_monitor.c.
int syncdbTableDelete ( syncdbClientHandle_t client_id,
char *  table_name 
)

Delete specified table or all tables.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameName of the table to be deleted.
Returns
SYNCDB_OK - Specified table is deleted.
SYNCDB_ERROR - Error.
SYNCDB_NO_TABLE - Specified table does not exist.

OpEN API Version: 1.10

int syncdbTableStatusGet ( syncdbClientHandle_t client_id,
int  num_tables,
syncdbDataTableStatus_t table_list 
)

Get Table Status as it pertains to the specified client.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]num_tablesNumber of tables in the list.
[in,out]table_listList of tables.
Returns
SYNCDB_OK - Status is returned.
SYNCDB_ERROR - The status request failed.
SYNCDB_SIZE - Too many tables in the table_list.
Note
The SYNCDB_OK means that the status command returned information. The return code should not be used as an indication that specified table or tables exist. The caller needs to check the status for each table to see if it is present.
The maximum size of the table_list array must be less or equal to SYNCDB_RECORD_MAX_SIZE. Otherwise the function returns the SYNCDB_SIZE error.

OpEN API Version: 1.10

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

Store specified table or all tables into the file system.

Parameters
[in]client_idHandle returned by syncdbClientRegister()
[in]table_nameName of the table to be written to the file. NULL - Store all tables to the file system.
[in]nvramNon-Zero - Save tables in NVRAM. 0 - Save tables only in the RAM disk.
Returns
SYNCDB_OK - Specified table(s) is written to file.
SYNCDB_ERROR - Error.
SYNCDB_NO_TABLE - Specified table does not exist.
Note
Only storable tables are written to the file system. The storable tables are created with the SYNCDB_TABLE_FLAG_STORABLE property.
If the "nvram" flag is set to 1, then tables with the SYNCDB_TABLE_FLAG_NVRAM are saved in NVRAM.

OpEN API Version: 1.10

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.

Parameters
[in]element_nodeElement descriptor nodes.
[in]node_schema_sizeSize of the element node array.
[in]schema_bufBuffer in which the JSON schema is returned. The caller must allocate space for this buffer.
[in]buf_sizeNumber of bytes in the schema_buf. The maximum buffer size is: SYNCDB_JSON_MAX_SCHEMA_SIZE
[out]schema_sizeActual schema length.
[in]data_element_sizeData record size. Used for error checking.
[out]schema_errorDetailed schema error code.
Returns
SYNCDB_OK Entry is found.
SYNCDB_ERROR Error in input parameters or element nodes.
SYNCDB_SIZE JSON schema does not fit into schema_buf buffer.
SYNCDB_SCHEMA_ERROR Error in schema.
Note
If an error is detected while generating the schema, the caller can print out the content of the schema_buf to see approximately where the error is found. The schema_buf contains generated schema up to the point where the error was found.

OpEN API Version: 1.10