How the structure engine works. Memory structures are a set of fields. You define a structure by calling w32allot() passing the fields in sequence, and retrieving a field descriptor which can be used to access the field. When done, call the w32allotted_size(). This function does two things:
field may be a nested field, in which case the leading field only is tested./n struct_type is a structure identifier, an ID_* constant or anything created by w32define_this_struct().
See Also: setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
The preprocess routine must take a sequence and return a sequence. Preprocess routines apply to all short structures derived from/from which derives id.
See Also: isFieldOf, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
Once taken, this decision cannot be rolled back. It simply avoids repetitively specifying the size as the first data item./n The following structure identifiers are already marked for this optimisation:
See Also: isFieldOf, setPreProcessDataIn, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
This is a very low level routine.
To access the memory, you must call w32handle_to_memory(returned_handle). When you are
done with the memory operation, call the w32release_handle(returned_handle,free_also) procedure.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
The memory allocated is linked to the Owner and all the
owner's memory can be released by one call.
owner may have been returned by w32new_memset(), or it may be the address of a structure.
In both cases, releasing the owner will also release the acquired memory.
If structure is a string, it is copied to the memory
location along with a zero byte.
structure may also be a structure identifier previously returned by w32define_this_struct(). In this case, it is recommended to w32store() objects inside it rather than poke()ing them. If you attempt to poke a field whose address is not known, or to w32fetch() one that you didn't fill yet, an error will occur.
If structure is an atom, it specifies that amount of memory to acquire (a minimum of 4 bytes will always be acquired) and the memory is set to all zeros. This atom may be a predefined size specifier. Using aszText or uszText will cause 0 to be returned, since these field types have an unknown data address until actually filled.
If the second argument has the form {{count,allocation_unit}}, and count is above 0 (0 will be returned if not greater),
then the memory specified by allocation_unit will be allocated count times. In case the allocation
unit has a variable length, the whole array of positions is returned. Each allocated unit can be freed individually.
Example:
atom mset, pt, pstr-- Establish a new memory set. mset = w32new_memset() -- get enough memory to hold a UInt datatype xy = w32acquire_mem( UInt ) -- allocate a point structure pt = w32acquire_mem( mset, SIZEOF_POINT ) -- copy a Euphoria string to a 'C' string area. pstr = w32acquire_mem( mset, "My String Data" ) . . . give all the memory area in 'mset' back w32release_mem(mset)
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
This is typically used if the structure contains an array.
In this snippet, the memBitmapInfo structure contains an array of RGBQUAD colors. The array is populated with the values in the pal:
-- get the start of the rgbQuad array rgbQuad = w32address( memBitmapInfo, bmiColors )-- copy the pal to memory for i = 1 to colors do
-- store values w32store( rgbQuad, rgbRed, pal[i][1] ) w32store( rgbQuad, rgbGreen, pal[i][2] ) w32store( rgbQuad, rgbBlue, pal[i][3] ) w32store( rgbQuad, rgbReserved, 0 )
-- move to next quad rgbQuad += SIZEOF_RGBQUAD
end for
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
FldDefn is either:
The repeat count is either:
The returned allotment definition is used by w32store and w32fetch. It has the
following structure.
The definition has seven items:
A structure field, an fieldOffset, a datatype, a repeat length, a
structure type, a flag (1 if member has variable length) and a unit bytesize
Allowable types are:
Example:
constant msLeft = w32allot( Long ), msTop = w32allot( Long ), msRight = w32allot( Long ), msBottom = w32allot( Long ), ID_BARERECT = w32define_this_struct() msVelocity = w32allot( Single ), msXYZ = w32allot( {4, DWord} ), msReserved = w32allot( 5 ), msName = w32allot( Lpsz ), msBuffer = w32allot( {128, Strz} ), SIZEOF_MYSTRUCT = w32allotted_size(), ID_MYSTRUCT = w32define_this_struct()
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
w32fetch(), when given a field that represents an asBuffer or usBuffer, returns the string in the buffer. Use this function on the field, and w32fetch() will return the buffer address instead when using the returned field. This is similar to how w32allotted_handle() works.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
to get the address from the handle, rather than the handle itself.
An empty sequence is returned if the parameter was invalid.
Example:
constant hDemo = w32allot( Hndl ), pDemo = w32allotted_handle( hDemo ), SIZEOF_DEMO = w32allotted_size() . . . x = w32acquire_mem(w32new_memset(),SIZEOF_DEMO) initDEMO(x)h = w32fetch(x, hDemo) a = w32fetch(x, pDemo) -- 'h' will contain the handle, and 'a' the address from the handle.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
w32fetch(), when given a field that represents an asBuffer or usBuffer, returns the string in the buffer. Use this function on the field, and w32fetch() will return the buffer length instead when using the returned field. This is similar to how w32allotted_handle() works.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
Example:
constant rectLeft = w32allot( Long ), rectTop = w32allot( Long ), rectRight = w32allot( Long ), rectBottom = w32allot( Long ), SIZEOF_RECT = w32allotted_size()
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
Example:
constant rectLeft = w32allot( Long ), rectTop = w32allot( Long ), SIZEOF_LT = w32allotted_sofar() rectRight = w32allot( Long ), rectBottom = w32allot( Long ), SIZEOF_RECT = w32allotted_size()
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
bDefn must be a field definition defining an Lpsz, Upsz, asBuffer or usBuffer field.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
bDefn must be a field definition defining an asBuffer or usBuffer field.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
Assumes there is enough room at struct to store the structure
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
{{struct number}} is returned if not currently defining a structure. Use w32acquire_mem() to create an instance of the structure.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
The selector argument is a routine_id. The associated routine must be a function that
takes an atom as sole argument. This atom is the memory address of the structure being queried.
The function must return an integer, the index in fields of the variant form that is stored
at that address.
data_assess is a routine_id of a function that takes an object (data to store in the union)
and returns, as above, which sort of variant of the union should be used.
Example:
-- The following function returns 1 if addr points to an submenu template entry, and 2 for an item/separator entryinteger isPopup, isDataPopup function isAPopup(atom addr) return w32iff(and_bits(peek(a)+peek(a+1)*256,MF_POPUP),1,2) end function isPopup = routine_id("isAPopup")
function isDataForPopup(object x) return w32iff(atom(x),1,2) end function
isDataPopup=routine_id("isDataForPopup")
-- Now define a menu item template entry as understood by the LoadMenuIndirect() API. -- This has an option field (a word), an optional ID field (a word), and a wide char string.
constant -- define a substructure that will store both option and ID FULLMENUITEMTEMPLATE_flags = w32allot(Word), FULLMENUITEMTEMPLATE_id = w32allot(Word), SIZEOF_FULLMENUITEMTEMPLATE = w32allotted_size(), -- 4 ID_FULLMENUITEMTEMPLATE = w32define_this_struct(),
-- define the start of an entry as either a word or an item entry ID_STARTITEMTEMPLATE = w32define_union({Word,ID_FULLMENUITEMTEMPLATE},isPopup,isDataPopup),
-- Now here is the MENUITEMTEMPLATE entry structure MENUITEMTEMPLATE_flags = w32allot(ID_STARTITEMTEMPLATE), MENUITEMTEMPLATE_mtString = w32allot(Ustrz), SIZEOF_MENUITEMTEMPLATE = w32allotted_size(),
-- You may wish to access the original fields of the structure: -- define a specialised form of a STARTITEMTEMPLATE union MENUITEMENTRY = w32specialise(ID_STARTITEMTEMPLATE,ID_FULLMENUITEMTEMPLATE),
-- Now define the subfields for access MENUITEMTEMPLATE_mtOption = {MENUITEMENTRY,FULLMENUITEMTEMPLATE_flags}, MENUITEMTEMPLATE_mtID = {MENUITEMENTRY,FULLMENUITEMTEMPLATE_id}
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
Data conversion is automatic. For example, if the field is an Lpsz, a sequence containing the string will automatically be returned.
Example:
-- fetch the average character width from the text metrics structure width = w32fetch( tm, tmAveCharWidth )-- Here we get individual elements from an w32allot array. constant bCoords = w32allot( {4, Long} ) . . . x = w32fetch( rect, bCoords & 1) y = w32fetch( rect, bCoords & 2)
-- To get all the values at once sequence coords coords = w32fetch( rect, bCoords)
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
If a field is itself a structure, its address is returned. If you need actual data, use w32from_memoryEx(), which this function wraps. No values are returned for filler fields: Align, AlignRel and ByteFill.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
If a field is itself a structure, its address is returned if level is 0. Use a positive value in level to define a maximum degree of recursion. Use -1 to resolve at any depth (ie replacing an embedded structure address by a list of field values).
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
The handle must have been acquired using w32acquire_handle().
Writing data outside of the referenced memory block will very likely crash your application.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
Used to indicate if an error routine needs to be
called in the event of a catastophic error.
The error routine is assumed to be a procedure
that accepts a single sequence (typically an
message string).
Use -1 to remove the handler. Use any sequence to simply return the handler.
Example:
integer RtnID, OldID RtnID = routine_id("abortErr") OldID = w32llSetAbort(RtnID)
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
Normally this is handled automatically by w32acquire_mem() but if you are expected to manage some memory acquired by another means, such as a Windows call or a 'C' routine, you can use this to record the memory for subsequent release by w32release_mem(). If Address is a sequence, it is a sequence of addresses to manage.
Example:
atom mset, pt, pstr-- Establish a new memory set. mset = w32new_memset() -- calls a routine which returns a structure address. pt = c_func( xyz, {abc}) -- register this memory w32manage_mem(mset, pt) . . . give all the memory area in 'mset' back w32release_mem(mset)
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
A memset id is actually a machine address of a 4-bytes location. You can use this 4-byte area for anything you like, until you call w32release_mem()
Example:
atom ssss = w32new_memset() b = w32acquire_mem(ss, "All you need is love") ... w32release_mem( ss ) -- Let go of set 'ss'
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
If pos is a {address,length} sequence, a sequence is returned. If pos is a single atom, the 16-bit word at that address is returned.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
This is typically done automatically by the fetch function. Note that this will not work with UTF-16 encoded strings.
Example:
-- get a C-string from address sequence ss = w32peek_string( address )
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
words is either a single word or a sequence of them. All low words are then stored. The caller is responsible to poke into memory s/he owns.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
If you ever used w32store() on a variable length field in a structure, the targeted member was most likely relocated. Since external code expects the structure to occupy a contiguous space in memory, you have to call w32realise() to get the address of a structure with the same data, but made contiguous again. struct is the address of the structure to rebuild; memset is a memory set where to rebuild the structure; flag is zero if you don't plan to reuse the structure again, so that the old one and the support data are recycled. As always, you are responsible for freeing the returned structure. Note that, if the structure has Align fields, the created structure will use a slightly oversize memory block. The amount of slack past the end of the structure is not greater than the sum of the widths of the Align fields minus their number - usually only a few bytes.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
flag is 0 to keep the handle, and nonzero to free it.
The handle must have been acquired using w32acquire_handle().
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
If structure is a memory set id, as returned by w32new_memset(), then
all the memory owned in the memory set is returned and the memory set id
is released. That is, it cannot be reused.
If structure is a memory address returned by w32acquire_mem(), then just
that memory is released. The memory set it belonged to is still usable.
Example:
atom mset, pt, pstr-- Establish a new memory set. mset = w32new_memset() -- get enough memory to hold a UInt datatype xy = w32acquire_mem( UInt ) -- allocate a point structure pt = w32acquire_mem( mset, SIZEOF_POINT ) -- copy a Euphoria string to a 'C' string area. pstr = w32acquire_mem( mset, "My String Data" ) . . . give all the memory area in 'mset' back w32release_mem(mset)
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
No realisation is attempted at addr.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32specialise, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
union is a field descriptor whose is of an union type. The point of w32specialise() is
to give w32store() a hint about what exactly is to be stored there.
variant is either a field descriptor or a number. If a field descriptor, it must
appear in the list of fields that union can have. If a number, it is the index of the
field to choose among those defining the union.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32store, w32to_memory, w32to_memoryEx, w32UsingSafeCode
Type conversion is automatic. For example, if an Lpsz field is
used, the value is automatically converted from a sequence to a
C-style string, and the address of that string is stored in the
structure.
If field is a union, it must be specialised, so that w32store() knows how to store data.
If it is not, then the last known specialisation is used. Otherwise, you should call
w32specialise() so as to get a specialised union which w32store() can handle.
Special rules apply to the asBuffer and usBuffer types. Normally, you'd store a string in such a field. However:
-- allocate RECT structure, and populate it atom rect-- allocate the structure rect = w32acquire_mem(w32new_memset(), SIZEOF_RECT )
-- store values into the structure w32store( rect, rectLeft, x1 ) w32store( rect, rectTop, y1 ) w32store( rect, rectRight, x2 ) w32store( rect, rectBottom, y2 )
-- Here we store individual elements to an w32allot array. constant bCoords = w32allot( {4, Long} ) . . . w32store( rect, bCoords & 1, Col) w32store( rect, bCoords & 2, Row)
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32to_memory, w32to_memoryEx, w32UsingSafeCode
id is a structure identifier, data is a sequence of field contents.
If there are variable length/position members, use w32to_memoryEx() instead.
If supplied data is shorter than expected, trailing zeroes are automatically stored in
the corresponding fields.
This function supersedes most of the struct_XXX() functions, at least those which don't
process their arguments.
When structures start with the structure size, this value is automatically prepended to
data, so that you need not bother with it.
Align, ByteFill and AlignRel fields are ignored, you should not to supply filler values.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memoryEx, w32UsingSafeCode
mem is the memory set to allocate from, id is a structure identifier, data is a sequence of field contents.
If flag is zero, a realised structure (see w32realise()) will be created, otherwise,
a virtual structure addresss will be returned. The flag is ignored if there are no
variable length/position members. w32to_memory() wraps this function with flag=0.
If supplied data is shorter than expected, trailing zeroes are automatically stored in
the corresponding fields.
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32UsingSafeCode
This is primarily as debugging aid. You only need to set this if you suspect that your program is causing memory corruptions or accessing strange locations.
Set this to zero to turn off the safe versions..
The initial setting is 0. That is, the safe versions are not being used.
Example:
--Ensure I can change RAM safely w32UsingSafeCode = 1 l_SafePoke4( adr, 0)
See Also: isFieldOf, setPreProcessDataIn, setStartWithSize, w32acquire_handle, w32acquire_mem, w32address, w32allot, w32allotted_buffer, w32allotted_handle, w32allotted_length, w32allotted_size, w32allotted_sofar, w32buffer_address, w32buffer_length, w32copy_field, w32copy_struct, w32define_this_struct, w32define_union, w32fetch, w32from_memory, w32from_memoryEx, w32handle_to_memory, w32llSetAbort, w32manage_mem, w32new_memset, w32peek2, w32peek_string, w32peek_string16, w32poke_words, w32realise, w32release_handle, w32release_mem, w32set_memory, w32specialise, w32store, w32to_memory, w32to_memoryEx