ftp.alaska-software.com/2014.06.ftp.alaska-software.com.tar/ftp.alaska-software.com/acsn/bapread.me

Text File | 2001-03-28 | 5KB | 146 lines

The Binary Access Package for Xbase++
=====================================
Version 1.5        03/29/2001

Author: Gernot Trautmann

Provides functions to make any DllCall or C-API function call which
requires structures possible.

Available function groups:

1. To create and extract structures:
------------------------------------
Theses functions are used to setup structures which can be manipulated
by non-Xbase++ functions. The structures may conatin pointers to
character buffers or even to other structures. It is necessary to
call BaInit(), BaStruct() and BaExtract() even if the return values
are not of any interest.


aBin := BaInit(nSize)
        =======
    Creates the array aBin and prepares to hold nSize structure
    members. Never touch the array.

lRet := BaStruct(aBin, [@]xValue)
        ======
    Adds one value to the structure. Available types:
    BOOL, NUMERIC, CHARACTER; per value or per reference.
    The creation order is the order of the members in the structure.
    Values passed by reference will be locked.
    If lret is .F., a failure with xValue occured. You should
    do sufficient calls to BaExtract() to unlock all locked values.

cBin := BaAccess(aBin)
        =========
    Now use cBin to pass the binary structure to the external function.
    If you pass it by reference, you may get updated values after
        extracting and therefore you must pass cBin back to BaExtract
        as its second parameter before.

xVal := BaExtract(aBin [, cBin] )
    ==========
    Extracts one value from the structure. You have to call
    it in the same order as the BaAdd-calls are placed.
    Values passed by reference will be unlocked.
        If you pass cBin, this value is used in all subsequent calls
        to extract from.
        After extracting all members you can free the array (aBin := NIL)
        or reuse it by using BaInit.


2. To cast return values:
-------------------------
These functions are used to interprete return values of DllCall()'s,
since DllCall() returns only numeric values.

cVal := StringOf(nVal,[nLength])
    ========
    If an external call returns a pointer to a character and this
    piece of memory is still available, you may use this function
    to create an Xbase++-character with the value where nVal
    points to. If no nLength is given, the buffer is copied up to
        the first 0-character.

nVal :=    WordOf(nVal)
    ======
    Corrects bits if an external call returns 16bit values to an
    Xbase++ numerical.

nVal :=    ByteOf(nVal)
    ======
    Corrects bits if an external call returns 8bit values to an
    Xbase++ numerical.


lVal := LogicOf(nVal)
    =======
    Converts a numeric to a logic value. The value 0 means .F.,
        others mean .T.


3. To extract values from binary (structered) buffers:
------------------------------------------------------
These functions are used to handle structures returned as a return
value or to extract values out of a structured buffer which was not
created using BaStruct().


cVal := BaExValue( cStruct, nPlace, nLength)
        =========
        Cut out a piece of the structure buffer. If the buffer
        was returned by a previous DllCall(), you must call
        cStruct := StringOf(nRet) prior to executing this function.


nAdr := BaExPointer( cStruct, nPlace)
    ===========
    Extract a pointer out of a structure buffer. It does the
        same as BaExValue(), but also converts the value to a
        numeric using Bin2U().


nAdr := BaDereference( nAddr)
    =============
    Interpretes nAddr as a pointer to a pointer, and returns
        the numeric value of the dereferenced pointer.
        C declaration: char **ptr.


nCnt := BaEvalPtrArray( cStruct, nPlace, cbEval)
    ==============
    Interpretes cStruct.nPlace as an array of pointers, dereferences
        the pointer and calls Eval( cbEval, nDerefPtr). The termination
        is done by a NULL pointer inside of the array.
    Returns number of Evals().


4. To create a callback function
--------------------------------
A callback function is called back while an API is under execution.
Currently, these types of callbacks are supported:

BA_CB_LPOFNHOOKPROC    - callback of Win32-API GetOpenFileName
BA_CB_ADDZIP            - callback of AddZip
BA_CB_GENERIC1          - Generic callbacks: The number designates
BA_CB_GENERIC2            the number of passed parameters, all of
BA_CB_GENERIC3            type NUMERIC, return value is NUMERIC.
BA_CB_GENERIC4            To adapt a generic callback, the Xbase++
                          passed to BaCallBack() must interprete the
                          parameters by itself, and may call a specialized
                          function. To interprete a parameter means to
                          cast to other types, like calling StringOf(par2)
                          to interprete the passed NUMERIC as an address
                          to a character.

nAdr := BaCallback( <cFuncName>, <nCallbackType>)
        =========
        The <cFuncName> is set as the current callback, which can
        only be one per thread.
        To disable/reset the callback, pass and empty string.
        The <nCallbackType> can be one of the BA_CB_xx - values
        defined in bap.ch.
        The return value is the address of the callback function
        which can be passed to the API which requires a callback
        function.