Build Configuration

Modules
	Building Dynamic Link Libraries (DLL/DSO)

Macros
#define	PJ_DEBUG   1
#define	PJ_DEBUG_MUTEX   0
#define	PJ_FUNCTIONS_ARE_INLINED   0
#define	PJ_HAS_FLOATING_POINT   1
#define	PJ_LOG_MAX_SIZE   4000
#define	PJ_LOG_USE_STACK_BUFFER   1
#define	PJ_LOG_ENABLE_INDENT   1
#define	PJ_LOG_INDENT_SIZE   1
#define	PJ_LOG_INDENT_CHAR   '.'
#define	PJ_LOG_SENDER_WIDTH   14
#define	PJ_LOG_THREAD_WIDTH   12
#define	PJ_TERM_HAS_COLOR   1
#define	PJ_SAFE_POOL   0
#define	PJ_POOL_DEBUG   0
#define	PJ_POOL_RELEASE_WIPE_DATA   0
#define	PJ_TIMER_DEBUG   1
#define	PJ_TIMER_USE_COPY   1
#define	PJ_TIMER_USE_LINKED_LIST   0
#define	PJ_GRP_LOCK_DEBUG   0
#define	PJ_THREAD_DEFAULT_STACK_SIZE   8192
#define	PJ_OS_HAS_CHECK_STACK   0
#define	PJ_HAS_POOL_ALT_API   PJ_POOL_DEBUG
#define	PJ_HAS_IPV6   0
#define	PJ_MAX_HOSTNAME   (128)
#define	PJ_ACTIVESOCK_MAX_CONSECUTIVE_ACCEPT_ERROR   50
#define	PJ_IOQUEUE_MAX_HANDLES   (64)
#define	PJ_IOQUEUE_HAS_SAFE_UNREG   1
#define	PJ_IOQUEUE_DEFAULT_ALLOW_CONCURRENCY   1
#define	PJ_IOQUEUE_KEY_FREE_DELAY   500
#define	PJ_IOQUEUE_DEFAULT_EPOLL_FLAGS   PJ_IOQUEUE_EPOLL_AUTO
#define	PJ_FD_SETSIZE_SETABLE   0
#define	PJ_IP_HELPER_IGNORE_LOOPBACK_IF   1
#define	PJ_SEMAPHORE_USE_DISPATCH_SEM   0
#define	PJ_MAXPATH   260
#define	PJ_HAS_EXCEPTION_NAMES   1
#define	PJ_MAX_EXCEPTION_ID   16
#define	PJ_EXCEPTION_USE_WIN32_SEH   0
#define	PJ_TIMESTAMP_USE_RDTSC   0
#define	PJ_NATIVE_ERR_POSITIVE   1
#define	PJ_HAS_ERROR_STRING   1
#define	PJ_HAS_STRICMP_ALNUM   0
#define	PJ_QOS_DUMMY   1
#define	PJ_QOS_BSD   2
#define	PJ_QOS_WM   3
#define	PJ_QOS_SYMBIAN   4
#define	PJ_QOS_DARWIN   5
#define	PJ_HAS_SSL_SOCK   0
#define	PJ_SSL_SOCK_IMP_NONE   0
#define	PJ_SSL_SOCK_IMP_OPENSSL   1
#define	PJ_SSL_SOCK_IMP_GNUTLS   2
#define	PJ_SSL_SOCK_IMP_DARWIN   3
#define	PJ_SSL_SOCK_IMP_APPLE   4
#define	PJ_SSL_SOCK_IMP   PJ_SSL_SOCK_IMP_NONE
#define	PJ_SSL_SOCK_MAX_CIPHERS   256
#define	PJ_SSL_SOCK_OSSL_CIPHERS   "HIGH:-COMPLEMENTOFDEFAULT"
#define	PJ_SSL_SOCK_MAX_CURVES   32
#define	PJ_SSL_SOCK_OSSL_USE_THREAD_CB   1
#define	PJ_SOCK_DISABLE_WSAECONNRESET   1
#define	PJ_MAX_SOCKOPT_PARAMS   4
#define	PJ_INLINE(type)   PJ_INLINE_SPECIFIER type
#define	PJ_EXPORT_DECL_SPECIFIER
#define	PJ_EXPORT_DEF_SPECIFIER
#define	PJ_IMPORT_DECL_SPECIFIER
#define	PJ_EXPORT_SYMBOL(x)
#define	PJ_DECL_NO_RETURN(type)   PJ_NORETURN PJ_DECL(type)
#define	PJ_IDECL_NO_RETURN(type)   PJ_NORETURN PJ_INLINE(type)
#define	PJ_BEGIN_DECL
#define	PJ_END_DECL
#define	PJ_DEF_DATA(type)   type
#define	PJ_IDECL(type)   PJ_DECL(type)
#define	PJ_IDEF(type)   PJ_DEF(type)
#define	PJ_UNUSED_ARG(arg)   (void)arg
#define	PJ_TODO(id)   TODO___##id:
#define	PJ_RACE_ME(x)
#define	__pj_throw__(x)

