Version: 2.0d6
Release Date: Tuesday, October 14, 1997
Expires no later than: December 31, 1997
Important: THIS DOCUMENTATION IS INCOMPLETE AND PROBABLY A BIT INACCURATE
It is subject to change as the API matures.
Feedback and contributions are encouraged:
grantcgi@list.nisto.com
or grant@achilles.net
Be aware that any of the functions which return a CGIErr may return
CGIErr_Unimplemented if the function has not been implemented for the
type of plug-in or application you are compiling (e.g., some services
are only available to plug-ins, or specific types of plug-ins, while
others may be only available to CGIs).
Most of the CGI API functions require an APIData structure to be
passed in to them. You should never have to directly access or modify
the contents of that structure.
The framework has its own memory handling system. This means that
allocation and deallocation of memory blocks should only be done
through the Framework's API.
The CGI API functions for memory handling correspond directly with the
MacOS memory functions. So, if you understand Mac memory handling, you
shouldn't have much to learn here.
If you are not familiar with Mac memory handling you should read
"Inside Macintosh: Memory". In the mean time, note that 'NewPtr' is
pretty much equivalent to 'malloc' and 'DisposePtr' is pretty much
equivalent to 'free'. Additionally, it's important to note that
Handles are pointers to pointers and that *theHandle may get moved by
the system so you have to lock it down (HLock/HUnlock) when you need
to keep it in one place for a while.
You should exercise caution when trying to make calls to grow memory
allocations when using this framework. In general, you should instead
allocate new blocks and copy the old data into them.
Most Mac Toolbox memory handling calls should probably not be used
within the context of this framework (ANSI C memory calls should not
be used, either). The following are those which should be considered
'off-limits' (one's with equivalent functions in the CGI framework are
marked with a '*'):
*DisposeHandle
*DisposePtr
EmptyHandle
*GetHandleSize
*GetPtrSize
HPurge
HandAndHand
HandToHand
NewEmptyHandle
NewEmptyHandleSys
*NewHandle
*NewHandleClear
NewHandleSys
NewHandleSysClear
*NewPtr
*NewPtrClear
NewPtrSys
NewPtrSysClear
PtrAndHand
PtrToHand
PtrZone
ReallocateHandle
RecoverHandle
SetHandleSize
SetPtrSize
If you need to use one of these, please contact me <grant@kagi.com> or
write a custom wrapper for the function (which takes into account the
special memory handling of the framework).
These functions correspond to their Mac toolbox equivalents.
CGIErr CGINewHandle ( const APIData apidata, long theSize, Handle *newHandle )
CGIErr CGINewHandleClear ( const APIData apidata, long theSize, Handle *newHandle )
CGIErr CGINewPtr ( const APIData apidata, long theSize, Ptr *newPtr )
CGIErr CGINewPtrClear ( const APIData apidata, long theSize, Ptr *newPtr )
CGIErr CGIDisposeHandle ( const APIData apidata, Handle theHandle )
CGIErr CGIDisposePtr ( const APIData apidata, Ptr thePtr )
CGIErr CGIGetHandleSize ( const APIData apidata, Handle theHandle, UInt32 *outSize )
Get "the logical size of the relocatable block corresponding to a handle."
outSize
CGIErr CGIGetPtrSize ( const APIData apidata, Ptr thePtr, UInt32 *outSize )
Get "the logical size of the nonrelocatable block corresponding to a pointer."
outSize
Boolean CGIDebugPtr ( APIData apidata, Ptr thePtr )
Returns true if there's a detected problem with the Ptr.
Important: Only use this function on Ptrs allocated by the framework.
Boolean CGIDebugHandle ( APIData apidata, Handle theHandle )
Returns true if there's a detected problem with the Handle.
Important: Only use this function on Handles allocated by the framework.