RTI Connext DDS Micro  Version 2.4.11
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
db_api.h
1 /*
2  * FILE: db_api.h - DB API definitions
3  *
4  * (c) Copyright, Real-Time Innovations, 2012-2015.
5  * All rights reserved.
6  *
7  * No duplications, whole or partial, manual or electronic, may be made
8  * without express written permission. Any such copies, or
9  * revisions thereof, must display this notice unaltered.
10  * This code contains trade secrets of Real-Time Innovations, Inc.
11  *
12  * Modification History
13  * --------------------
14  * 04nov2015,tk MICRO-1505 Reduce memory footprint
15  * 31jul2014,tk MICRO-241/PR#1413 - Removed superfluous DB fields
16  * 31jul2014,tk MICRO-842/PR#9683 - Removed superfluous paramaters in DB
17  * compare function
18  * 06may2014,tk MICRO-227 (Verocel PR#1406): Refactored get_count() to better
19  * handle error conditions
20  * 28may2012,tk Written
21  */
22 /*ci
23  * \file
24  * \defgroup DBModule DB
25  *
26  * \brief Public DB API
27  *
28  * \details
29  * This file defines the public API for the database. It contains functions
30  * to create/delete databases, create/delete tables, create/delete records
31  * in tables and functions to traverse and index database tables based on keys.
32  * The database API is not a general purpose API, it is only designed to support
33  * features in Connext Micro.
34  */
35 
36 /*ci \addtogroup DBModule
37  * @{
38  */
39 #ifndef db_api_h
40 #define db_api_h
41 
42 #ifndef db_dll_h
43 #include "db/db_dll.h"
44 #endif
45 #ifndef osapi_types_h
46 #include "osapi/osapi_types.h"
47 #endif
48 #ifndef osapi_mutex_h
49 #include "osapi/osapi_mutex.h"
50 #endif
51 
52 #ifdef __cplusplus
53 extern "C"
54 {
55 #endif
56 
57 /*ci
58  * \ingroup DBModule
59  */
60 
61 /*ci
62  * \brief Abstract database declaration
63  * \ingroup DBModule
64  */
65 struct DB_Database;
66 
67 /*ci
68  * \brief Abstract database type
69  */
70 typedef struct DB_Database* DB_Database_T;
71 
72 /*ci
73  * \brief Abstract database table
74  */
75 struct DB_Table;
76 
77 /*ci
78  * \brief Abstract database table type
79  */
80 typedef struct DB_Table *DB_Table_T;
81 
82 /*ci
83  * \brief Abstract database table record
84  */
85 struct DB_Record;
86 
87 /*ci
88  * \brief Abstract database table record type
89  */
90 typedef void *DB_Record_T;
91 
92 /*ci
93  * \brief Abstract database key
94  */
95 typedef void *DB_Key_T;
96 
97 /*ci
98  * \brief Abstract database cursor
99  */
100 struct DB_Cursor;
101 
102 /*ci
103  * \brief Abstract database cursor type
104  */
105 typedef struct DB_Cursor *DB_Cursor_T;
106 
107 /*ci
108  * \brief Abstract database index
109  */
110 struct DB_Index;
111 
112 /*ci
113  * \brief Abstract database index type
114  */
115 typedef struct DB_Index *DB_Index_T;
116 
117 /****************/
118 
119 /*ci
120  * \brief Maximum length of a database name in ASCIIZ format, NULL included
121  */
122 #define URTDB_DATABASE_NAME_MAX_LENGTH 16
123 
124 /*ci
125  * \brief Maximum length of a table name in ASCIIZ format, NULL included
126  */
127 #define URTDB_TABLE_NAME_MAX_LENGTH 16
128 
129 /*ci
130  * \brief The value for the default index. The default index is created
131  * based on the compare function passed to the \ref DB_Database_create_table
132  * function.
133  */
134 #define DB_TABLE_DEFAULT_INDEX 0
135 
136 /*ci
137  * \brief Return code for database function
138  */
139 typedef enum
140 {
141  /*ci
142  * \brief Function call was successful
143  */
144  DB_RETCODE_OK = 0,
145 
146  /*ci
147  * \brief Invalid arguments to function
148  */
149  DB_RETCODE_BAD_PARAMETER,
150 
151  /*ci
152  * \brief One or more records still exist in the database
153  */
154  DB_RETCODE_EXISTS,
155 
156  /*ci
157  * \brief An cursor contains no more data, or a search did not yield any
158  * results
159  */
160  DB_RETCODE_NO_DATA,
161 
162  /*ci
163  * \brief The database is out of one or more pre-allocated resources
164  */
165  DB_RETCODE_OUT_OF_RESOURCES,
166 
167  /*ci
168  * \brief A cursor is no longer valid due to the database being updated
169  * while the cursor was in use
170  */
171  DB_RETCODE_INVALIDATED_CURSOR,
172 
173  /*ci
174  * \brief Generic catch all return code in case of failure
175  */
176  DB_RETCODE_ERROR
177 } DB_ReturnCode_T;
178 
179 /*ci
180  * \brief Database locking granularity
181  */
182 typedef enum
183 {
184  /*ci
185  * \brief The database is never locked
186  */
187  DB_LOCK_LEVEL_NONE = 0,
188 
189  /*ci
190  * \brief The database is using a shared lock (outside of the database)
191  */
192  DB_LOCK_LEVEL_SHARED = 1,
193 
194  /*ci
195  * \brief The database is using a global lock created internally
196  */
197  DB_LOCK_LEVEL_GLOBAL = 2
198 } DB_LockLevel_T;
199 
200 /*ci
201  * \brief Record selection criteria
202  */
203 typedef enum
204 {
205  /*ci
206  * \brief Select record from a table based on exact match
207  */
208  DB_SELECTOPCODE_EQUAL = 1,
209 
210  /*ci
211  * \brief Select records from a table that has a key within a range
212  */
213  DB_SELECTOPCODE_BETWEEN = 2,
214 
215  /*ci
216  * \brief Select all records from a table
217  */
218  DB_SELECTOPCODE_ALL = 3
219 } DB_Select_T;
220 
221 /*ci
222  * \brief Database properties
223  *
224  * \details
225  *
226  * A new database can be created with the following properties. Note that
227  * the properties are immutable.
228  */
229 struct DB_DatabaseProperty
230 {
231  /*ci
232  * \brief The maximum number of tables the database can contain
233  */
234  RTI_SIZE_T max_tables;
235 
236  /*ci
237  * \brief The locking mode used for the database
238  */
239  DB_LockLevel_T lock_mode;
240 };
241 
242 /*ci
243  * \brief Initialize a \ref DB_DatabaseProperty to a default value
244  */
245 #define DB_DatabaseProperty_INITIALIZER \
246 {\
247  1,\
248  DB_LOCK_LEVEL_NONE\
249 }
250 
251 /*ci
252  * \brief Operand 2 in the compare function is a key
253  */
254 #define DB_SELECT_OP2_AS_KEY (0x1)
255 
256 /*ci
257  * \brief Test if operand 2 in the compare function is a key
258  */
259 #define DB_SELECT_OP2_IS_KEY(flags) (flags & DB_SELECT_OP2_AS_KEY)
260 
261 /*ci
262  * \brief A generic record compare function
263  *
264  * \details
265  *
266  * A table contains records sorted by a key. It is not possible to
267  * create a table with no compare function. The compare function must
268  * maintain an ordered relationship.
269  *
270  * \param[in] flags Information about the operands
271  * \param[in] op1 Always DB_Record_T
272  * \param[in] key DB_Record_T or DB_Key_T (passed transparently from the user)
273  *
274  * \return positive integer if op1 is greater than key,
275  * negative integer if op1 is less than key,
276  * zero if left is equal to key
277  *
278  * \sa \ref DB_SELECT_OP2_IS_KEY
279  */
280 FUNCTION_MUST_TYPEDEF(
281 RTI_INT32
282 (*DB_IndexCompare_T)(RTI_INT32 flags,const DB_Record_T op1, void *key)
283 )
284 
285 /*ci
286  * \brief A record destructor function type
287  *
288  * \details
289  *
290  * When a record is deleted from a table the database still needs the primary
291  * key of the table. However, if the key is dynamically allocated it cannot
292  * be free'd before \ref DB_Table_delete_record is called. To solve this a
293  * record destructor can be passed to DB_Table_delete_record_w_dtor. The
294  * destructor is called when the DB is done with the record and can be used
295  * to clean up any resources.
296  *
297  * \param[in] record To destruct/finalize
298  *
299  * \return A record destructor function must return RTI_TRUE on success and
300  * RTI_FALSE on failure. NOTE: Even if the dtor returns failure the
301  * record is considered deleted.
302  *
303  * \sa DB_Table_delete_record_w_dtor
304  */
305 FUNCTION_SHOULD_TYPEDEF(
306 RTI_BOOL
307 (*DB_Table_RecordDtor_T)(DB_Record_T record)
308 )
309 
310 /*ci
311  * \brief Table properties
312  *
313  * \details
314  *
315  * A table can be created with the following properties. Note that
316  * the properties are immutable.
317  */
318 struct DB_TableProperty
319 {
320  /*ci
321  * \brief The maximum number of records the table can hold
322  */
323  RTI_SIZE_T max_records;
324 
325  /*ci
326  * \brief The maximum number of indices which can be created in the table
327  */
328  RTI_SIZE_T max_indices;
329 
330  /*ci
331  * \brief The maximum number of cursors which can be open on the table
332  * at any given time
333  */
334  RTI_SIZE_T max_cursors;
335 };
336 
337 /*ci
338  * \brief Initialize a \ref DB_TableProperty to a default value
339  */
340 #define DB_TableProperty_INITIALIZER \
341 {\
342  0,\
343  0,\
344  1\
345 }
346 
347 /*ci
348  * \brief Index properties
349  *
350  * \details
351  *
352  * A index can be created with the following properties. Note that
353  * the properties are immutable.
354  */
355 struct DB_IndexProperty
356 {
357  /*ci
358  * \brief The maximum number of entries the index can hold
359  */
360  RTI_SIZE_T max_entries;
361 };
362 
363 /*ci
364  * \brief Initialize a \ref DB_IndexProperty to a default value
365  */
366 #define DB_IndexProperty_INITIALIZER \
367 {\
368  0 \
369 }
370 
371 /**************************** Database Functions ******************************/
372 
373 /*ci
374  * \brief Create an empty database
375  *
376  * \param[inout] db Handle to the newly created database. *db must be NULL.
377  * \param[in] name The name of the database, cannot be NULL. It is OK
378  * to create multiple databases with the same name
379  * \param[in] property The database properties. Cannot be NULL.
380  * \param[in] shared_lock If the lock-level is \ref DB_LOCK_LEVEL_SHARED this
381  * argument must point to a valid mutex.
382  *
383  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
384  * db holds a reference to the new database.
385  *
386  * \sa \ref DB_Database_delete
387  *
388  */
389 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
390 DB_Database_create(DB_Database_T *db,
391  const char *name,
392  struct DB_DatabaseProperty *property,
393  OSAPI_Mutex_T *const shared_lock);
394 
395 #ifndef RTI_CERT
396 /*ci
397  * \brief Delete a database
398  *
399  * \details
400  *
401  * This function deletes a database and returns any used memory to the system.
402  * It is illegal to delete a database that has resources in use. For example,
403  * it is illegal to delete a database where a cursor is open or a table contains
404  * records. This restriction exists to prevent an application from deleting
405  * resources that may be in use and thus could cause a memory access violation.
406  *
407  * \param[in] db Handle to db being deleted
408  *
409  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
410  * the database was deleted and db is no longer a valid handle. Note
411  * the handle is not cleared.
412  *
413  * \sa \ref DB_Database_create
414  *
415  */
416 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
417 DB_Database_delete(DB_Database_T db);
418 #endif /* !RTI_CERT */
419 
420 /*ci
421  * \brief Lock database to prevent modifications
422  *
423  * \details
424  *
425  * This function locks a database, preventing any modification to it.
426  * If the database was created with a lock-level of \ref DB_LOCK_LEVEL_SHARED
427  * or \ref DB_LOCK_LEVEL_GLOBAL the mutex is taken before returning. Otherwise
428  * this call always succeeds. Note that there is no timeout on the mutex.
429  * A locked database must be unlocked with \ref DB_Database_unlock. It is
430  * legal to lock the database multiple times from the same thread, and a
431  * database must be unlocked as many times as it was locked.
432  *
433  * \param[in] db Handle to db to lock
434  *
435  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
436  * the database was successfully locked.
437  *
438  * \sa \ref DB_Database_unlock, \ref DB_LockLevel_T
439  *
440  */
441 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
442 DB_Database_lock(DB_Database_T db);
443 
444 /*ci
445  * \brief Unlock a database previously locked with \ref DB_Database_lock
446  *
447  * \details
448  *
449  * This function unlocks a database, allowing modifications to it. Note that if
450  * a database was locked multiple time, an equal number of unlocks is required.
451  *
452  * \param[in] db Handle to db to unlock
453  *
454  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
455  * the database was successfully unlocked.
456  *
457  * \sa \ref DB_Database_lock, \ref DB_LockLevel_T
458  *
459  */
460 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
461 DB_Database_unlock(DB_Database_T db);
462 
463 /*ci
464  * \brief Temporarily release a database
465  *
466  * \param[in] db Database to release lock on
467  * \param[out] level The current lock-level, must be passed to
468  * \ref DB_Database_lock_resume. Cannot be NULL.
469  *
470  * \return DB_RETCODE_OK on success, DB_RETCODE_ERROR on failure.
471  */
472 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
473 DB_Database_lock_release(DB_Database_T db,RTI_UINT32 *level);
474 
475 /*ci
476  * \brief Resume lock on a database that has temporarily been released.
477  *
478  * \param[in] db Database to resume lock on
479  * \param[in] level The lock-level returned by \ref DB_Database_lock_release
480  *
481  * \return DB_RETCODE_OK on success, DB_RETCODE_ERROR on failure.
482  */
483 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
484 DB_Database_lock_resume(DB_Database_T db,RTI_UINT32 level);
485 
486 /*ci
487  * \brief Create a database table
488  *
489  * \details
490  *
491  * This function creates an empty database table. Every table in the same
492  * database must have a unique name. A table contains fixed size records.
493  * Any memory allocation required by a record must be done outside of the
494  * database. For example, any record that contains pointers or sequences
495  * must be initialized outside of the table itself.
496  *
497  * \param[inout] table Handle to new table. *table must be NULL on input.
498  * \param[in] db Database where the table shall be created.
499  * Cannot be NULL.
500  * \param[in] name Name of the table. Must be unique in the database.
501  * Cannot be NULL.
502  * \param[in] record_size Size in bytes of a record. Must be > 0.
503  * \param[in] compare_func The compare function. Cannot be NULL.
504  * \param[in] property Table properties. Cannot be NULL.
505  *
506  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
507  * the table was successfully created and table contains a handle to
508  * the newly created table.
509  *
510  * \sa \ref DB_Database_delete_table
511  */
512 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
513 DB_Database_create_table(DB_Table_T *table,
514  DB_Database_T db,
515  const char *name,
516  RTI_SIZE_T record_size,
517  DB_IndexCompare_T compare_func,
518  struct DB_TableProperty *property);
519 
520 #ifndef RTI_CERT
521 /*ci
522  * \brief Delete a database table
523  *
524  * \details
525  *
526  * Delete a database table. A database table can only be deleted if it
527  * is empty and there are no outstanding cursors.
528  *
529  * \param[in] db Database to delete table from.
530  * \param[in] table Table to delete.
531  *
532  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
533  * the table was successfully deleted.
534  *
535  * \sa \ref DB_Database_create_table
536  */
537 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
538 DB_Database_delete_table(DB_Database_T db,DB_Table_T table);
539 #endif /* !RTI_CERT */
540 
541 /*************************** Table Functions **********************************/
542 
543 /*ci
544  * \brief Create record in a database table
545  *
546  * \details
547  *
548  * A table can only manage records created from the table. This function
549  * returns an unused record. Note that the record is not initialized. It is
550  * illegal to delete a table with records in use. That is, all records must be
551  * deleted from a table before the table can be deleted.
552  *
553  * \param[in] table Table to create record in.
554  * \param[inout] record Created record. *record must be NULL on input.
555  *
556  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
557  * the record was successfully created and a handle is returned in
558  * record.
559  *
560  * \sa \ref DB_Table_delete_record
561  */
562 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
563 DB_Table_create_record(DB_Table_T table,DB_Record_T *record);
564 
565 /*ci
566  * \brief Insert a record into the table
567  *
568  * \details
569  *
570  * A record becomes available to users of a table only after it is inserted.
571  * If a record is inserted into a cursor selection the cursor is invalidated.
572  *
573  * \param[in] table Table to insert record into.
574  * \param[in] record Record to insert.
575  *
576  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
577  * the record was successfully inserted.
578  *
579  * \sa \ref DB_Table_delete_record
580  *
581  */
582 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
583 DB_Table_insert_record(DB_Table_T table, DB_Record_T record);
584 
585 /*ci
586  * \brief Remove a record from a table
587  *
588  * \details
589  *
590  * Remove a record from the table based on the key. The record is no longer
591  * search-able and it not reusable until deleted with
592  * \ref DB_Table_delete_record.
593  *
594  * \param[in] table Table to remove record from.
595  * \param[out] record Removed record.
596  * \param[in] key The key to search for.
597  *
598  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
599  * the record was removed.
600  *
601  * \sa \ref DB_Table_insert_record
602  *
603  */
604 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
605 DB_Table_remove_record(DB_Table_T table,DB_Record_T *record,DB_Key_T key);
606 
607 /*ci
608  * \brief Delete a record from a table
609  *
610  * \details
611  *
612  * Delete the record from the table. A deleted record will be marked as free
613  * for reuse and may be returned by \ref DB_Table_create_record.
614  *
615  * \param[in] table Table to delete record from.
616  * \param[in] record Record to delete.
617  *
618  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
619  * the record was deleted.
620  *
621  * \sa \ref DB_Table_create_record
622  */
623 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
624 DB_Table_delete_record(DB_Table_T table,DB_Record_T record);
625 
626 /*ci
627  * \brief Delete a record from a table with with a record destructor
628  *
629  * \details
630  *
631  * Delete the record from the table. A deleted record will be marked as free
632  * for reuse and may be returned by \ref DB_Table_create_record. The provided
633  * dtor, if not NULL, is called to finalize the record before it is returned to
634  * for reuse. This is useful for records that use dynamically allocated
635  * keys that are either the primary key or a part of a key for an index.
636  *
637  * \param[in] table Table to delete record from.
638  * \param[in] record Record to delete.
639  * \paran[in] dtor Function pointer to call with record to finalize the
640  * content. See \ref DB_Table_RecordDtor_T for details.
641  *
642  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
643  * the record was deleted.
644  *
645  * \sa \ref DB_Table_create_record
646  */
647 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
648 DB_Table_delete_record_w_dtor(DB_Table_T table,DB_Record_T record,
649  DB_Table_RecordDtor_T dtor);
650 
651 /*ci
652  * \brief Create a new index for a table
653  *
654  * \details
655  *
656  * A table always has a default index based on the compare function passed
657  * to \ref DB_Database_create_table function. It is however possible to create
658  * a subset of the table or sort the records in a different order by creating
659  * a new index. Note that it is illegal to delete a table with indices
660  * (except for the default).
661  *
662  * \param[in] table Table to create index for.
663  * \param[inout] index Handle to index, *index must be NULL on input.
664  * \param[in] compare_func Compare function.
665  * \param[in] property The index property.
666  *
667  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
668  * the index was successfully created and a handle is available in the
669  * index output parameter.
670  *
671  * \sa \ref DB_Table_delete_index
672  *
673  */
674 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
675 DB_Table_create_index(DB_Table_T table,
676  DB_Index_T *index,
677  DB_IndexCompare_T compare_func,
678  const struct DB_IndexProperty *const property);
679 /*ci
680  * \brief Delete an index
681  *
682  * \details
683  *
684  * Delete an index previously created with \ref DB_Table_create_index
685  *
686  * \param[in] table Table to delete index from.
687  * \param[in] index Handle to index.
688  *
689  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
690  * the index was successfully deleted.
691  *
692  * \sa \ref DB_Table_delete_index
693  *
694  */
695 #ifndef RTI_CERT
696 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
697 DB_Table_delete_index(DB_Table_T table,DB_Index_T index);
698 #endif /* !RTI_CERT */
699 
700 /*ci
701  * \brief Select all the records from an index
702  *
703  * \details
704  *
705  * Create cursor to iterate over all the records in an index. The
706  * DB_Table_select_all_default function uses the default index which will return
707  * all the records in the table. The records are ordered based on the compare
708  * function for the index used for the selection.
709  *
710  * Note that the database should be locked while iterating over a cursor.
711  *
712  * \param[in] table Table to select records from.
713  * \param[in] index Index to return records from.
714  * \param[out] cursor Cursor to iterate over result set.
715  *
716  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
717  * a cursor was successfully created and a handle is available in the
718  * cursor output parameter.
719  *
720  * \sa \ref DB_Table_select_match, \ref DB_Table_select_range
721  *
722  */
723 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
724 DB_Table_select_all(DB_Table_T table,DB_Index_T index,DB_Cursor_T *cursor);
725 
726 
727 /*ci
728  * \brief Select all the records from the default index
729  *
730  * \details
731  *
732  * Create cursor to iterate over all the records in the default index.
733  * Note that the database should be locked while iterating over a cursor.
734  *
735  * \param[in] table Table to iterate over.
736  * \param[out] cursor Cursor to iterate over result set.
737  *
738  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
739  * a cursor was successfully created and a handle available in the
740  * cursor output parameter.
741  *
742  * \sa \ref DB_Table_select_match, \ref DB_Table_select_range
743  *
744  */
745 #define DB_Table_select_all_default(table_,eh_) \
746  DB_Table_select_all(table_,DB_TABLE_DEFAULT_INDEX,eh_)
747 
748 /*ci
749  * \brief Search for a record in an index
750  *
751  * \details
752  *
753  * Search for a record with a matching key in an index. If a match is found the
754  * record is returned in the record parameter. If none are found
755  * DB_RETCODE_NO_DATA is returned. NOTE: The output parameter is only updated
756  * on success. If no record is found the output argument is _not_ updated.
757  *
758  * \param[in] table Table to search in.
759  * \param[in] index Index to return record from.
760  * \param[out] record Updated with matching record if it is found.
761  * \param[in] key Key to search for.
762  *
763  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
764  * record points to the matching record.
765  *
766  * \sa \ref DB_Table_select_all, \ref DB_Table_select_range
767  *
768  */
769 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
770 DB_Table_select_match(DB_Table_T table,DB_Index_T index,
771  DB_Record_T *record,DB_Key_T key);
772 
773 /*ci
774  * \brief Select all the records from an index that lies within a range
775  *
776  * \details
777  *
778  * Select all records between [lower,upper] keys.
779  *
780  * \param[in] table Table to delete index from
781  * \param[in] index Index to return records from
782  * \param[out] cursor Cursor to the result set
783  * \param[in] lower Lower key to search for
784  * \param[in] upper Upper key to search for
785  *
786  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
787  * cursor holds records which lies within the [lower,upper] range of
788  * keys.
789  *
790  * \sa \ref DB_Table_select_all, \ref DB_Table_select_match
791  *
792  */
793 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
794 DB_Table_select_range(DB_Table_T table,DB_Index_T index,
795  DB_Cursor_T *cursor,
796  DB_Key_T lower,DB_Key_T upper);
797 
798 /*ci
799  * \brief Return the name of a table
800  *
801  * \details
802  *
803  * Return the name of a table
804  *
805  * \param[in] table Table to return name for, cannot be NULL.
806  *
807  * \return pointer to name of table in ASCIIZ format
808  *
809  * \sa
810  */
811 DBDllExport const char*
812 DB_Table_get_name(DB_Table_T table);
813 
814 /*ci
815  * \brief Return the number of records in a result set for a cursor
816  *
817  * \param[in] cursor Cursor to result set.
818  * \param[out] count Number of records the cursor can iterate over.
819  *
820  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
821  * count contains the number of records.
822  *
823  * \sa \ref DB_Table_select_range, \ref DB_Table_select_all
824  */
825 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
826 DB_Cursor_get_count(DB_Cursor_T cursor,RTI_INT32 *count);
827 
828 /*ci
829  * \brief Return the next record the cursor is pointing to
830  *
831  * \details
832  *
833  * This function returns the next record the cursor is pointing to in its
834  * result set. When a cursor is first created it does not point to a record,
835  * but upon the first call to \ref DB_Cursor_get_next it points to the first
836  * record (if any). Note that a cursor cannot be iterated over again, a new
837  * cursor must be created.
838  *
839  * \param[in] handle Cursor with a result set.
840  * \param[out] record Pointer to the next record.
841  *
842  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
843  * record points to the next record.
844  *
845  * \sa \ref DB_Table_select_range, \ref DB_Table_select_all,
846  * \ref DB_Cursor_finish
847  */
848 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
849 DB_Cursor_get_next(DB_Cursor_T handle, DB_Record_T *record);
850 
851 /*ci
852  * \brief Close a cursor
853  *
854  * \details
855  *
856  * This function closes a cursor and returns it to the table. Note that it
857  * is illegal to delete a table if there are open cursors.
858  *
859  * \param[in] table Table the cursor should be returned to. Must be the
860  * same table the cursor was created from. Note that the
861  * caller is responsible to make sure this is the case.
862  *
863  * \param[in] cursor Cursor to close.
864  *
865  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
866  * record point to the next record.
867  *
868  * \sa \ref DB_Table_select_range, \ref DB_Table_select_all
869  */
870 DBDllExport void
871 DB_Cursor_finish(DB_Table_T table,DB_Cursor_T cursor);
872 
873 #ifdef __cplusplus
874 } /* extern "C" */
875 #endif
876 
877 #endif /* db_api_h */
878 
879 /*ci @} */

RTI Connext DDS Micro Version 2.4.11 Copyright © Mon Jul 23 2018 Real-Time Innovations, Inc