Detailed Description

This section contains macros that can set during PJLIB build process to controll various aspects of the library.

Note: the values in this page does NOT necessarily reflect to the macro values during the build process.

Macro Definition Documentation

__pj_throw__

#define __pj_throw__

(

x

)

Function attributes to inform that the function may throw exception.

Parameters

x	The exception list, enclosed in parenthesis.

PJ_ACTIVESOCK_MAX_CONSECUTIVE_ACCEPT_ERROR

#define PJ_ACTIVESOCK_MAX_CONSECUTIVE_ACCEPT_ERROR   50

Maximum consecutive identical error for accept() operation before activesock stops calling the next ioqueue accept.

Default: 50

PJ_BEGIN_DECL

#define PJ_BEGIN_DECL

Mark beginning of declaration section in a header file.

PJ_DEBUG

#define PJ_DEBUG   1

If this macro is set to 1, it will enable some debugging checking in the library.

Default: equal to (NOT NDEBUG).

PJ_DEBUG_MUTEX

#define PJ_DEBUG_MUTEX   0

Enable this macro to activate logging to mutex/semaphore related events. This is useful to troubleshoot concurrency problems such as deadlocks. In addition, you should also add PJ_LOG_HAS_THREAD_ID flag to the log decoration to assist the troubleshooting.

Default: 0

PJ_DECL_NO_RETURN

#define PJ_DECL_NO_RETURN

(

type

)

PJ_NORETURN PJ_DECL(type)

Parameters

type	The return type of the function. Declare a function that will not return.

PJ_DEF_DATA

#define PJ_DEF_DATA

(

type

)

type

Parameters

type	The data type. Define a global data.

PJ_END_DECL

#define PJ_END_DECL

Mark end of declaration section in a header file.

PJ_EXCEPTION_USE_WIN32_SEH

#define PJ_EXCEPTION_USE_WIN32_SEH   0

Should we use Windows Structured Exception Handling (SEH) for the PJLIB exceptions.

Default: 0

PJ_EXPORT_DECL_SPECIFIER

#define PJ_EXPORT_DECL_SPECIFIER

This macro declares platform/compiler specific specifier prefix to be added to symbol declaration to export the symbol when PJLIB is built as dynamic library.

This macro should have been added by platform specific headers, if the platform supports building dynamic library target.

PJ_EXPORT_DEF_SPECIFIER

#define PJ_EXPORT_DEF_SPECIFIER

This macro declares platform/compiler specific specifier prefix to be added to symbol definition to export the symbol when PJLIB is built as dynamic library.

This macro should have been added by platform specific headers, if the platform supports building dynamic library target.

PJ_EXPORT_SYMBOL

#define PJ_EXPORT_SYMBOL

(

x

)

This macro has been deprecated. It will evaluate to nothing.

PJ_FD_SETSIZE_SETABLE

#define PJ_FD_SETSIZE_SETABLE   0

Determine if FD_SETSIZE is changeable/set-able. If so, then we will set it to PJ_IOQUEUE_MAX_HANDLES. Currently we detect this by checking for Winsock.

PJ_FUNCTIONS_ARE_INLINED

