structs_1.4v.e
Version 1.4v
Written by: Chris Bensler and Jason Mirwald
Modified by: Vincent Howell
LAST MODIFIED : 1/1/06
Arrays:
An array of structures can be created either by a call to define_array, or by specifying a value other than 1 as the number of times a structure should be repeated when define_struct is called. The individual elements in an array of structures can be accessed using integer values in the elem argument of peek_struct or poke_struct to specify an indice within the array. If the indice in the array is the only id provided in the argument elem in either routine, it must be enclosed in curly braces.
For example; the fifth element in an array of RGBQUAD structures could be accessed with; {5}.
Unions:
When reading and writing data within a union, and a specific element within the union is not specified in the elem argument of peek_struct or poke_struct, the first data type that was defined within the union will be used by default.
Predefined Data Types:
Following is a list of the predefined data types that can be used when defining a structure:
Function Index
define_struct
define_array
define_union
sizeOf
offsetOf
alloc_struct
dealloc_struct
poke_struct
peek_struct
pokes
peeks
define_struct(sequence s)
Description: Define a C-style structure by specifying a list of elements that the structure is to contain. Each element can be one of the predefined data types, or another structure (including arrays and unions).
Each item listed in the sequence s should be a sequence containing three values; a string-id to identify the element, the type of data or a structure handle, and the number of times that data type is to be repeated within the structure.
Example:
RGBQUAD = define_struct({ { "Red", BYTE, 1 }, { "Blue", BYTE, 2 }, { "Green", BYTE, 4 }, { "Reserved", BYTE, 8 } })Return: Returns an atom representing the handle of the new structure.
define_array(integer i, integer l)
Description: Defines an array, or a series, of like structures. The integer i is a structure handle returned from a previous call to define_struct, and the integer l specifies the number of times to repeat the structure i.
Example:
palette = define_array( RGBQUAD, 256 )Return: Returns an atom representing the handle of the new structure.
define_union(sequence s)
Description: Defines a union of different data types or structures. The number of bytes reserved for the union will always be equal to the number of bytes needed by the largest element defined within the union.
Each item listed in the sequence s should be a sequence containing three values; a string-id for the element, the type of data or a structure handle, and the number of times that data type is to be repeated within the structure.
Example:
RGB_UNION = define_union({ { "RGBQUAD", RGBQUAD, 1 }, { "colorval", DWORD, 1 } })Return: Returns an atom representing the handle of the new structure.
sizeOf(object x)
Description: Return the size, in bytes, of a structure or an element within a structure. The argument x must be either the handle of a structure that was returned from a call to define_struct or the handle and a string-id of one of the elements.
If an two element sequence with a handle of a structure and a string-id of one of the elements is provided for argument x, or in the case of nested structures, a sequence of string-ids, the size of that element will be returned. Otherwise, if the handle is only provided, the size of the entire structure will be returned.Example:
rgb_size = sizeOf( RGBQUAD )
rgb_size = sizeOf( {RGBQUAD, "Green"} )Return: Returns an atom representing the number of bytes needed to store the structure in memory.
offsetOf(object x)
Description: Retrieve a pointer to the memory address of specific element within a structure.
Arguments:
str: If the argument str is an atom, it must be the pointer to a structure that was returned from a previous call to alloc_struct. To retrieve the address of an element in a structure that was not previously allocated using alloc_struct, the argument str can be a sequence containing two atoms, the address in memory where the structure is located, and a structure handle that was returned by define_struct. The sequence should have the format: { addr, str }.
elem: If the argument elem is a sequence of length zero, or {}, the address of the structure will be returned. By providing the string-id of one of the elements within the structure, or in the case of nested structures, a sequence of string-ids, the address of that element will be returned.
Return: Returns an atom representing the address of the specified element within the structure.
alloc_struct(object x)
Description: Allocates space for a structure in memory. Function dealloc_struct should be used to deallocate the memory reserved for the structure when it is no longer needed.
Return: Returns a pointer to the structure in memory that can be used in calls to peek_struct or poke_struct to read or write data within the structure.
dealloc_struct(atom addr)
Description: Frees the memory reserved for a structure.
Return: This procedure does not return a value.
peek_struct(atom id, object x)
Description: Return the value or values stored in a given structure, or element within a structure, from memory.
Arguments:
str: If the argument str is an atom, it must be the pointer to a structure that was returned from a previous call to alloc_struct. To read data from a structure that was not previously allocated using alloc_struct, the argument str can be a sequence containing two atoms, the address in memory where the structure is located, and a structure handle that was returned by define_struct. The sequence should have the format: { addr, str }.
elem: If the argument elem is a sequence of length zero, or {}, the data from the entire structure will be returned as a sequence of values, one for each element in the structure. By providing the string-id of one of the elements within the structure to be read, or in the case of nested structures, a sequence of string-ids, a single element within a structure can be read. In the case of an array of structures, and integer can be passed to specify the indice within the array.
Return: The type of data that is returned depends upon the arguments supplied in the arguments to the routine. If an atom value is specified by str and elem, and atom will be returned. In the case of arrays or structures, a sequence of values will be returned.
poke_struct(atom id, object x, object data)
Description: Poke the value or values in the object data into the structure str.
Arguments:
str: If the argument str is an atom, it must be the pointer to a structure that was returned from a previous call to alloc_struct. To write data into a structure that was not previously allocated using alloc_struct, the argument str can be a sequence containing two atoms, the address in memory where the structure is located, and a structure handle that was returned by define_struct. The sequence should have the format; {addr,str}.
elem: By providing the string-id of one of the elements within the structure to be written, or in the case of nested structures, a sequence of string-ids, a single element within a structure can be written. In the case of an array of structures, and integer can be provided to specify the indice within the array that is to be written to.
data: The argument data should represent the type, number, and size of the value or values that are to be poked into memory. In the case of nested structures, the data for the nested structure should also be nested within the object data.
Return: This procedure does not return a value.