10.1Structure Support

Functions used to manipulate C structures directly.

This functions are meant to use memory buffers as structures to be passed to remote functions.

Functions

getStruct

Gets raw data from a structure.

getStruct( struct, offset, size )
struct Memory buffer or raw pointer pointing to the structure.
offset Offset in bytes of the retreived data.
size Size in bytes of the retreived data.
ReturnAn integer containing the binary value of the data (in local endianity).

Size can be either 1, 2, 4 or 8. If struct is a MemBuf, offset must be smaller than the size of the MemBuf.

limitMembuf

Sizes a memory buffer to a zero terminated string.

limitMembuf( mb, [size] )
mb The memory buffer to be sized.
size The size at which to cut the memory buffer.
ReturnThe resized Memory Buffer.

Many external functions in C dynamic libraries returns zero terminated strings in an encoding-neutral format.

It is possible to encapsulate that data in a Falcon memory buffer for easier manipulation in Falcon, and possibly for a later transformation into an internationalized Falcon string.

Whenever DynLib returns a memory buffer, it sets its size to 2^31, as the size of the returned data is not known. But if the user knows that the returned data is actually a non-utf8 zero terminated string (utf-8 strings can be parsed directly with the "S" return specifier), or if it has some mean to determine the returned structure size, it is possible to re-size the MemBuf so that it fits the actual data. It is granted that the resized memory buffer points to the same foreign data as the original one, so the returned buffer can be fed into foreign function expecting to deal with the original data.

Note: The behavior of this function is undefined if the mb parameter was not created through a function in DynLib in versions prior to 0.8.12.

If the size parameter is not provided, the function scans for a zero byte and sets that position as the size of this memory buffer. If it's provided, that value is used as the new dimension of the Memory Buffer.

Note: Using this function is necessary to correctly turn a C zero terminated string in arbitrary encoding into a Falcon string via transcodeFrom.

Note: since version 0.9, the function modifies the original memory buffer and returns it, instead of creating a new memory buffer.

limitMembufW

Sizes a memory buffer to a zero terminated string.

limitMembufW( mb, [size] )
mb The memory buffer to be sized.
size The size at which to cut the memory buffer.

Many external functions in C dynamic libraries returns zero terminated strings in an encoding-neutral format.

It is possible to encapsulate that data in a Falcon memory buffer for easier manipulation in Falcon, and possibly for a later transformation into an internationalized Falcon string.

Whenever DynLib returns a memory buffer, it sets its size to 2^31, as the size of the returned data is not known. But if the user knows that the returned data is actually a non-utf16 zero terminated string (utf-16 strings can be parsed directly with the "W" return specifier), or if it has some mean to determine the returned structure size, it is possible to re-size the MemBuf so that it fits the actual data. It is granted that the resized memory buffer points to the same foreign data as the original one, so the returned buffer can be fed into foreign function expecting to deal with the original data.

Note: The behavior of this function is undefined if the mb parameter was not created through a function in DynLib in versions prior to 0.8.12.

If the size parameter is not provided, the function scans for a zero short int (16-bit word) and sets that position as the size of this memory buffer. If it's provided, that value is used as the new dimension of the Memory Buffer.

Note: Using this function is necessary to correctly turn a C zero terminated string in arbitrary encoding into a Falcon string via transcodeFrom.

Note: Actually, this function uses the platform specific wchar_t size to scan for the 0 terminator. On some platforms, wchar_t is 4 bytes wide.

Note: since version 0.9, the function modifies the original memory buffer and returns it, instead of creating a new memory buffer.

memBufFromPtr

Creates a memory buffer out from a raw pointer.

memBufFromPtr( ptr, size )
ptr The raw memory pointer.
size The size of the memory buffer.
ReturnA memory buffer pointing to the memory data.

This function returns a memory buffer that can be used to access the given data area, byte by byte. The memory buffer doesn't dispose of the memory when it is destroyed.

memBufToPtr

Returns the inner data of a memory buffer.

memBufToPtr( mb )
mb The memory buffer to be placed in the foreign structure.
ReturnThe memory pointer to the memory buffer data.

This function returns the inner data of a Falcon MemBuf to be used in managed structures. It can be passed to any remote function, as long as the remote function doesn't relocate the structure, or tries to write more bytes than the structure size.

Memory Buffers passed in this way can receive string data placed in deep structures by the remote library and then turned into string via strFromMemBuf function in the core module. Use limitMembuf or limitMembufW prior to create a string from a memory buffer filled in this way.

memSet

sets the given memory to a given byte value

memSet( struct, value, size )
struct The structure raw pointer o MemBuf
value The value to be set in the structure (0-255)
size The size of the memory to be set.

setStruct

Sets raw data into a structure.

setStruct( struct, offset, size, data )
struct Memory buffer or raw pointer pointing to the structure.
offset Offset in bytes of the set data.
size Size in bytes of the set data.
data The data to be set (numeric value)

Size can be either 1, 2, 4 or 8. If struct is a MemBuf, offset must be smaller than the size of the MemBuf. Data must be an integer; it should be always > 0 except when size is 8.

stringToPtr

Returns the inner data of a string.

stringToPtr( string )
string The string to be placed in a foreign structure.
ReturnThe memory pointer to the string data.

This function returns the inner data of a Falcon string to be used in managed structures. As such, it is quite dangerous, and should be used only when the remote functions is taking this data as read-only.

Made with http://www.falconpl.org