LibreOffice LibreOffice 26.2 SDK C/C++ API Reference

Loading...
Searching...
No Matches
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
291#if defined LIBO_INTERNAL_ONLY
298#ifdef _MSC_VER
299# define SAL_RET_MAYBENULL _Ret_maybenull_
300#else
301# define SAL_RET_MAYBENULL /*coverity[+returnsnull]*/
302#endif
303#endif
304
309#ifdef _MSC_VER
310# define SAL_NO_VTABLE __declspec(novtable)
311#else
312# define SAL_NO_VTABLE
313#endif
314
315#ifdef _WIN32
316# pragma pack(push, 8)
317#endif
318
321 typedef struct _sal_Sequence
322{
325 sal_Int32 nRefCount;
328 sal_Int32 nElements;
331 char elements[1];
332} sal_Sequence;
333
334#define SAL_SEQUENCE_HEADER_SIZE ((sal_Size) offsetof(sal_Sequence,elements))
335
336#if defined( _WIN32)
337#pragma pack(pop)
338#endif
339
340#ifdef __cplusplus
341}
342#endif /* __cplusplus */
343
348#if defined __cplusplus
349#if __cplusplus >= 201103L
350#define SAL_THROW_EXTERN_C() noexcept
351#else
352#define SAL_THROW_EXTERN_C() throw ()
353#endif
354#else
355#define SAL_THROW_EXTERN_C()
356#endif
357
358#ifdef __cplusplus
359
364#if defined(LIBO_INTERNAL_ONLY) && defined(__COVERITY__) && __COVERITY_MAJOR__ <= 2024
365# define COVERITY_NOEXCEPT_FALSE noexcept(false)
366#else
367# define COVERITY_NOEXCEPT_FALSE
368#endif
369
370 enum __sal_NoAcquire
371{
374 SAL_NO_ACQUIRE
375};
376
377 namespace com { namespace sun { namespace star { } } }
378
383 namespace css = ::com::sun::star;
384
393#if defined LIBO_INTERNAL_ONLY
394#define SAL_DELETED_FUNCTION = delete
395#else
396#define SAL_DELETED_FUNCTION
397#endif
398
406#if defined LIBO_INTERNAL_ONLY
407#define SAL_OVERRIDE override
408#else
409#define SAL_OVERRIDE
410#endif
411
419#if defined LIBO_INTERNAL_ONLY
420#define SAL_CONSTEXPR constexpr
421#else
422#define SAL_CONSTEXPR
423#endif
424
431#if __cplusplus >= 201103L
432#define SAL_NOEXCEPT noexcept
433#else
434#define SAL_NOEXCEPT throw ()
435#endif
436
437#endif /* __cplusplus */
438
439#ifdef __cplusplus
440
441 namespace sal {
442
454 template< typename T1, typename T2 > inline T1 static_int_cast(T2 n) {
455 return static_cast< T1 >(n);
456}
457
458}
459
460#else /* __cplusplus */
461
474#define SAL_INT_CAST(type, expr) ((type) (expr))
475
476#endif /* __cplusplus */
477
482
483#if defined __GNUC__ || defined __clang__
484#if defined LIBO_INTERNAL_ONLY
485# define SAL_DEPRECATED(message) __attribute__((deprecated(message)))
486#else
487# define SAL_DEPRECATED(message) __attribute__((deprecated))
488#endif
489#elif defined(_MSC_VER)
490# define SAL_DEPRECATED(message) __declspec(deprecated(message))
491#else
492# define SAL_DEPRECATED(message)
493#endif
494
506#ifdef LIBO_INTERNAL_ONLY
507# define SAL_DEPRECATED_INTERNAL(message)
508#else
509# define SAL_DEPRECATED_INTERNAL(message) SAL_DEPRECATED(message)
510#endif
511
518
519#if defined LIBO_INTERNAL_ONLY && defined __GNUC__
520#define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
521 _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic push)) \
522 _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic ignored "-Wdeprecated-declarations"))
523#define SAL_WNODEPRECATED_DECLARATIONS_POP \
524 _Pragma(SAL_STRINGIFY_ARG(GCC diagnostic pop))
525#elif defined LIBO_INTERNAL_ONLY && defined _MSC_VER
526#define SAL_WNODEPRECATED_DECLARATIONS_PUSH \
527 _Pragma(SAL_STRINGIFY_ARG(warning(push))) \
528 _Pragma(SAL_STRINGIFY_ARG(warning(disable : 4996)))
529#define SAL_WNODEPRECATED_DECLARATIONS_POP \
530 _Pragma(SAL_STRINGIFY_ARG(warning(pop)))
531#else
532# define SAL_WNODEPRECATED_DECLARATIONS_PUSH
533# define SAL_WNODEPRECATED_DECLARATIONS_POP
534#endif
535
551
552#ifdef _MSC_VER
553#define SAL_WNOUNREACHABLE_CODE_PUSH \
554 __pragma(warning(push)) \
555 __pragma(warning(disable:4702)) \
556 __pragma(warning(disable:4722))
557#define SAL_WNOUNREACHABLE_CODE_POP \
558 __pragma(warning(pop))
559#else
560/* Add definitions for GCC and Clang if needed */
561#define SAL_WNOUNREACHABLE_CODE_PUSH
562#define SAL_WNOUNREACHABLE_CODE_POP
563#endif
564
588#if defined __cplusplus
589#if defined __GNUC__ || defined __clang__
590#define SAL_UNUSED_PARAMETER __attribute__ ((unused))
591#else
592#define SAL_UNUSED_PARAMETER
593#endif
594#endif
595
607
608#if defined LIBO_INTERNAL_ONLY && (defined __GNUC__ || defined __clang__)
609#define SAL_WARN_UNUSED __attribute__((warn_unused))
610#else
611#define SAL_WARN_UNUSED
612#endif
613
615
616#if defined __GNUC__ || defined __clang__
617// Macro to try to catch and warn on assignments inside expr.
618# define SAL_DETAIL_BOOLEAN_EXPR(expr) \
619 __extension__ ({ \
620 int sal_boolean_var_; \
621 if (expr) \
622 sal_boolean_var_ = 1; \
623 else \
624 sal_boolean_var_ = 0; \
625 sal_boolean_var_; \
626 })
627
638# define SAL_LIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 1)
639
650# define SAL_UNLIKELY(expr) __builtin_expect(SAL_DETAIL_BOOLEAN_EXPR((expr)), 0)
651
663# define SAL_HOT __attribute__((hot))
664
678# define SAL_COLD __attribute__((cold))
679#else
680# define SAL_LIKELY(expr) (expr)
681# define SAL_UNLIKELY(expr) (expr)
682# define SAL_HOT
683# define SAL_COLD
684#endif
685
687
689
698#ifndef __has_attribute
699#define __has_attribute(x) 0
700#endif
701
702#if defined LIBO_INTERNAL_ONLY && ((defined __GNUC__ && !defined __clang__) || (defined __clang__ && __has_attribute(returns_nonnull)))
703#define SAL_RETURNS_NONNULL __attribute__((returns_nonnull))
704#else
705#define SAL_RETURNS_NONNULL
706#endif
708
709#if defined LIBO_INTERNAL_ONLY
710// An annotation mechanism used by some loplugins. The id argument must be an ordinary string
711// literal. For Clang, this expands to a clang::annotate attribute with an annotation consisting of
712// the concatenation of a "loplugin:" prefix and the given id suffix. For non-Clang, this expands
713// to nothing to avoid e.g. -Wattributes from GCC's -Wall.
714#if defined __clang__
715#define SAL_LOPLUGIN_ANNOTATE(id) [[clang::annotate("loplugin:" id)]]
716#else
717#define SAL_LOPLUGIN_ANNOTATE(id)
718#endif
719#endif
720
721#endif // INCLUDED_SAL_TYPES_H
722
723/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
macros.h
__sal_NoAcquire
__sal_NoAcquire
Definition types.h:371
SAL_NO_ACQUIRE
@ SAL_NO_ACQUIRE
definition of a no acquire enum for ctors
Definition types.h:374
sal_uInt8
unsigned char sal_uInt8
Definition types.h:44
sal_Sequence
struct _sal_Sequence sal_Sequence
This is the binary specification of a SAL sequence.
sal_Bool
unsigned char sal_Bool
Definition types.h:38
sal_Unicode
sal_uInt16 sal_Unicode
Definition types.h:123
sal_Handle
void * sal_Handle
Definition types.h:126
sal_Int8
signed char sal_Int8
Definition types.h:43
config.h
typesizes.h
com
Definition types.h:377
com::sun
Definition types.h:377
com::sun::star
Definition types.h:377
sal
Definition types.h:441
sal::static_int_cast
T1 static_int_cast(T2 n)
A static_cast between integral types, to avoid C++ compiler warnings.
Definition types.h:454
_sal_Sequence
This is the binary specification of a SAL sequence.
Definition types.h:322
_sal_Sequence::nRefCount
sal_Int32 nRefCount
reference count of sequence
Definition types.h:325
_sal_Sequence::nElements
sal_Int32 nElements
element count
Definition types.h:328
_sal_Sequence::elements
char elements[1]
elements array
Definition types.h:331