RTI Connext DDS Micro  Version 2.4.8
 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 Create a database table
465  *
466  * \details
467  *
468  * This function creates an empty database table. Every table in the same
469  * database must have a unique name. A table contains fixed size records.
470  * Any memory allocation required by a record must be done outside of the
471  * database. For example, any record that contains pointers or sequences
472  * must be initialized outside of the table itself.
473  *
474  * \param[inout] table Handle to new table. *table must be NULL on input.
475  * \param[in] db Database where the table shall be created.
476  * Cannot be NULL.
477  * \param[in] name Name of the table. Must be unique in the database.
478  * Cannot be NULL.
479  * \param[in] record_size Size in bytes of a record. Must be > 0.
480  * \param[in] compare_func The compare function. Cannot be NULL.
481  * \param[in] property Table properties. Cannot be NULL.
482  *
483  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
484  * the table was successfully created and table contains a handle to
485  * the newly created table.
486  *
487  * \sa \ref DB_Database_delete_table
488  */
489 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
490 DB_Database_create_table(DB_Table_T *table,
491  DB_Database_T db,
492  const char *name,
493  RTI_SIZE_T record_size,
494  DB_IndexCompare_T compare_func,
495  struct DB_TableProperty *property);
496 
497 #ifndef RTI_CERT
498 /*ci
499  * \brief Delete a database table
500  *
501  * \details
502  *
503  * Delete a database table. A database table can only be deleted if it
504  * is empty and there are no outstanding cursors.
505  *
506  * \param[in] db Database to delete table from.
507  * \param[in] table Table to delete.
508  *
509  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
510  * the table was successfully deleted.
511  *
512  * \sa \ref DB_Database_create_table
513  */
514 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
515 DB_Database_delete_table(DB_Database_T db,DB_Table_T table);
516 #endif /* !RTI_CERT */
517 
518 /*************************** Table Functions **********************************/
519 
520 /*ci
521  * \brief Create record in a database table
522  *
523  * \details
524  *
525  * A table can only manage records created from the table. This function
526  * returns an unused record. Note that the record is not initialized. It is
527  * illegal to delete a table with records in use. That is, all records must be
528  * deleted from a table before the table can be deleted.
529  *
530  * \param[in] table Table to create record in.
531  * \param[inout] record Created record. *record must be NULL on input.
532  *
533  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
534  * the record was successfully created and a handle is returned in
535  * record.
536  *
537  * \sa \ref DB_Table_delete_record
538  */
539 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
540 DB_Table_create_record(DB_Table_T table,DB_Record_T *record);
541 
542 /*ci
543  * \brief Insert a record into the table
544  *
545  * \details
546  *
547  * A record becomes available to users of a table only after it is inserted.
548  * If a record is inserted into a cursor selection the cursor is invalidated.
549  *
550  * \param[in] table Table to insert record into.
551  * \param[in] record Record to insert.
552  *
553  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
554  * the record was successfully inserted.
555  *
556  * \sa \ref DB_Table_delete_record
557  *
558  */
559 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
560 DB_Table_insert_record(DB_Table_T table, DB_Record_T record);
561 
562 /*ci
563  * \brief Remove a record from a table
564  *
565  * \details
566  *
567  * Remove a record from the table based on the key. The record is no longer
568  * search-able and it not reusable until deleted with
569  * \ref DB_Table_delete_record.
570  *
571  * \param[in] table Table to remove record from.
572  * \param[out] record Removed record.
573  * \param[in] key The key to search for.
574  *
575  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
576  * the record was removed.
577  *
578  * \sa \ref DB_Table_insert_record
579  *
580  */
581 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
582 DB_Table_remove_record(DB_Table_T table,DB_Record_T *record,DB_Key_T key);
583 
584 /*ci
585  * \brief Delete a record from a table
586  *
587  * \details
588  *
589  * Delete the record from the table. A deleted record will be marked as free
590  * for reuse and may be returned by \ref DB_Table_create_record.
591  *
592  * \param[in] table Table to delete record from.
593  * \param[in] record Record to delete.
594  *
595  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
596  * the record was deleted.
597  *
598  * \sa \ref DB_Table_create_record
599  */
600 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
601 DB_Table_delete_record(DB_Table_T table,DB_Record_T record);
602 
603 /*ci
604  * \brief Delete a record from a table with with a record destructor
605  *
606  * \details
607  *
608  * Delete the record from the table. A deleted record will be marked as free
609  * for reuse and may be returned by \ref DB_Table_create_record. The provided
610  * dtor, if not NULL, is called to finalize the record before it is returned to
611  * for reuse. This is useful for records that use dynamically allocated
612  * keys that are either the primary key or a part of a key for an index.
613  *
614  * \param[in] table Table to delete record from.
615  * \param[in] record Record to delete.
616  * \paran[in] dtor Function pointer to call with record to finalize the
617  * content. See \ref DB_Table_RecordDtor_T for details.
618  *
619  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
620  * the record was deleted.
621  *
622  * \sa \ref DB_Table_create_record
623  */
624 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
625 DB_Table_delete_record_w_dtor(DB_Table_T table,DB_Record_T record,
626  DB_Table_RecordDtor_T dtor);
627 
628 /*ci
629  * \brief Create a new index for a table
630  *
631  * \details
632  *
633  * A table always has a default index based on the compare function passed
634  * to \ref DB_Database_create_table function. It is however possible to create
635  * a subset of the table or sort the records in a different order by creating
636  * a new index. Note that it is illegal to delete a table with indices
637  * (except for the default).
638  *
639  * \param[in] table Table to create index for.
640  * \param[inout] index Handle to index, *index must be NULL on input.
641  * \param[in] compare_func Compare function.
642  * \param[in] property The index property.
643  *
644  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
645  * the index was successfully created and a handle is available in the
646  * index output parameter.
647  *
648  * \sa \ref DB_Table_delete_index
649  *
650  */
651 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
652 DB_Table_create_index(DB_Table_T table,
653  DB_Index_T *index,
654  DB_IndexCompare_T compare_func,
655  const struct DB_IndexProperty *const property);
656 /*ci
657  * \brief Delete an index
658  *
659  * \details
660  *
661  * Delete an index previously created with \ref DB_Table_create_index
662  *
663  * \param[in] table Table to delete index from.
664  * \param[in] index Handle to index.
665  *
666  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
667  * the index was successfully deleted.
668  *
669  * \sa \ref DB_Table_delete_index
670  *
671  */
672 #ifndef RTI_CERT
673 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
674 DB_Table_delete_index(DB_Table_T table,DB_Index_T index);
675 #endif /* !RTI_CERT */
676 
677 /*ci
678  * \brief Select all the records from an index
679  *
680  * \details
681  *
682  * Create cursor to iterate over all the records in an index. The
683  * DB_Table_select_all_default function uses the default index which will return
684  * all the records in the table. The records are ordered based on the compare
685  * function for the index used for the selection.
686  *
687  * Note that the database should be locked while iterating over a cursor.
688  *
689  * \param[in] table Table to select records from.
690  * \param[in] index Index to return records from.
691  * \param[out] cursor Cursor to iterate over result set.
692  *
693  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
694  * a cursor was successfully created and a handle is available in the
695  * cursor output parameter.
696  *
697  * \sa \ref DB_Table_select_match, \ref DB_Table_select_range
698  *
699  */
700 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
701 DB_Table_select_all(DB_Table_T table,DB_Index_T index,DB_Cursor_T *cursor);
702 
703 
704 /*ci
705  * \brief Select all the records from the default index
706  *
707  * \details
708  *
709  * Create cursor to iterate over all the records in the default index.
710  * Note that the database should be locked while iterating over a cursor.
711  *
712  * \param[in] table Table to iterate over.
713  * \param[out] cursor Cursor to iterate over result set.
714  *
715  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
716  * a cursor was successfully created and a handle available in the
717  * cursor output parameter.
718  *
719  * \sa \ref DB_Table_select_match, \ref DB_Table_select_range
720  *
721  */
722 #define DB_Table_select_all_default(table_,eh_) \
723  DB_Table_select_all(table_,DB_TABLE_DEFAULT_INDEX,eh_)
724 
725 /*ci
726  * \brief Search for a record in an index
727  *
728  * \details
729  *
730  * Search for a record with a matching key in an index. If a match is found the
731  * record is returned in the record parameter. If none are found
732  * DB_RETCODE_NO_DATA is returned. NOTE: The output parameter is only updated
733  * on success. If no record is found the output argument is _not_ updated.
734  *
735  * \param[in] table Table to search in.
736  * \param[in] index Index to return record from.
737  * \param[out] record Updated with matching record if it is found.
738  * \param[in] key Key to search for.
739  *
740  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
741  * record points to the matching record.
742  *
743  * \sa \ref DB_Table_select_all, \ref DB_Table_select_range
744  *
745  */
746 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
747 DB_Table_select_match(DB_Table_T table,DB_Index_T index,
748  DB_Record_T *record,DB_Key_T key);
749 
750 /*ci
751  * \brief Select all the records from an index that lies within a range
752  *
753  * \details
754  *
755  * Select all records between [lower,upper] keys.
756  *
757  * \param[in] table Table to delete index from
758  * \param[in] index Index to return records from
759  * \param[out] cursor Cursor to the result set
760  * \param[in] lower Lower key to search for
761  * \param[in] upper Upper key to search for
762  *
763  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
764  * cursor holds records which lies within the [lower,upper] range of
765  * keys.
766  *
767  * \sa \ref DB_Table_select_all, \ref DB_Table_select_match
768  *
769  */
770 SHOULD_CHECK_RETURN DBDllExport DB_ReturnCode_T
771 DB_Table_select_range(DB_Table_T table,DB_Index_T index,
772  DB_Cursor_T *cursor,
773  DB_Key_T lower,DB_Key_T upper);
774 
775 /*ci
776  * \brief Return the name of a table
777  *
778  * \details
779  *
780  * Return the name of a table
781  *
782  * \param[in] table Table to return name for, cannot be NULL.
783  *
784  * \return pointer to name of table in ASCIIZ format
785  *
786  * \sa
787  */
788 DBDllExport const char*
789 DB_Table_get_name(DB_Table_T table);
790 
791 /*ci
792  * \brief Return the number of records in a result set for a cursor
793  *
794  * \param[in] cursor Cursor to result set.
795  * \param[out] count Number of records the cursor can iterate over.
796  *
797  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
798  * count contains the number of records.
799  *
800  * \sa \ref DB_Table_select_range, \ref DB_Table_select_all
801  */
802 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
803 DB_Cursor_get_count(DB_Cursor_T cursor,RTI_INT32 *count);
804 
805 /*ci
806  * \brief Return the next record the cursor is pointing to
807  *
808  * \details
809  *
810  * This function returns the next record the cursor is pointing to in its
811  * result set. When a cursor is first created it does not point to a record,
812  * but upon the first call to \ref DB_Cursor_get_next it points to the first
813  * record (if any). Note that a cursor cannot be iterated over again, a new
814  * cursor must be created.
815  *
816  * \param[in] handle Cursor with a result set.
817  * \param[out] record Pointer to the next record.
818  *
819  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
820  * record points to the next record.
821  *
822  * \sa \ref DB_Table_select_range, \ref DB_Table_select_all,
823  * \ref DB_Cursor_finish
824  */
825 MUST_CHECK_RETURN DBDllExport DB_ReturnCode_T
826 DB_Cursor_get_next(DB_Cursor_T handle, DB_Record_T *record);
827 
828 /*ci
829  * \brief Close a cursor
830  *
831  * \details
832  *
833  * This function closes a cursor and returns it to the table. Note that it
834  * is illegal to delete a table if there are open cursors.
835  *
836  * \param[in] table Table the cursor should be returned to. Must be the
837  * same table the cursor was created from. Note that the
838  * caller is responsible to make sure this is the case.
839  *
840  * \param[in] cursor Cursor to close.
841  *
842  * \return One of \ref DB_ReturnCode_T is returned. If DB_RETCODE_OK is returned
843  * record point to the next record.
844  *
845  * \sa \ref DB_Table_select_range, \ref DB_Table_select_all
846  */
847 DBDllExport void
848 DB_Cursor_finish(DB_Table_T table,DB_Cursor_T cursor);
849 
850 #ifdef __cplusplus
851 } /* extern "C" */
852 #endif
853 
854 #endif /* db_api_h */
855 
856 /*ci @} */

RTI Connext DDS Micro Version 2.4.8 Copyright © Tue Apr 12 2016 Real-Time Innovations, Inc