Preprocessor Definitions
The CIGI_LITTLE_ENDIAN and MOST_SIGNIFICANT_BIT_FIRST preprocessor definitions are used
by the API. These two flags should be set depending on the memory layout of the target architecture. For example, Intel-based systems will
typically define CIGI_LITTLE_ENDIAN but not the MOST_SIGNIFICANT_BIT_FIRST flag.
These two preprocessor definitions will generally be set for the project, but do not necessarily have to be. Because all conditional processing
for these flags is done in the header and not the implementation file, it is ok to define these before including the CIGI files and then to
undefine them afterwards. This is desirable when the preprocessor definition are not wanted or cause problems with other files in the
project. The following segment of code illustrates this.
Example |
#ifndef CIGI_LITTLE_ENDIAN
#define CIGI_LITTLE_ENDIAN
#endif
#include <cigi_icd.h>
#undef CIGI_LITTLE_ENDIAN
|
 |
|
In addition, the CIGI_FORCE_DWORD_ALIGN preprocessor definition is used by the API, but is used from within the cigi_api.c
source file, so it will need to be defined before this file is compiled.
CIGI_LITTLE_ENDIAN
If the target architecture is little endian, then CIGI_LITTLE_ENDIAN should be defined for the project, or for the CIGI include files.
The Intel architecture is one of the widely used little endian architectures, while most of the other
processors such as the MIPS and Power PC based architectures are big endian.
The network byte order format is big endian, so if CIGI_LITTLE_ENDIAN is defined, the data will be byte-swapped by the API when it each packet is
added to the outgoing message. When received, the packets in the CIGI message are in big endian format, so if CIGI_LITTLE_ENDIAN is defined, the API
will byte-swap the data. Note the byte-swapping done on little endian architectures incurs some overhead the big endian versions of the API functions.
Note: This preprocessor definition was changed from LITTLE_ENDIAN to CIGI_LITTLE_ENDIAN
after the release of the CIGI API version 2, due to conflicts with other libraries.
MOST_SIGNIFICANT_BIT_FIRST
Target architectures for which the first bit in memory is the most significant, should use the MOST_SIGNIFICANT_BIT_FIRST preprocessor definition.
This is the case for most processors, including MIPS and Power PC based architectures. In contrast, the Intel processor
places the least significant bit first in memory, and the most significant bit last, so this definition will not be needed.
The MOST_SIGNIFICANT_BIT_FIRST definition controls how the bit fields in the CIGI packets are declared in the cigi_icd.h file. In particular, the
bit fields are swapped on a byte-per-byte basis.
CIGI_FORCE_DWORD_ALIGN
Structures which contain double fields need to be aligned on double word boundaries, which most compilers are capabile of handling. The
CIGI_FORCE_DWORD_ALIGN definition is used with compilers for which this is not the case, or to ensure that the packets accessed in the
incoming message buffer are aligned on such a boundary. For more information, refer to the topic
on structure alignment in the compiler issues section.
Instead of accessing the packet from directly within the message buffer, packets are copied to a temporary session buffer which is known to be aligned correctly on
a double word. This means that when examining incoming messages, the packet pointer obtained from functions that process the incoming message buffer should not be
advanced or changed directly.
CIGI_VERSION_N
The CIGI API is made to be compatible with pervious versions of the CIGI, but functions called through the API default to the most recent version. Functions
implemented for previous versions may be invoked explicitly, without having to set them as the default. To set the default CIGI version for the API, the
preprocessor definition CIGI_VERSION_N is used, where N is version number to use.
Example |
#define CIGI_VERSION_1
|
|
|
For details about how versioning is handled by the CIGI API, please refer to the section on versioning.
CIGIAPI_LIBRARY
The presence of the CIGIAPI_LIBRARY preprocessor definition will prevent the API from automatically referencing the little endian
versions of the CIGI functions, which is normally done when the CIGI_LITTLE_ENDIAN preprocessor definition is defined. This is done
so that the API can (internally) access both big and little endian versions of the functions. In general, this should not need to be
defined unless directly modifying the API.
For more information, see the section above on CIGI_LITTLE_ENDIAN.
|
|
