RTI Connext DDS Micro  Version 2.4.11
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
reda_sequence.h
1 /*
2  * FILE: reda_sequence.h - Sequence API
3  *
4  * Copyright 2008-2016 Real-Time Innovations, Inc.
5  *
6  * No duplications, whole or partial, manual or electronic, may be made
7  * without express written permission. Any such copies, or
8  * revisions thereof, must display this notice unaltered.
9  * This code contains trade secrets of Real-Time Innovations, Inc.
10  *
11  * Modification History
12  * --------------------
13  * 10feb2016,tk MICRO-1530 Unified REDA_StringSeq, CDR_StringSeq, and DDS_StringSeq
14  * 17may2015,as MICRO-1193 Refactoring of Sequence API levels
15  * 19jul2013,as Added support for C++
16  * 03jun2013,kaj MICRO-502 support for string sequences req. max string length
17  * 20oct2008,tk Written
18  */
19 /*ci
20  * \file
21  *
22  * \brief The REDA Sequence API provides a strongly typed vector API.
23  *
24  * \defgroup REDASequenceClass REDA Sequence
25  * \ingroup REDAModule
26  *
27  * \details
28  *
29  * The REDA sequence API provides a strongly typed API to manage variable
30  * size vectors/arrays of the same type. The typing is achieved by encapsulating
31  * generic function in a typed wrapper using macro's. The documentation
32  * is for the generic functions.
33  */
34 #ifndef reda_sequence_h
35 #define reda_sequence_h
36 
37 /*ci
38  * \addtogroup REDASequenceClass
39  * @{
40  */
41 #ifndef reda_dll_h
42 #include "reda/reda_dll.h"
43 #endif
44 #ifndef osapi_types_h
45 #include "osapi/osapi_types.h"
46 #endif
47 
48 #ifdef __cplusplus
49 extern "C"
50 {
51 #endif
52 
53 /*\ci
54  * \brief Do not define a typed API
55  */
56 #define REDA_SEQUENCE_API_UNTYPED 0
57 
58 /*\ci
59  * \brief Define minimal interface available to every sequence type
60  *
61  * \details
62  * The following typed sequence functions are defined for every sequence type:
63  * TSeq_initialize
64  * TSeq_get_maximum
65  * TSeq_set_maximum
66  * TSeq_get_length
67  * TSeq_set_length
68  * TSeq_get_reference
69  * TSeq_finalize
70  */
71 #define REDA_SEQUENCE_API_BASIC 1
72 
73 /*\ci
74  * \brief Define the full typed sequence API.
75  *
76  * \details
77  * The BASIC API plus:
78  * TSeq_copy
79  * TSeq_is_equal
80  * TSeq_loan_contiguous
81  * TSeq_loan_discontiguous
82  * TSeq_has_ownership
83  * TSeq_has_discontiguous_buffer
84  * TSeq_get_buffer
85  * TSeq_set_buffer
86  * TSeq_unloan
87  * TSeq_set_token
88  * TSeq_get_token
89  */
90 #define REDA_SEQUENCE_API_FULL 2
91 
92 /*ci The default sequence API for core types unless a different one is specified
93  * when a sequence is declared/defined
94  */
95 #ifndef REDA_SEQUENCE_API_DEFAULT
96 #ifndef RTI_CERT
97 #define REDA_SEQUENCE_API_DEFAULT REDA_SEQUENCE_API_FULL
98 #else
99 #define REDA_SEQUENCE_API_DEFAULT REDA_SEQUENCE_API_BASIC
100 #endif
101 #else
102 #if REDA_SEQUENCE_API_DEFAULT < REDA_SEQUENCE_API_BASIC
103 #error "REDA_SEQUENCE_API_DEFAULT must be at least REDA_SEQUENCE_API_BASIC"
104 #endif
105 #endif
106 
107 /*ci The default sequence API for user types unless a one is specified
108  * when a sequence is declared/defined
109  */
110 #ifndef REDA_SEQUENCE_API_USER_DEFAULT
111 #ifndef RTI_CERT
112 #define REDA_SEQUENCE_API_USER_DEFAULT REDA_SEQUENCE_API_FULL
113 #else
114 #define REDA_SEQUENCE_API_USER_DEFAULT REDA_SEQUENCE_API_BASIC
115 #endif
116 #else
117 #if REDA_SEQUENCE_API_USER_DEFAULT < REDA_SEQUENCE_API_BASIC
118 #error "REDA_SEQUENCE_API_USER_DEFAULT must be at least REDA_SEQUENCE_API_BASIC"
119 #endif
120 #endif
121 
122 /* Initialize a REDA sequence structure for a type */
123 #define REDA_DEFINE_SEQUENCE_INITIALIZER(t_) \
124 { NULL,0,0,sizeof(t_),NULL,NULL,0 }
125 
126 /* Initialize a REDA sequence structure for no type (0 size) */
127 #define REDA_DEFINE_EMPTY_SEQUENCE_INITIALIZER \
128 { NULL,0,0,0,NULL,NULL,0 }
129 
130 /* forward declaration of the REDA_Sequence structure for the API below.
131  * The structure is defined in REDA_Sequence.c
132  */
133 struct REDA_Sequence;
134 
135 /*ci
136  *\brief Internal flag set when sequence is using a loaned buffer.
137  */
138 #define REDA_SEQUENCE_FLAG_LOAN (RTI_UINT8)0x01
139 
140 /*ci
141  *\brief Internal flag set when the sequencebuffer contains pointers to elements
142  */
143 #define REDA_SEQUENCE_FLAG_DISCONTIGUOUS (RTI_UINT8)0x02
144 
145 /*ci
146  *\brief Internal flag set when the sequence buffer contains pointer elements
147  * with memory allocated by set_maximum/ensure_length
148  */
149 #define REDA_SEQUENCE_FLAG_PTR_ALLOCATION (RTI_UINT8)0x04
150 
151 /*ci
152  * \brief Constant passed as max_str_length to indicate that that memory
153  * for the pointer element should be allocated as needed
154  *
155  */
156 #define REDA_SEQUENCE_ELEMENT_ALLOC (0xfffffffeU)
157 
158 /*ci
159  * \brief Constant passed as max_str_length to indicate that that memory
160  * for the pointer element should is already sized and should be
161  * assumed to be sufficiently large as a destination
162  */
163 #define REDA_SEQUENCE_ELEMENT_REPLACE (0xffffffffU)
164 
165 /*ci
166  * \brief Initialize a sequence
167  *
168  * \details
169  *
170  * Initializes a sequence structure based on the element size.
171  * \return RTI_TRUE on success, RTI_FALSE on failure
172  *
173  * \param[in] self Sequence structure to initialize
174  *
175  * \param[in] element_size Size in bytes of the sequence structure
176  *
177  * \sa REDA_Sequence_finalize
178  */
179 MUST_CHECK_RETURN REDADllExport RTI_BOOL
180 REDA_Sequence_initialize(struct REDA_Sequence *self, RTI_INT32 element_size);
181 
182 #ifndef RTI_CERT
183 /*ci
184  * \brief Finalize a sequence
185  *
186  * \details
187  *
188  * Finalize a sequence structure based
189  *
190  * \return RTI_TRUE on success, RTI_FALSE on failure
191  *
192  * \param[in] self Sequence structure to finalize
193  *
194  * \sa REDA_Sequence_initialize
195  */
196 SHOULD_CHECK_RETURN REDADllExport RTI_BOOL
197 REDA_Sequence_finalize(struct REDA_Sequence *self);
198 #endif /* !RTI_CERT */
199 
200 /*ci
201  * \brief Get the current maximum of elements the sequence can store
202  *
203  * \details
204  *
205  * Return the current maximum number of elements a sequence can hold. The
206  * caller must ensure that self is not NULL.
207  *
208  * \param[in] self Sequence to return the maximum number of elements for
209  *
210  * \return maximum number of elements the sequence can hold.
211  *
212  * \sa REDA_Sequence_set_maximum
213  */
214 REDADllExport RTI_INT32
215 REDA_Sequence_get_maximum(const struct REDA_Sequence *self);
216 
217 /*ci
218  * \brief Set the current maximum of elements the sequence can store
219  *
220  * \details
221  *
222  * Set maximum number of elements a sequence can hold. The caller must
223  * ensure that self is not NULL. If new_max is larger than the current
224  * max additional memory is allocated if possible. If new_max is less
225  * than the current maximum memory may be freed.
226  *
227  * \param[in] self Sequence to change
228  * \param[in] new_max The new maximum number of elements the sequence can
229  * hold.
230  * \param[in] copy_content Whether the content of the sequence element should
231  * be copied or not. If copy_content is RTI_FALSE only
232  * the element array is resized, but the content of
233  * each element is not touched. If copy_content is
234  * RTI_TRUE then the content of each element is
235  * copied. This parameter is used by the typed wrapper
236  * functions to manage elements that manage their
237  * own memory, such as string sequences.
238  *
239  * \return RTI_TRUE on success, RTI_FALSE on failure.
240  *
241  * \sa REDA_Sequence_set_maximum
242  */
243 MUST_CHECK_RETURN REDADllExport RTI_BOOL
244 REDA_Sequence_set_maximum(struct REDA_Sequence *self, RTI_INT32 new_max,
245  RTI_BOOL copy_content);
246 
247 /*ci
248  * \brief Get the current number of elements in the sequence
249  *
250  * \details
251  *
252  * Return the current number of elements in the sequence.
253  *
254  * \param[in] self Sequence to return the current number of elements for
255  *
256  * \return Number of elements in the sequence.
257  *
258  * \sa REDA_Sequence_set_length
259  */
260 REDADllExport RTI_INT32
261 REDA_Sequence_get_length(const struct REDA_Sequence *self);
262 
263 /*ci
264  * \brief Set the current number of elements in the sequence
265  *
266  * \details
267  *
268  * Set the current number of elements in the sequence. Note that this function
269  * does not expand the sequence, rather it changes how many of the currently
270  * maximum number of elements are valid. Thus it is illegal to specify
271  * a new_length > get_maximum(self)
272  *
273  * \param[in] self Sequence to set the current number of elements for
274  * \param[in] new_length The number of elements in the sequence
275  *
276  * \return RTI_TRUE if the length was successfully changed, RTI_FALSE otherwise.
277  *
278  * \sa REDA_Sequence_get_length
279  */
280 MUST_CHECK_RETURN REDADllExport RTI_BOOL
281 REDA_Sequence_set_length(struct REDA_Sequence *self, RTI_INT32 new_length);
282 
283 /*ci
284  * \brief Return the underlying buffer holding sequence elements
285  *
286  * \details
287  *
288  * This function returns the underlying buffer holding up to max elements.
289  * It is guaranteed that the buffer is a contiguous memory area of at least
290  * element_size * maximum bytes.
291  *
292  * \param[in] self Sequence to get the current buffer for
293  *
294  * \return Current buffer or NULL if the sequence is not initialized.
295  *
296  * \sa REDA_Sequence_set_buffer
297  */
298 MUST_CHECK_RETURN REDADllExport void*
299 REDA_Sequence_get_buffer(const struct REDA_Sequence *self);
300 
301 /*ci
302  * \brief Set the underlying buffer holding sequence elements
303  *
304  * \details
305  *
306  * This function sets the underlying buffer holding up to max elements.
307  * It is guaranteed that the buffer is a contiguous memory area of at least
308  * element_size * maximum bytes.
309  *
310  * \param[in] self Sequence to set the current buffer for
311  *
312  * \param[in] buffer Buffer with sequence elements
313  *
314  * \return Current buffer or NULL if the sequence is not initialized.
315  *
316  * \sa REDA_Sequence_set_buffer
317  */
318 MUST_CHECK_RETURN REDADllExport RTI_BOOL
319 REDA_Sequence_set_buffer(struct REDA_Sequence *self, void *buffer);
320 
321 /*ci
322  * \brief Return a pointer to an element in the vector
323  *
324  * \details
325  *
326  * This function returns a pointer (reference) to an element in the vector
327  * given an index. The indexing is 0-based. If an index higher than the current
328  * length is specified NULL is returned.
329  *
330  * \param[in] self Sequence to return the element from
331  * \param[in] index Which element to return
332  *
333  * \return A reference to element index is returned, or NULL if the index
334  * is not within the current length.
335  */
336 MUST_CHECK_RETURN REDADllExport void*
337 REDA_Sequence_get_reference(const struct REDA_Sequence *self,RTI_INT32 index);
338 
339 /*ci
340  * \brief Copy the content of one sequence to another
341  *
342  * \details
343  *
344  * This function copies the content of the source sequence to the destination
345  * sequence, expanding the destination sequence if needed. The length of the
346  * destination will be equal to the source after the successful copying.
347  * it is not guaranteed that the maximum length of the two sequences are equal,
348  * only that the destination sequence is at least as large as the source
349  * sequence.
350  *
351  * \param[in] self Sequence to copy to
352  * \param[in] src Sequence to copy from
353  * \param[in] copy_content Whether the content of the sequence element should
354  * be copied or not. If copy_content is RTI_FALSE only
355  * the element array is resized, but the content of
356  * each element is not touched. If copy_content is
357  * RTI_TRUE then the content of each element is
358  * copied. This parameter is used by the typed wrapper
359  * functions to manage elements that manage their
360  * own memory, such as string sequences.
361  *
362  * \return A reference to destination sequence is returned on success, otherwise
363  * NULL is returned.
364  */
365 MUST_CHECK_RETURN REDADllExport struct REDA_Sequence*
366 REDA_Sequence_copy(struct REDA_Sequence *self,
367  const struct REDA_Sequence *src,
368  RTI_BOOL copy_content);
369 
370 /*ci
371  * \brief Compare two sequences
372  *
373  * \details
374  *
375  * Compare two function for equality. Two sequences are considered to be equal
376  * if the sequences are of the same length and the content of each element
377  * in the same position is identical.
378  *
379  * \param[in] left Left side of the comparison
380  * \param[in] right Right side of the comparison
381  * \param[in] compare_content Whether the content of the sequence element should
382  * be compared or not. If compare_content is
383  * RTI_FALSE only the element array sizes are
384  * compared, but the content of
385  * each element is not compared. If compare_content
386  * is RTI_TRUE then the content of each element is
387  * compared. This parameter is used by the typed
388  * wrapper functions to manage elements that manage
389  * their own memory, such as string sequences.
390  *
391  * \return RTI_TRUE if the sequences are equal, RTI_FALSE otherwise.
392  */
393 REDADllExport RTI_BOOL
394 REDA_Sequence_is_equal(const struct REDA_Sequence *left,
395  const struct REDA_Sequence *right,
396  RTI_BOOL compare_content);
397 
398 /*ci
399  * \brief Loan an external, contiguous buffer to a sequence
400  *
401  * \details
402  *
403  * Typically a sequence manages its own memory. However, it is possible to
404  * loan the sequence a buffer of elements. When a sequence is loaning a
405  * buffer it is not allowed to resize it. The caller must first unloan the
406  * sequence and then loan the sequence a different buffer. In a contiguous
407  * buffer it is assumed that each element is contained in the buffer. It
408  * is not legal to loan a buffer to a sequence currently managing its own
409  * element buffer. In this case the sequence must first be finalized.
410  *
411  * \param[in] self Sequence to loan buffer to
412  * \param[in] buffer Buffer to loan
413  * \param[in] new_length The number of valid elements in the buffer
414  * \param[in] new_max The maximum number of elements the buffer can hold
415  *
416  * \return RTI_TRUE is returned if the loan is successful, RTI_FALSE otherwise
417  */
418 MUST_CHECK_RETURN REDADllExport RTI_BOOL
419 REDA_Sequence_loan_contiguous(struct REDA_Sequence *self, void *buffer,
420  RTI_INT32 new_length, RTI_INT32 new_max);
421 
422 /*ci
423  * \brief Loan an external, discontiguous buffer to a sequence
424  *
425  * \details
426  *
427  * Typically a sequence manages its own memory. However, it is possible to
428  * loan the sequence a buffer of elements. When a sequence is loaning a
429  * buffer it is not allowed to resize it. The caller must first unloan the
430  * sequence and then loan the sequence a different buffer. In a discontiguous
431  * buffer it is assumed that each element is a reference to the actual element
432  * contained in the buffer. It is not legal to loan a buffer to a sequence
433  * currently managing its own element buffer. In this case the sequence must
434  * first be finalized.
435  *
436  * \param[in] self Sequence to loan buffer to
437  * \param[in] buffer Buffer to loan
438  * \param[in] new_length The number of valid elements in the buffer
439  * \param[in] new_max The maximum number of elements the buffer can hold
440  *
441  * \return RTI_TRUE is returned if the loan is successful, RTI_FALSE otherwise
442  */
443 MUST_CHECK_RETURN REDADllExport RTI_BOOL
444 REDA_Sequence_loan_discontiguous(struct REDA_Sequence *self, void *buffer,
445  RTI_INT32 new_length, RTI_INT32 new_max);
446 /*ci
447  * \brief Remove a loan of an external buffer to a sequence
448  *
449  * \details
450  *
451  * Remove a previously loaned buffer from a sequence.
452  *
453  * \param[in] self Sequence to unloan the buffer from
454  *
455  * \return RTI_TRUE is returned if the unloan is successful, RTI_FALSE otherwise
456  *
457  * \sa \ref REDA_Sequence_loan_discontiguous, \ref REDA_Sequence_loan_contiguous
458  */
459 MUST_CHECK_RETURN REDADllExport RTI_BOOL
460 REDA_Sequence_unloan(struct REDA_Sequence *self);
461 
462 /*ci
463  * \brief Check if a sequence owns the current element buffer or not
464  *
465  * \details
466  *
467  * Check if a sequence owns the current element buffer or not
468  *
469  * \param[in] self Sequence to check ownership for
470  *
471  * \return RTI_TRUE if the sequence owns the buffer, RTI_FALSE if not
472  *
473  * \sa \ref REDA_Sequence_loan_discontiguous, \ref REDA_Sequence_loan_contiguous
474  */
475 REDADllExport RTI_BOOL
476 REDA_Sequence_has_ownership(const struct REDA_Sequence *self);
477 
478 /*ci
479  * \brief Check if a sequence uses a contiguous or discontinuous buffer
480  *
481  * \details
482  *
483  * Check if a sequence uses a contiguous or discontinuous buffer
484  *
485  * \param[in] self Sequence to check ownership for
486  *
487  * \return RTI_TRUE if the sequence is contiguous, RTI_FALSE if not
488  *
489  * \sa \ref REDA_Sequence_loan_discontiguous
490  */
491 REDADllExport RTI_BOOL
492 REDA_Sequence_has_discontiguous_buffer(const struct REDA_Sequence *self);
493 
494 /*ci
495  * \brief Set a token on a sequence
496  *
497  * \details
498  * A token is an opaque pointer stored in the sequence. It has no meaning
499  * to the sequence and is not considered part of the content.
500  *
501  * \param[in] self Sequence to get the current buffer for
502  * \param[in] token1 The first token to associate with the sequence
503  * \param[in] token2 The second token to associate with the sequence
504  *
505  * \sa REDA_Sequence_get_token
506  */
507 REDADllExport void
508 REDA_Sequence_set_token(struct REDA_Sequence *self,void *token1,void *token2);
509 
510 /*ci
511  * \brief Get the token from a sequence
512  *
513  * \details
514  * A token is an opaque pointer stored in the sequence. It has no meaning
515  * to the sequence and is not considered part of the content.
516  *
517  * \param[in] self Sequence to get the current buffer for
518  * \param[out] token1 The first token associated with the sequence
519  * \param[out] token2 The second token associated with the sequence
520  *
521  * \sa REDA_Sequence_set_token
522  */
523 REDADllExport void
524 REDA_Sequence_get_token(const struct REDA_Sequence *self,void **token1,void **token2);
525 
526 #ifdef __cplusplus
527 } /* extern "C" */
528 #endif
529 
530 #endif /* reda_sequence_h */
531 
532 /*ci @} */

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