LibreOfficeDev
LibreOfficeDev 24.8 SDK C/C++ API Reference
types.h
Go to the documentation of this file.
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3  * This file is part of the LibreOffice project.
4  *
5  * This Source Code Form is subject to the terms of the Mozilla Public
6  * License, v. 2.0. If a copy of the MPL was not distributed with this
7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8  *
9  * This file incorporates work covered by the following license notice:
10  *
11  * Licensed to the Apache Software Foundation (ASF) under one or more
12  * contributor license agreements. See the NOTICE file distributed
13  * with this work for additional information regarding copyright
14  * ownership. The ASF licenses this file to you under the Apache
15  * License, Version 2.0 (the "License"); you may not use this file
16  * except in compliance with the License. You may obtain a copy of
17  * the License at http://www.apache.org/licenses/LICENSE-2.0 .
18  */
19 
20 /*
21  * This file is part of LibreOffice published API.
22  */
23 
24 #ifndef INCLUDED_SAL_TYPES_H
25 #define INCLUDED_SAL_TYPES_H
26 
27 #include "sal/config.h"
28 
29 #include <stddef.h>
30 
31 #include "sal/macros.h"
32 #include "sal/typesizes.h"
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 typedef unsigned char sal_Bool;
39 # define sal_False ((sal_Bool)0)
40 # define sal_True ((sal_Bool)1)
41 
42 /* char is assumed to always be 1 byte long */
43 typedef signed char sal_Int8;
44 typedef unsigned char sal_uInt8;
45 
46 #if SAL_TYPES_SIZEOFSHORT == 2
47  typedef signed short sal_Int16;
48  typedef unsigned short sal_uInt16;
49 #else
50  #error "Could not find 16-bit type, add support for your architecture"
51 #endif
52 
53 #if SAL_TYPES_SIZEOFLONG == 4
54  typedef signed long sal_Int32;
55  typedef unsigned long sal_uInt32;
56  #define SAL_PRIdINT32 "ld"
57  #define SAL_PRIuUINT32 "lu"
58  #define SAL_PRIxUINT32 "lx"
59  #define SAL_PRIXUINT32 "lX"
60 #elif SAL_TYPES_SIZEOFINT == 4
61  typedef signed int sal_Int32;
62  typedef unsigned int sal_uInt32;
63  #define SAL_PRIdINT32 "d"
64  #define SAL_PRIuUINT32 "u"
65  #define SAL_PRIxUINT32 "x"
66  #define SAL_PRIXUINT32 "X"
67 #else
68  #error "Could not find 32-bit type, add support for your architecture"
69 #endif
70 
71 #ifdef _MSC_VER
72  typedef __int64 sal_Int64;
73  typedef unsigned __int64 sal_uInt64;
74 
75  /* The following are macros that will add the 64 bit constant suffix. */
76  #define SAL_CONST_INT64(x) x##i64
77  #define SAL_CONST_UINT64(x) x##ui64
78 
79  #define SAL_PRIdINT64 "I64d"
80  #define SAL_PRIuUINT64 "I64u"
81  #define SAL_PRIxUINT64 "I64x"
82  #define SAL_PRIXUINT64 "I64X"
83 #elif defined (__GNUC__)
84  #if SAL_TYPES_SIZEOFLONG == 8
85  typedef signed long int sal_Int64;
86  typedef unsigned long int sal_uInt64;
87 
88 
89  /* The following are macros that will add the 64 bit constant suffix. */
90  #define SAL_CONST_INT64(x) x##l
91  #define SAL_CONST_UINT64(x) x##ul
92 
93  #define SAL_PRIdINT64 "ld"
94  #define SAL_PRIuUINT64 "lu"
95  #define SAL_PRIxUINT64 "lx"
96  #define SAL_PRIXUINT64 "lX"
97  #elif SAL_TYPES_SIZEOFLONGLONG == 8
98  typedef signed long long sal_Int64;
99  typedef unsigned long long sal_uInt64;
100 
101  /* The following are macros that will add the 64 bit constant suffix. */
102  #define SAL_CONST_INT64(x) x##ll
103  #define SAL_CONST_UINT64(x) x##ull
104 
105  #define SAL_PRIdINT64 "lld"
106  #define SAL_PRIuUINT64 "llu"
107  #define SAL_PRIxUINT64 "llx"
108  #define SAL_PRIXUINT64 "llX"
109  #else
110  #error "Could not find 64-bit type, add support for your architecture"
111  #endif
112 #else
113  #error "Please define the 64-bit types for your architecture/compiler in include/sal/types.h"
114 #endif
115 
116 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus
117  #define SAL_UNICODE_NOTEQUAL_WCHAR_T
118  typedef char16_t sal_Unicode;
119 #elif defined(_WIN32)
120  typedef wchar_t sal_Unicode;
121 #else
122  #define SAL_UNICODE_NOTEQUAL_WCHAR_T
123  typedef sal_uInt16 sal_Unicode;
124 #endif
125 
126 typedef void * sal_Handle;
127 
128 /* sal_Size should currently be the native width of the platform */
129 #if SAL_TYPES_SIZEOFPOINTER == 4
130  typedef sal_uInt32 sal_Size;
131  typedef sal_Int32 sal_sSize;
132 #elif SAL_TYPES_SIZEOFPOINTER == 8
133  typedef sal_uInt64 sal_Size;
134  typedef sal_Int64 sal_sSize;
135 #else
136  #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
137 #endif
138 
139 /* sal_PtrDiff holds the result of a pointer subtraction */
140 #if SAL_TYPES_SIZEOFPOINTER == 4
141  typedef sal_Int32 sal_PtrDiff;
142 #elif SAL_TYPES_SIZEOFPOINTER == 8
143  typedef sal_Int64 sal_PtrDiff;
144 #else
145  #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
146 #endif
147 
148 /* printf-style conversion specification length modifiers for size_t and
149  ptrdiff_t (most platforms support C99, MSC has its own extension) */
150 #if defined(_MSC_VER)
151  #define SAL_PRI_SIZET "I"
152  #define SAL_PRI_PTRDIFFT "I"
153 #else
154  #define SAL_PRI_SIZET "z"
155  #define SAL_PRI_PTRDIFFT "t"
156 #endif
157 
158 /* sal_IntPtr, sal_uIntPtr are integer types designed to hold pointers so that any valid
159  * pointer to void can be converted to this type and back to a pointer to void and the
160  * result will compare to the original pointer */
161 #if SAL_TYPES_SIZEOFPOINTER == 4
162  typedef sal_Int32 sal_IntPtr;
163  typedef sal_uInt32 sal_uIntPtr;
164  #define SAL_PRIdINTPTR SAL_PRIdINT32
165  #define SAL_PRIuUINTPTR SAL_PRIuUINT32
166  #define SAL_PRIxUINTPTR SAL_PRIxUINT32
167  #define SAL_PRIXUINTPTR SAL_PRIXUINT32
168 #elif SAL_TYPES_SIZEOFPOINTER == 8
169  typedef sal_Int64 sal_IntPtr;
170  typedef sal_uInt64 sal_uIntPtr;
171  #define SAL_PRIdINTPTR SAL_PRIdINT64
172  #define SAL_PRIuUINTPTR SAL_PRIuUINT64
173  #define SAL_PRIxUINTPTR SAL_PRIxUINT64
174  #define SAL_PRIXUINTPTR SAL_PRIXUINT64
175 #else
176  #error "Please make sure SAL_TYPES_SIZEOFPOINTER is defined for your architecture/compiler"
177 #endif
178 
179 /* The following SAL_MIN_INTn defines codify the assumption that the signed
180  * sal_Int types use two's complement representation. Defining them as
181  * "-0x7F... - 1" instead of as "-0x80..." prevents warnings about applying the
182  * unary minus operator to unsigned quantities.
183  */
184 #define SAL_MIN_INT8 ((sal_Int8) (-0x7F - 1))
185 #define SAL_MAX_INT8 ((sal_Int8) 0x7F)
186 #define SAL_MAX_UINT8 ((sal_uInt8) 0xFF)
187 #define SAL_MIN_INT16 ((sal_Int16) (-0x7FFF - 1))
188 #define SAL_MAX_INT16 ((sal_Int16) 0x7FFF)
189 #define SAL_MAX_UINT16 ((sal_uInt16) 0xFFFF)
190 #define SAL_MIN_INT32 ((sal_Int32) (-0x7FFFFFFF - 1))
191 #define SAL_MAX_INT32 ((sal_Int32) 0x7FFFFFFF)
192 #define SAL_MAX_UINT32 ((sal_uInt32) 0xFFFFFFFF)
193 #define SAL_MIN_INT64 ((sal_Int64) (SAL_CONST_INT64(-0x7FFFFFFFFFFFFFFF) - 1))
194 #define SAL_MAX_INT64 ((sal_Int64) SAL_CONST_INT64(0x7FFFFFFFFFFFFFFF))
195 #define SAL_MAX_UINT64 ((sal_uInt64) SAL_CONST_UINT64(0xFFFFFFFFFFFFFFFF))
196 
197 #if SAL_TYPES_SIZEOFPOINTER == 4
198 #define SAL_MAX_SSIZE SAL_MAX_INT32
199 #define SAL_MAX_SIZE SAL_MAX_UINT32
200 #elif SAL_TYPES_SIZEOFPOINTER == 8
201 #define SAL_MAX_SSIZE SAL_MAX_INT64
202 #define SAL_MAX_SIZE SAL_MAX_UINT64
203 #endif
204 
205 #define SAL_MAX_ENUM 0x7fffffff
206 
207 #if defined(_MSC_VER)
208 # define SAL_DLLPUBLIC_EXPORT __declspec(dllexport)
209 # define SAL_JNI_EXPORT __declspec(dllexport)
210 # define SAL_DLLPUBLIC_IMPORT __declspec(dllimport)
211 # define SAL_DLLPRIVATE
212 # define SAL_DLLPUBLIC_TEMPLATE
213 # define SAL_DLLPUBLIC_RTTI
214 # define SAL_CALL __cdecl
215 #elif defined SAL_UNX
216 # if defined(__GNUC__)
217 # if defined(DISABLE_DYNLOADING)
218 # define SAL_DLLPUBLIC_EXPORT __attribute__ ((visibility("hidden")))
219 # define SAL_JNI_EXPORT __attribute__ ((visibility("default")))
220 # define SAL_DLLPUBLIC_IMPORT __attribute__ ((visibility("hidden")))
221 # define SAL_DLLPRIVATE __attribute__ ((visibility("hidden")))
222 # define SAL_DLLPUBLIC_TEMPLATE __attribute__ ((visibility("hidden")))
223 # define SAL_DLLPUBLIC_RTTI __attribute__ ((visibility("default")))
224 # else
225 # define SAL_DLLPUBLIC_EXPORT __attribute__ ((visibility("default")))
226 # define SAL_JNI_EXPORT __attribute__ ((visibility("default")))
227 # define SAL_DLLPUBLIC_IMPORT __attribute__ ((visibility("default")))
228 # define SAL_DLLPRIVATE __attribute__ ((visibility("hidden")))
229 # define SAL_DLLPUBLIC_TEMPLATE __attribute__ ((visibility("default")))
230 # if defined __clang__
231 # if __has_attribute(type_visibility)
232 # define SAL_DLLPUBLIC_RTTI __attribute__ ((type_visibility("default")))
233 # else
234 # define SAL_DLLPUBLIC_RTTI __attribute__ ((visibility("default")))
235 # endif
236 # else
237 // GCC does not have currently have equivalent functionality to clang's type_visibility
238 // but I have a feature request for that at https://gcc.gnu.org/bugzilla/show_bug.cgi?id=113958
239 // Until that is implemented, just make the whole class visible, which is what I would need to
240 // do anyhow if something wants to import the typeinfo symbol.
241 # define SAL_DLLPUBLIC_RTTI __attribute__ ((visibility("default")))
242 # endif
243 # endif
244 # else
245 # define SAL_DLLPUBLIC_EXPORT
246 # define SAL_JNI_EXPORT
247 # define SAL_DLLPUBLIC_IMPORT
248 # define SAL_DLLPRIVATE
249 # define SAL_DLLPUBLIC_TEMPLATE
250 # define SAL_DLLPUBLIC_RTTI
251 # endif
252 # define SAL_CALL
253 #else
254 # error("unknown platform")
255 #endif
256 
263 #if defined(__GNUC__)
264 # if defined(DISABLE_DYNLOADING)
265 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT __attribute__((visibility("default")))
266 # else
267 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT SAL_DLLPUBLIC_EXPORT
268 # endif
269 # define SAL_EXCEPTION_DLLPRIVATE SAL_DLLPRIVATE
270 #else
271 # define SAL_EXCEPTION_DLLPUBLIC_EXPORT
272 # define SAL_EXCEPTION_DLLPRIVATE
273 #endif
274 
281 #if defined LIBO_INTERNAL_ONLY && defined __cplusplus
282 #define SAL_WARN_UNUSED_RESULT [[nodiscard]]
283 #elif (defined __GNUC__ \
284  && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 1))) \
285  || defined __clang__
286 # define SAL_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
287 #else
288 # define SAL_WARN_UNUSED_RESULT
289 #endif
290 
297 #ifdef _MSC_VER
298 # define SAL_RET_MAYBENULL _Ret_maybenull_
299 #else
300 # define SAL_RET_MAYBENULL
301 #endif
302 
303 
308 #ifdef _MSC_VER
309 # define SAL_NO_VTABLE __declspec(novtable)
310 #else
311 # define SAL_NO_VTABLE
312 #endif
313 
314 #ifdef _WIN32
315 # pragma pack(push, 8)
316 #endif
317 
320 typedef struct _sal_Sequence
321 {
324  sal_Int32 nRefCount;
327  sal_Int32 nElements;
330  char elements[1];
331 } sal_Sequence;
332 
333 #define SAL_SEQUENCE_HEADER_SIZE ((sal_Size) offsetof(sal_Sequence,elements))
334 
335 #if defined( _WIN32)
336 #pragma pack(pop)
337 #endif
338 
339 #ifdef __cplusplus
340 }
341 #endif /* __cplusplus */
342 
347 #if defined __cplusplus
348 #if __cplusplus >= 201103L
349 #define SAL_THROW_EXTERN_C() noexcept
350 #else
351 #define SAL_THROW_EXTERN_C() throw ()
352 #endif
353 #else
354 #define SAL_THROW_EXTERN_C()
355 #endif
356 
357 #ifdef __cplusplus
358 
363 #if defined(LIBO_INTERNAL_ONLY) && defined(__COVERITY__)
364 # define COVERITY_NOEXCEPT_FALSE noexcept(false)
365 #else
366 # define COVERITY_NOEXCEPT_FALSE
367 #endif
368 
370 {
374 };
375 
376 namespace com { namespace sun { namespace star { } } }
377 
382 namespace css = ::com::sun::star;
383 
392 #if defined LIBO_INTERNAL_ONLY
393 #define SAL_DELETED_FUNCTION = delete
394 #else
395 #define SAL_DELETED_FUNCTION
396 #endif
397 
405 #if defined LIBO_INTERNAL_ONLY
406 #define SAL_OVERRIDE override
407 #else
408 #define SAL_OVERRIDE
409 #endif
410 
418 #if defined LIBO_INTERNAL_ONLY
419 #define SAL_CONSTEXPR constexpr
420 #else
421 #define SAL_CONSTEXPR
422 #endif
423 
430 #if __cplusplus >= 201103L
431 #define SAL_NOEXCEPT noexcept
432 #else
433 #define SAL_NOEXCEPT throw ()
434 #endif
435 
436 #endif /* __cplusplus */
437 
438 #ifdef __cplusplus
439 
440 namespace sal {
441 
453 template< typename T1, typename T2 > inline T1 static_int_cast(T2 n) {
454  return static_cast< T1 >(n);
455 }
456 
457 }
458 
459 #else /* __cplusplus */
460 
473 #define SAL_INT_CAST(type, expr) ((type) (expr))
474 
475 #endif /* __cplusplus */
476 
482 #if defined __GNUC__ || defined __clang__
483 #if defined LIBO_INTERNAL_ONLY
484 # define SAL_DEPRECATED(message) __attribute__((deprecated(message)))
485 #else
486 # define SAL_DEPRECATED(message) __attribute__((deprecated))
487 #endif
488 #elif defined(_MSC_VER)
489 # define SAL_DEPRECATED(message) __declspec(deprecated(message))
490 #else
491 # define SAL_DEPRECATED(message)
492 #endif
493 
505 #ifdef LIBO_INTERNAL_ONLY
506 # define SAL_DEPRECATED_INTERNAL(message)
507 #else
508 # define SAL_DEPRECATED_INTERNAL(message) SAL_DEPRECATED(message)
509 #endif
510 
518 #if defined LIBO_INTERNAL_ONLY && defined __GNUC__
519 #define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
520  _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic push)) \
521  _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic ignored "-Wdeprecated-declarations"))
522 #define SAL_WNODEPRECATED_DECLARATIONS_POP \
523  _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic pop))
524 #elif defined LIBO_INTERNAL_ONLY && defined _MSC_VER
525 #define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
526  _Pragma(SAL_STRINGIFY_ARG(warning(push))) \
527  _Pragma(SAL_STRINGIFY_ARG(warning(disable : 4996)))
528 #define SAL_WNODEPRECATED_DECLARATIONS_POP \
529  _Pragma(SAL_STRINGIFY_ARG(warning(pop)))
530 #else
531 # define SAL_WNODEPRECATED_DECLARATIONS_PUSH
532 # define SAL_WNODEPRECATED_DECLARATIONS_POP
533 #endif
534 
551 #ifdef _MSC_VER
552 #define SAL_WNOUNREACHABLE_CODE_PUSH \
553  __pragma(warning(push)) \
554  __pragma(warning(disable:4702)) \
555  __pragma(warning(disable:4722))
556 #define SAL_WNOUNREACHABLE_CODE_POP \
557  __pragma(warning(pop))
558 #else
559 /* Add definitions for GCC and Clang if needed */
560 #define SAL_WNOUNREACHABLE_CODE_PUSH
561 #define SAL_WNOUNREACHABLE_CODE_POP
562 #endif
563 
587 #if defined __cplusplus
588 #if defined __GNUC__ || defined __clang__
589 #define SAL_UNUSED_PARAMETER __attribute__ ((unused))
590 #else
591 #define SAL_UNUSED_PARAMETER
592 #endif
593 #endif
594 
607 #if defined LIBO_INTERNAL_ONLY && (defined __GNUC__ || defined __clang__)
608 #define SAL_WARN_UNUSED __attribute__((warn_unused))
609 #else
610 #define SAL_WARN_UNUSED
611 #endif
612 
614 
615 #if defined __GNUC__ || defined __clang__
616 // Macro to try to catch and warn on assignments inside expr.
617 # define SAL_DETAIL_BOOLEAN_EXPR(expr) \
618  __extension__ ({ \
619  int sal_boolean_var_; \
620  if (expr) \
621  sal_boolean_var_ = 1; \
622  else \
623  sal_boolean_var_ = 0; \
624  sal_boolean_var_; \
625  })
626 
637 # define SAL_LIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 1)
638 
649 # define SAL_UNLIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 0)
650 
662 # define SAL_HOT __attribute__((hot))
663 
677 # define SAL_COLD __attribute__((cold))
678 #else
679 # define SAL_LIKELY(expr) (expr)
680 # define SAL_UNLIKELY(expr) (expr)
681 # define SAL_HOT
682 # define SAL_COLD
683 #endif
684 
686 
688 
697 #ifndef __has_attribute
698 #define __has_attribute(x) 0
699 #endif
700 
701 #if defined LIBO_INTERNAL_ONLY && ((defined __GNUC__ && !defined __clang__) || (defined __clang__ && __has_attribute(returns_nonnull)))
702 #define SAL_RETURNS_NONNULL __attribute__((returns_nonnull))
703 #else
704 #define SAL_RETURNS_NONNULL
705 #endif
706 
708 #if defined LIBO_INTERNAL_ONLY
709 // An annotation mechanism used by some loplugins. The id argument must be an ordinary string
710 // literal. For Clang, this expands to a clang::annotate attribute with an annotation consisting of
711 // the concatenation of a "loplugin:" prefix and the given id suffix. For non-Clang, this expands
712 // to nothing to avoid e.g. -Wattributes from GCC's -Wall.
713 #if defined __clang__
714 #define SAL_LOPLUGIN_ANNOTATE(id) [[clang::annotate("loplugin:" id)]]
715 #else
716 #define SAL_LOPLUGIN_ANNOTATE(id)
717 #endif
718 #endif
719 
720 #endif // INCLUDED_SAL_TYPES_H
721 
722 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */
void * sal_Handle
Definition: types.h:126
signed char sal_Int8
Definition: types.h:43
This is the binary specification of a SAL sequence.
Definition: types.h:320
struct _sal_Sequence sal_Sequence
This is the binary specification of a SAL sequence.
char elements[1]
elements array
Definition: types.h:330
Definition: types.h:376
sal_uInt16 sal_Unicode
Definition: types.h:123
unsigned char sal_Bool
Definition: types.h:38
__sal_NoAcquire
Definition: types.h:369
Definition: types.h:440
sal_Int32 nRefCount
reference count of sequence
Definition: types.h:324
sal_Int32 nElements
element count
Definition: types.h:327
definition of a no acquire enum for ctors
Definition: types.h:373
T1 static_int_cast(T2 n)
A static_cast between integral types, to avoid C++ compiler warnings.
Definition: types.h:453
Definition: types.h:376
unsigned char sal_uInt8
Definition: types.h:44