#define PJ_FUNCTIONS_ARE_INLINED   0

Expand functions in *_i.h header files as inline.

Default: 0.

PJ_GRP_LOCK_DEBUG

#define PJ_GRP_LOCK_DEBUG   0

Set this to 1 to enable debugging on the group lock. Default: 0

PJ_HAS_ERROR_STRING

#define PJ_HAS_ERROR_STRING   1

Include error message string in the library (pj_strerror()). This is very much desirable!

Default: 1

PJ_HAS_EXCEPTION_NAMES

#define PJ_HAS_EXCEPTION_NAMES   1

Enable name registration for exceptions with pj_exception_id_alloc(). If this feature is enabled, then the library will keep track of names associated with each exception ID requested by application via pj_exception_id_alloc().

Disabling this macro will reduce the code and .bss size by a tad bit. See also PJ_MAX_EXCEPTION_ID.

Default: 1

PJ_HAS_FLOATING_POINT

#define PJ_HAS_FLOATING_POINT   1

Use floating point computations in the library.

Default: 1.

PJ_HAS_IPV6

#define PJ_HAS_IPV6   0

Support TCP in the library. Disabling TCP will reduce the footprint slightly (about 6KB).

Default: 1 Support IPv6 in the library. If this support is disabled, some IPv6 related functions will return PJ_EIPV6NOTSUP.

Default: 0 (disabled, for now)

PJ_HAS_POOL_ALT_API

#define PJ_HAS_POOL_ALT_API   PJ_POOL_DEBUG

Do we have alternate pool implementation?

Default: 0

PJ_HAS_SSL_SOCK

#define PJ_HAS_SSL_SOCK   0

Force the use of some QoS backend API for some platforms. Enable secure socket. For most platforms, this is implemented using OpenSSL or GnuTLS, so this will require one of those libraries to be installed. For Symbian platform, this is implemented natively using CSecureSocket.

Default: 0 (for now)

PJ_HAS_STRICMP_ALNUM

#define PJ_HAS_STRICMP_ALNUM   0

Include pj_stricmp_alnum() and pj_strnicmp_alnum(), i.e. custom functions to compare alnum strings. On some systems, they're faster then stricmp/strcasecmp, but they can be slower on other systems. When disabled, pjlib will fallback to stricmp/strnicmp.

Default: 0

PJ_IDECL

#define PJ_IDECL

(

type

)

PJ_DECL(type)

Parameters

type	The function's return type. Declare a function that may be expanded as inline.

PJ_IDECL_NO_RETURN

#define PJ_IDECL_NO_RETURN

(

type

)

PJ_NORETURN PJ_INLINE(type)

Parameters

type	The return type of the function. Declare an inline function that will not return.

PJ_IDEF

#define PJ_IDEF

(

type

)

PJ_DEF(type)

Parameters

type	The function's return type. Define a function that may be expanded as inline.

PJ_IMPORT_DECL_SPECIFIER

#define PJ_IMPORT_DECL_SPECIFIER

This macro declares platform/compiler specific specifier prefix to be added to symbol declaration to import the symbol.

This macro should have been added by platform specific headers, if the platform supports building dynamic library target.

PJ_INLINE

#define PJ_INLINE

(

type

)

PJ_INLINE_SPECIFIER type

Parameters

type	The return type of the function. Expand the function as inline.

PJ_IOQUEUE_DEFAULT_ALLOW_CONCURRENCY

#define PJ_IOQUEUE_DEFAULT_ALLOW_CONCURRENCY   1

Default concurrency setting for sockets/handles registered to ioqueue. This controls whether the ioqueue is allowed to call the key's callback concurrently/in parallel. The default is yes, which means that if there are more than one pending operations complete simultaneously, more than one threads may call the key's callback at the same time. This generally would promote good scalability for application, at the expense of more complexity to manage the concurrent accesses.

Please see the ioqueue documentation for more info.

PJ_IOQUEUE_DEFAULT_EPOLL_FLAGS

#define PJ_IOQUEUE_DEFAULT_EPOLL_FLAGS   PJ_IOQUEUE_EPOLL_AUTO

