Function set "Structure Support"

Functions used to manipulate C structures directly.

more...

Summary

Functions used to manipulate C structures directly.

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

Members

getStruct()

Gets raw data from a structure.

getStruct( struct, offset, size )

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] )

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] )

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 )

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 )

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 )

setStruct()

Sets raw data into a structure.

setStruct( struct, offset, size, data )

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 )

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.