Documentation for Win32lib v0.70.18
Table of Contents

Memory management

Routines to allocate, use, and release of Random Access Memory (RAM).


Normally, a Euphoria program doesn't have to worry about this as it is handled quietly in the background. However, when working with external systems, such as the Windows API, the coder often needs to explicitly manage RAM as resource, primarily when sharing data between your application and Windows.
/n

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:

  • It returns the size of the structure, or at least its fixed stub size (read below).
  • As a side effect, it registers the structure template you just defined and cleans up so as to possibly start another structure definition later. In addition, you can define a structure identifier. This is returned by w32define_this_struct(), and is used by the bulk load/store routines. w32define_this_struct() is also useful to define shorter variants of a maximal structure. For instance, Windows XP uses more fields than Windows 98 in some cases. You don't need to define two different structures: just insert a w32define_this_struct() call at the "break points" so as to retrieve structure ids for the various versions.
    Variable length members. Some Windows API structure include arrays or strings of variable length. In that case, only the length of the part of the structure preceding the first variable length field is known and reported. The library supports a wide range of schemes and special alignment fields to deal with these beasts. Please read further under w32allot().
    Unions are also supported. The only limitation is that no alternative field description can be a union itself. Read further under w32define_union().

  • func isFieldOf(sequence field,sequence struct_type)    Determines whether field is a field of the struct_type structure type.
  • proc setPreProcessDataIn(sequence id,integer rid)    Sets up a routine to preprocess data fed to w32to_memory() for a given type of structure.
  • proc setStartWithSize(sequence struct_id)   Indicates to w32to_memory() that, when filling a structure of this type, its size should be plugged in as the first field.
  • func w32acquire_handle(atom flags,integer size)   Gets a Windows memory handle to memory of the requested size.
  • func w32acquire_mem( atom Owner, object structure )   Allocate memory for structure, and initialize to zero.
  • func w32address( structure address, field )    Get address of field in structure.
  • func w32allot( object FldDefn )   Allocate space in structure for a new field.
  • func w32allotted_buffer(hDefn)    Returns a modified field so as to w32fetch() the address of the supplied buffer
  • func w32allotted_handle(hDefn)   Returns the address of the supplied handle, but with fetch instructions
  • func w32allotted_length(hDefn)    Returns a modified field so as to w32fetch() the length of the supplied buffer
  • func w32allotted_size()   Return allocate size of structure, and reset for new structure.
  • func w32allotted_sofar()   Return size allotted sofar to the structure
  • func w32buffer_address(atom struct,sequence bDefn)    Returns the address of the buffer, while w32fetch would return the string stored there.
  • func w32buffer_length(atom struct,sequence bDefn)   Returns the stored length of the buffer.
  • proc w32copy_field(atom struct,sequence s,atom origin)    Copies contents of the field of the structure at origin described by s to struct.
  • proc w32copy_struct(atom struct,sequence id,atom origin)    Copies the structure whose base address is origin to struct, its type being id.
  • func w32define_this_struct()   Returns an identifier for the currently defined structure at the current point.
  • func w32define_union(sequence fields,integer selector, integer data_assess)    Defines a union structure: the structure is any of the ones given in fields.
  • func w32fetch( structure address, field )   Fetch field from structure.
  • func w32from_memory(atom struct,sequence s)   Returns the fields of a structure.
  • func w32from_memoryEx(atom struct,sequence s,integer level)   Returns the fields of a structure.
  • func w32handle_to_memory(atom handle)   Gives current task exclusive access to the referenced memory block.
  • func w32llSetAbort( i )   Possibly sets the routine id of an Abort routine.
  • func w32manage_mem( atom Owner, object Address)   Records an acquired memory for garbage collection.
  • func w32new_memset( )   Allocates a unique id for a memory set.
  • func w32peek2(object pos)   Retrieves a sequence of double byte encoded characters as a regular sequence
  • func w32peek_string( address )   Get sequence from address holding C-style string.
  • func w32peek_string16(atom addr)    Returns a 0000 terminated DBCS encoded string starting at addr.
  • proc w32poke_words(atom at,object words)    Poke one or more words at at.
  • func w32realise(atom struct,integer flag)   Rebuilds a contiguous memory structure, possibly discarding virtual info
  • proc w32release_handle(atom handle,integer flag)   Releases the referenced memory block, and optionally frees it.
  • proc w32release_mem( atom structure )    Returns the memory allocated by w32acquire_mem() back to the system.
  • proc w32set_memory(atom struct,sequence id,sequence data)    Performs the same function as w32to_memory(), but stores data at address struct.
  • func w32specialise(sequence union,object variant)   Returns a structure field descriptor that can be translated into an actual variant of a union.
  • proc w32store( structure, field, value )   Store a value into a structure.
  • func w32to_memory(sequence id,sequence data)   Initialises memory structiure of given type with supplied data.
  • func w32to_memoryEx(atom mem,sequence id,sequence data,integer flag)   Initialises memory structiure of given type with supplied data.
  • Var w32UsingSafeCode   Determines whether or not the 'safe' versions of peek and poke are used.

    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    isFieldOf
    (sequence field,sequence struct_type)

    Determines whether field is a field of the struct_type structure type.

    Returns: (INTEGER) w32True if the field belongs to the structure, else w32False.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    setPreProcessDataIn
    (sequence id,integer rid)

    Sets up a routine to preprocess data fed to w32to_memory() for a given type of structure.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    setStartWithSize
    (sequence struct_id)

    Indicates to w32to_memory() that, when filling a structure of this type, its size should be plugged in as the first field.

    Category: Memory management

    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:

  • ID_OSVERSIONINFOEX
  • ID_INITCOMMONCONTROLSEX
  • ID_WINDOWINFO
  • ID_MENUITEMINFO
  • ID_WNDCLASSEX
  • ID_SCROLLINFO
  • ID_COLORDLG
  • ID_DOCINFO
  • ID_DRAWTEXTPARAMS
  • ID_OPENFILENAME
  • ID_BITMAPINFOHEADER
  • ID_PAGESETUPDLG
  • ID_CHARFORMAT
  • ID_TOOLINFO
  • ID_REBARBANDINFO
  • ID_OUTLINETEXTMETRIC
  • ID_PARAFORMAT

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32acquire_handle
    (atom flags,integer size)

    Gets a Windows memory handle to memory of the requested size.

    Returns: (ATOM) Handle to memory.

    Category: Memory management

    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.

  • Here are the known flags to or tohether as required.

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32acquire_mem
    ( atom Owner, object structure )

    Allocate memory for structure, and initialize to zero.

    Returns: Address of allocated memory, or array of such addresses.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32address
    ( structure address, field )

    Get address of field in structure.

    Returns: ATOM: Address of the field in the structure.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32allot
    ( object FldDefn )

    Allocate space in structure for a new field.

    Returns: SEQUENCE: Definition of allotted memory.

    Category: Memory management

    FldDefn is either:

  • a number of bytes to allocate,
  • one of the predefined datatypes (listed below),
  • a structure identifier, predefined or returned by w32define_this_struct(),
  • a 2-element sequence containing a repeat count and any of the above.

    The repeat count is either:

  • a positive number;
  • a field definition previously returned by this function. In that case, the length of the array is assumed to equal the contents of the supplied field in the structure;
  • a sequence holding a sequence of bytes. The length of the array is not known, and its end is marked by this sequence of bytes. For instance, a C-string could be defined using w32allot({{{0}},Byte}).
  • a sequence holding a sequence holding a sequence made of two routine_ids. The length of the array is not known, and the routine_ids are respectively used to determine and mark when an item is the last item. If a number of bytes is supplied, the field is aligned to the next 32-bit boundary before allocation.
    If a {{{id_check_last,id_set_last}}} is supplied as a length, id_check_last is the routine_id of a function that takes an atom and returns zero if not last item, nonzero for last item (each item is examined in turn). id_set_last is the routine_id of a procedure that takes a single atom as argument (the address of the item at which to apply some end mark).

    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:

  • Byte: 8 bit value
  • Int8: Signed 8 bit integer, same as Byte.
  • Word: 16 bit value
  • Integer: 16 bit value, same as Word
  • Int16: 16 bit value, same as Word
  • Long: Signed 32 bit value
  • DWord: 32 bit value, same as Long
  • Int32: 32 bit value, same as Long
  • UInt: Unsigned 32 bit value.
  • Ptr: 32 bit value, same as UInt
  • ULong: 32 bit value, same as UInt
  • Hndl: 32 bit value,
  • HndlAddr: 32 bit value, a pointer to a pointer
  • Lpsz: Long pointer (32 bits) to zero delimited string
  • Strz: Fixed size buffer that holds a zero-delim string
  • Single: 32-bit IEEE floating point value
  • Float: Same as Single
  • Double: 64-bit IEEE floating point value
  • Upsz: Long pointer to 0000 delimited UTF-16 encoded string
  • Ustrz: Fixed size buffer that holds a 0000 delimited DBCS encoded string
  • aszText: An /i actual 0 terminated string
  • uszText: An /i actual 0000 terminated UTF-16 encoded string
  • asBuffer: A pointer to an UTF-8 encoded string, followed by a dword storing its length
  • usBuffer: A pointer to an UTF-16 encoded string, followed by a dword storing its length in TCHARs
  • Align: A pseudo field that forces the next field address to be aligned on a multiple of the size passed. If no size is provided, 8 is assumed.
  • AlignRel: A pseudo field that forces the next field offset to be aligned on a multiple of the size passed. If no size is provided, 4 is assumed.
  • ByteFill: An unaccessible byte. If no size is specified, 1 is assumed.
    You cannot fetch/store the contents of an Align, AlignRel or ByteFill field.
    Arrays of Strz or Ustrz are not currently supported.

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32allotted_buffer
    (hDefn)

    Returns a modified field so as to w32fetch() the address of the supplied buffer

    Returns: SEQUENCE: Handle's "fieldOffset" into a structure.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32allotted_handle
    (hDefn)

    Returns the address of the supplied handle, but with fetch instructions

    Returns: SEQUENCE: Handle's "fieldOffset" into a structure.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32allotted_length
    (hDefn)

    Returns a modified field so as to w32fetch() the length of the supplied buffer

    Returns: INTEGER: Buffer length "fieldOffset" into a structure.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32allotted_size
    ()

    Return allocate size of structure, and reset for new structure.

    Returns: INTEGER: Allotted size of structure.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32allotted_sofar
    ()

    Return size allotted sofar to the structure

    Returns: INTEGER: Allotted size of structure.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32buffer_address
    (atom struct,sequence bDefn)

    Returns the address of the buffer, while w32fetch would return the string stored there.

    Returns: (ATOM) The address of the buffer.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32buffer_length
    (atom struct,sequence bDefn)

    Returns the stored length of the buffer.

    Returns: (INTEGER) The length of the buffer.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    w32copy_field
    (atom struct,sequence s,atom origin)

    Copies contents of the field of the structure at origin described by s to struct.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    w32copy_struct
    (atom struct,sequence id,atom origin)

    Copies the structure whose base address is origin to struct, its type being id.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32define_this_struct
    ()

    Returns an identifier for the currently defined structure at the current point.

    Returns: (SEQUENCE) A structure identifier.

    Category: Memory management

    {{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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32define_union
    (sequence fields,integer selector, integer data_assess)

    Defines a union structure: the structure is any of the ones given in fields.

    Returns: (SEQUENCE) A structure id, which you can use almost like any other.

    Category: Memory management

    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 entry 
    

    integer 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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32fetch
    ( structure address, field )

    Fetch field from structure.

    Returns: OBJECT: Field from a structure.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32from_memory
    (atom struct,sequence s)

    Returns the fields of a structure.

    Returns: (SEQUENCE) List of field values.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32from_memoryEx
    (atom struct,sequence s,integer level)

    Returns the fields of a structure.

    Returns: (SEQUENCE) List of field values.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32handle_to_memory
    (atom handle)

    Gives current task exclusive access to the referenced memory block.

    Returns: (ATOM) Pointer to memory block.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32llSetAbort
    ( i )

    Possibly sets the routine id of an Abort routine.

    Returns: The previous value set.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32manage_mem
    ( atom Owner, object Address)

    Records an acquired memory for garbage collection.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32new_memset
    ( )

    Allocates a unique id for a memory set.

    Returns: ATOM: An id for a new memory set (memset).

    Category: Memory management

    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 ss
    

    ss = 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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32peek2
    (object pos)

    Retrieves a sequence of double byte encoded characters as a regular sequence

    Returns: (OBJECT) A sequence where each element represents two contiguous bytes, lowest weight at lowest address.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32peek_string
    ( address )

    Get sequence from address holding C-style string.

    Returns: SEQUENCE: containing the C-style string.

    Category: Memory management

    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 s
    

    s = 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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32peek_string16
    (atom addr)

    Returns a 0000 terminated DBCS encoded string starting at addr.

    Returns: (SEQUENCE) A sequence of integers, all of them in the 0-65535 range.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    w32poke_words
    (atom at,object words)

    Poke one or more words at at.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32realise
    (atom struct,integer flag)

    Rebuilds a contiguous memory structure, possibly discarding virtual info

    Returns: (SEQUENCE) {Address of rebuilt structure,size of the structure}.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    w32release_handle
    (atom handle,integer flag)

    Releases the referenced memory block, and optionally frees it.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    w32release_mem
    ( atom structure )

    Returns the memory allocated by w32acquire_mem() back to the system.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    w32set_memory
    (atom struct,sequence id,sequence data)

    Performs the same function as w32to_memory(), but stores data at address struct.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32specialise
    (sequence union,object variant)

    Returns a structure field descriptor that can be translated into an actual variant of a union.

    Returns: (SEQUENCE) A field descriptor.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [proc]
    w32store
    ( structure, field, value )

    Store a value into a structure.

    Category: Memory management

    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:

  • Using an atom stores the values 0 and 0;
  • Storing a pair {{},{u,v}}, where u and v are atoms, store these values without any reference to a string.
    Example:

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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32to_memory
    (sequence id,sequence data)

    Initialises memory structiure of given type with supplied data.

    Returns: (ATOM) Address of initialised structure.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [func]
    w32to_memoryEx
    (atom mem,sequence id,sequence data,integer flag)

    Initialises memory structiure of given type with supplied data.

    Returns: (ATOM) Address of initialised structure.

    Category: Memory management

    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


    Documentation for Win32lib v0.70.18
    Table of Contents

    [Var]
    w32UsingSafeCode

    Determines whether or not the 'safe' versions of peek and poke are used.

    Category: Memory management

    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