Default flags for epoll_flags member of pj_ioqueue_cfg structure. The values are combination of pj_ioqueue_epoll_flag constants.

Default: PJ_IOQUEUE_EPOLL_AUTO

PJ_IOQUEUE_HAS_SAFE_UNREG

#define PJ_IOQUEUE_HAS_SAFE_UNREG   1

If PJ_IOQUEUE_HAS_SAFE_UNREG macro is defined, then ioqueue will do more things to ensure thread safety of handle unregistration operation by employing reference counter to each handle.

In addition, the ioqueue will preallocate memory for the handles, according to the maximum number of handles that is specified during ioqueue creation.

All applications would normally want this enabled, but you may disable this if:

• there is no dynamic unregistration to all ioqueues.
• there is no threading, or there is no preemptive multitasking.

Default: 1

PJ_IOQUEUE_KEY_FREE_DELAY

#define PJ_IOQUEUE_KEY_FREE_DELAY   500

When safe unregistration (PJ_IOQUEUE_HAS_SAFE_UNREG) is configured in ioqueue, the PJ_IOQUEUE_KEY_FREE_DELAY macro specifies how long the ioqueue key is kept in closing state before it can be reused.

The value is in miliseconds.

Default: 500 msec.

PJ_IOQUEUE_MAX_HANDLES

#define PJ_IOQUEUE_MAX_HANDLES   (64)

Constants for declaring the maximum handles that can be supported by a single IOQ framework. This constant might not be relevant to the underlying I/O queue impelementation, but still, developers should be aware of this constant, to make sure that the program will not break when the underlying implementation changes.

PJ_IP_HELPER_IGNORE_LOOPBACK_IF

#define PJ_IP_HELPER_IGNORE_LOOPBACK_IF   1

Overrides FD_SETSIZE so it is consistent throughout the library. We only do this if we detected that FD_SETSIZE is changeable. If FD_SETSIZE is not set-able, then PJ_IOQUEUE_MAX_HANDLES must be set to value lower than FD_SETSIZE. Specify whether pj_enum_ip_interface() function should exclude loopback interfaces.

Default: 1

PJ_LOG_ENABLE_INDENT

#define PJ_LOG_ENABLE_INDENT   1

Enable log indentation feature.

Default: 1

PJ_LOG_INDENT_CHAR

#define PJ_LOG_INDENT_CHAR   '.'

Log indentation character.

Default: space

PJ_LOG_INDENT_SIZE

#define PJ_LOG_INDENT_SIZE   1

Number of PJ_LOG_INDENT_CHAR to put every time pj_log_push_indent() is called.

Default: 1

PJ_LOG_MAX_SIZE

#define PJ_LOG_MAX_SIZE   4000

Declare maximum logging level/verbosity. Lower number indicates higher importance, with the highest importance has level zero. The least important level is five in this implementation, but this can be extended by supplying the appropriate implementation.

The level conventions:

• 0: fatal error
• 1: error
• 2: warning
• 3: info
• 4: debug
• 5: trace
• 6: more detailed trace

Default: 4 Maximum message size that can be sent to output device for each call to PJ_LOG(). If the message size is longer than this value, it will be cut. This may affect the stack usage, depending whether PJ_LOG_USE_STACK_BUFFER flag is set.

Default: 4000

PJ_LOG_SENDER_WIDTH

#define PJ_LOG_SENDER_WIDTH   14

Log sender width.

Default: 22 (for 64-bit machines), 14 otherwise

PJ_LOG_THREAD_WIDTH

#define PJ_LOG_THREAD_WIDTH   12

Log thread name width.

Default: 12

PJ_LOG_USE_STACK_BUFFER

#define PJ_LOG_USE_STACK_BUFFER   1

Log buffer. Does the log get the buffer from the stack? (default is yes). If the value is set to NO, then the buffer will be taken from static buffer, which in this case will make the log function non-reentrant.

Default: 1

PJ_MAX_EXCEPTION_ID

#define PJ_MAX_EXCEPTION_ID   16

Maximum number of unique exception IDs that can be requested with pj_exception_id_alloc(). For each entry, a small record will be allocated in the .bss segment.

