Functions used to manipulate C structures directly.
This functions are meant to use memory buffers as structures to be passed to remote functions.
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. |
| Return | An 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.
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. |
| Return | The 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.
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.
Creates a memory buffer out from a raw pointer.
memBufFromPtr( ptr, size )
| ptr | The raw memory pointer. |
| size | The size of the memory buffer. |
| Return | A 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.
Returns the inner data of a memory buffer.
memBufToPtr( mb )
| mb | The memory buffer to be placed in the foreign structure. |
| Return | The 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.
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. |
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.
Returns the inner data of a string.
stringToPtr( string )
| string | The string to be placed in a foreign structure. |
| Return | The 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.