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

RTI Connext DDS Micro Version 2.4.6 Copyright © Sun Jan 24 2016 Real-Time Innovations, Inc