Default: 16

PJ_MAX_HOSTNAME

#define PJ_MAX_HOSTNAME   (128)

Maximum hostname length. Libraries sometimes needs to make copy of an address to stack buffer; the value here affects the stack usage.

Default: 128

PJ_MAX_SOCKOPT_PARAMS

#define PJ_MAX_SOCKOPT_PARAMS   4

Maximum number of socket options in pj_sockopt_params.

Default: 4

PJ_MAXPATH

#define PJ_MAXPATH   260

Event object (for synchronization, e.g. in Win32)

Default: 1 Maximum file name length.

PJ_NATIVE_ERR_POSITIVE

#define PJ_NATIVE_ERR_POSITIVE   1

Is native platform error positive number? Default: 1 (yes)

PJ_OS_HAS_CHECK_STACK

#define PJ_OS_HAS_CHECK_STACK   0

Specify if PJ_CHECK_STACK() macro is enabled to check the sanity of the stack. The OS implementation may check that no stack overflow occurs, and it also may collect statistic about stack usage. Note that this will increase the footprint of the libraries since it tracks the filename and line number of each functions.

PJ_POOL_DEBUG

#define PJ_POOL_DEBUG   0

If pool debugging is used, then each memory allocation from the pool will call malloc(), and pool will release all memory chunks when it is destroyed. This works better when memory verification programs such as Rational Purify is used.

Default: 0

PJ_POOL_RELEASE_WIPE_DATA

#define PJ_POOL_RELEASE_WIPE_DATA   0

If enabled, when calling pj_pool_release(), the memory pool content will be wiped out first before released.

Default: 0

PJ_QOS_BSD

#define PJ_QOS_BSD   2

QoS backend based on setsockopt(IP_TOS)

PJ_QOS_DARWIN

#define PJ_QOS_DARWIN   5

QoS backend for Darwin

PJ_QOS_DUMMY

#define PJ_QOS_DUMMY   1

Dummy QoS backend implementation, will always return error on all the APIs.

PJ_QOS_SYMBIAN

#define PJ_QOS_SYMBIAN   4

QoS backend for Symbian

PJ_QOS_WM

#define PJ_QOS_WM   3

QoS backend for Windows Mobile 6

PJ_RACE_ME

#define PJ_RACE_ME

(

x

)

Simulate race condition by sleeping the thread in strategic locations. Default: no!

PJ_SAFE_POOL

#define PJ_SAFE_POOL   0

Set this flag to non-zero to enable various checking for pool operations. When this flag is set, assertion must be enabled in the application.

This will slow down pool creation and destruction and will add few bytes of overhead, so application would normally want to disable this feature on release build.

Default: 0

PJ_SEMAPHORE_USE_DISPATCH_SEM

#define PJ_SEMAPHORE_USE_DISPATCH_SEM   0

Has semaphore functionality?

Default: 1 Use dispatch semaphores on Darwin.

Default: 1 on Darwin, 0 otherwise

PJ_SOCK_DISABLE_WSAECONNRESET

#define PJ_SOCK_DISABLE_WSAECONNRESET   1

Disable WSAECONNRESET error for UDP sockets on Win32 platforms. See https://github.com/pjsip/pjproject/issues/1197.

Default: 1

PJ_SSL_SOCK_IMP

#define PJ_SSL_SOCK_IMP   PJ_SSL_SOCK_IMP_NONE

Select which SSL socket implementation to use. Currently pjlib supports PJ_SSL_SOCK_IMP_OPENSSL, which uses OpenSSL, and PJ_SSL_SOCK_IMP_GNUTLS, which uses GnuTLS. Setting this to PJ_SSL_SOCK_IMP_NONE will disable secure socket.

Default is PJ_SSL_SOCK_IMP_NONE if PJ_HAS_SSL_SOCK is not set, otherwise it is PJ_SSL_SOCK_IMP_OPENSSL.

PJ_SSL_SOCK_IMP_APPLE

#define PJ_SSL_SOCK_IMP_APPLE   4

Using Apple's Network framework.

