Windows, C/C++ and Xbase++ strings

As usual for C or C++ Windows assumes text strings to contain Ansi characters terminated with a NULL-byte or Unicode characters terminated with a NULL-word. This termination convention is possible because no glyph is assigned to the Ansi character 0x00 or the Unicode character 0x0000. Although in C/C++ the buffer holding a text string might be bigger than the actual string, all C/C++ text string functions only read the string up to the terminator. When C/C++ text strings are transferred from memory to Xbase++ values, these strings must only be read up to the terminator excluding it. When a text string is transferred from an Xbase++ value to memory in preparation of a function call, the proper terminator must be added. Since an Xbase++ string does not bear any information about its contents (binary or text), a string type can be specified for all Cockpit Core string transfer functions. It controls terminator handling and character set conversion as well.

Because binary strings (which don't represent text information) can include any byte value as valid data, automatic termination with a dedicated terminator is not possible in C/C++ and some extra size information is required in function calls.

A size information must also be passed separately to a function that is supposed to return a binary or text string in a buffer that was allocated by the caller. Sometimes this size information must not explicitly be passed as a parameter. In this case you will find some information in the docs which minimum size of the buffer is expected.