PJ_SSL_SOCK_IMP_DARWIN

#define PJ_SSL_SOCK_IMP_DARWIN   3

Using Apple's Secure Transport (deprecated in MacOS 10.15 & iOS 13.0)

PJ_SSL_SOCK_IMP_GNUTLS

#define PJ_SSL_SOCK_IMP_GNUTLS   2

Using GnuTLS.

PJ_SSL_SOCK_IMP_NONE

#define PJ_SSL_SOCK_IMP_NONE   0

Disable SSL socket.

PJ_SSL_SOCK_IMP_OPENSSL

#define PJ_SSL_SOCK_IMP_OPENSSL   1

Using OpenSSL.

PJ_SSL_SOCK_MAX_CIPHERS

#define PJ_SSL_SOCK_MAX_CIPHERS   256

Define the maximum number of ciphers supported by the secure socket.

Default: 256

PJ_SSL_SOCK_MAX_CURVES

#define PJ_SSL_SOCK_MAX_CURVES   32

Define the maximum number of curves supported by the secure socket.

Default: 32

PJ_SSL_SOCK_OSSL_CIPHERS

#define PJ_SSL_SOCK_OSSL_CIPHERS   "HIGH:-COMPLEMENTOFDEFAULT"

Specify what should be set as the available list of SSL_CIPHERs. For example, set this as "DEFAULT" to use the default cipher list (Note: PJSIP release 2.4 and before used this "DEFAULT" setting).

Default: "HIGH:-COMPLEMENTOFDEFAULT"

PJ_SSL_SOCK_OSSL_USE_THREAD_CB

#define PJ_SSL_SOCK_OSSL_USE_THREAD_CB   1

Use OpenSSL thread locking callback. This is only applicable for OpenSSL version prior to 1.1.0

Default: 1 (enabled)

PJ_TERM_HAS_COLOR

#define PJ_TERM_HAS_COLOR   1

Colorfull terminal (for logging etc).

Default: 1

PJ_THREAD_DEFAULT_STACK_SIZE

#define PJ_THREAD_DEFAULT_STACK_SIZE   8192

Specify this as stack_size argument in pj_thread_create() to specify that thread should use default stack size for the current platform.

Default: 8192

PJ_TIMER_DEBUG

#define PJ_TIMER_DEBUG   1

Enable timer debugging facility. When this is enabled, application can call pj_timer_heap_dump() to show the contents of the timer along with the source location where the timer entries were scheduled. See https://github.com/pjsip/pjproject/issues/1527 for more info.

Default: 1

PJ_TIMER_USE_COPY

#define PJ_TIMER_USE_COPY   1

If enabled, the timer will keep internal copies of the timer entries. This will increase the robustness and stability of the timer (against accidental modification or premature deallocation of the timer entries) and makes it easier to troubleshoot any timer related issues, with the overhead of additional memory space required.

Note that the detection against premature deallocation only works if the freed memory content has changed (such as if it's been reallocated and overwritten by another data. Alternatively, you can enable PJ_POOL_RELEASE_WIPE_DATA which will erase the data first before releasing the memory).

Default: 1 (enabled)

PJ_TIMER_USE_LINKED_LIST

#define PJ_TIMER_USE_LINKED_LIST   0

If enabled, the timer use sorted linked list instead of binary heap tree structure. Note that using sorted linked list is intended for debugging purposes and will hamper performance significantly when scheduling large number of entries.

Default: 0 (Use binary heap tree)

PJ_TIMESTAMP_USE_RDTSC

#define PJ_TIMESTAMP_USE_RDTSC   0

Should we attempt to use Pentium's rdtsc for high resolution timestamp.

Default: 0

PJ_TODO

#define PJ_TODO

(

id

)

TODO___##id:

Parameters

id	Any identifier that will be printed as TODO message. PJ_TODO macro will display TODO message as warning during compilation. Example: PJ_TODO(CLEAN_UP_ERROR);

PJ_UNUSED_ARG

#define PJ_UNUSED_ARG

(

arg

)

(void)arg

Parameters

arg	The argument name. PJ_UNUSED_ARG prevents warning about unused argument in a function.