This document contains reference information for most of the GEOS system routines. You may look up information in this and other GEOS SDK documentation by consulting the index. If, instead, you wish to browse this reference, you may choose one of the links below; the text of each is the name of the first routine documented on its page of the document.
AccessPointCommit() ...
AccessPointGetStringPropertyBlock() ...
ArrayQuickSort() ...
CCB() ...
CFatalError() ...
ChunkArrayDelete() ...
ChunkArrayElementToPtr() ...
ChunkArrayGetCountHandles() ...
ChunkArraySort() ...
ClipboardClearQuickTransferNotification() ...
ClipboardQueryItem() ...
ClipboardSetQuickTransferFeedback() ...
ConstructOptr() ...
ContactGetDBHandle() ...
ContactMatchNumber() ...
DataStoreCreate() ...
DataStoreDiscardRecord() ...
DataStoreGetFieldChunk() ...
DataStoreGetRecordCount() ...
DataStoreNewRecord() ...
DataStoreSetField() ...
DBAlloc() ...
DBDeref() ...
DBLock() ...
DiskCheckInUse() ...
DiskForEach() ...
DiskGetDrive() ...
DiskSave() ...
DriveGetDefaultMedia() ...
EC() ...
ECCheckHugeArray() ...
ECCheckProcessHandle() ...
ECVMCheckVMBlockHandle() ...
ElementArrayDelete() ...
ElementArrayRemoveReference() ...
FatalError() ...
FileCreate() ...
FileDeleteDir() ...
FileEnum() ...
FileEnumLocateAttr() ...
FileGetDiskHandle() ...
FileOpen() ...
FileRename() ...
FileSetHandleExtAttributes() ...
FileTruncate() ...
FloatFloatToAscii() ...
FoamDBAddFieldToRecord() ...
FoamDBGetCurrentRecordID() ...
FoamDBResumeUpdates() ...
FormatIDFromManufacturerAndType ...
GCNListAdd() ...
GCNListSend() ...
GenCopyChunk() ...
GeodeAllocQueue() ...
GeodeGetAppObject() ...
GeodeLoadDGroup ...
GeoFree() ...
GrApplyTranslation() ...
GrClearBitmap() ...
GrDestroyBitmap() ...
GrDrawCurve() ...
GrDrawLine() ...
GrDrawRect() ...
GrDrawRoundRect() ...
GrEndGString() ...
GrFillEllipse() ...
GrGetAreaColor() ...
GrGetDefFontID() ...
GrGetLineMask() ...
GrGetPtrRegBounds() ...
GrInitDefaultTransform() ...
GrNewPage() ...
GrSDivDWFByWWF() ...
GrSetClipPath() ...
GrSetLineAttr() ...
GrSetPalette() ...
GrSetTextMode() ...
GrTestPointInPath() ...
GrUDivWWFixed() ...
GSCloseSubPath() ...
GSDrawEllipse() ...
GSDrawSpline() ...
GSFillBitmap() ...
GSMoveTo() ...
GSSetCustomLineMask() ...
GSSetLineEnd() ...
GSSetSubscriptAttr() ...
HAL_COUNT() ...
HandleV() ...
HugeArrayDestroy() ...
HugeArrayPrev() ...
IACPProcessMessage() ...
ImpexExportToMetafile() ...
InitFileEnumStringSection() ...
InitFileReadStringBlock() ...
InitFileRevert() ...
InkDBGetDisplayInfo() ...
InkFolderGetNumChildren() ...
InkNoteGetCreationDate() ...
InkNoteSetModificationDate() ...
isalnum() ...
LMemAlloc() ...
LMemGetChunkSize() ...
LMemReAlloc() ...
LocalAsciiToFixed() ...
LocalCustomParseDateTime() ...
LocalGeosToCodePage() ...
LocalLexicalValue() ...
MailboxAcknowledgeMessageReceipt() ...
MailboxGetBodyFormat() ...
MailboxGetVMFile() ...
MakeWWFixed() ...
MemAlloc() ...
MemDowngradeExclLock() ...
MemLock() ...
MemModifyFlags() ...
MemThreadGrab() ...
MemUnlock() ...
ModemAnswerCall() ...
ModemSetMessageDataNotify() ...
NameArrayAdd() ...
NameArrayFind() ...
ObjCompFindChildByOptr() ...
ObjCompProcessChildren() ...
ObjDeref() ...
ObjDoRelocation() ...
ObjFreeChunk() ...
ObjInitDetach() ...
ObjIsClassADescendant() ...
ObjResizeMaster() ...
ObjVarAddData() ...
ObjVarDeleteDataAt() ...
ObjVarScanData() ...
ParallelClose() ...
PCCOMABORT() ...
qsort ...
realloc() ...
SerialGetFormat() ...
SGC_MACHINE ...
SocketBind() ...
SocketClose() ...
SocketGetAddressController() ...
SocketInterrupt() ...
SocketRemoveLoadOnMsg() ...
SoundAllocMusic() ...
SoundFreeMusic() ...
SoundPlayToMusicStream() ...
SpeedDialGetNumber() ...
SpoolGetNumPaperSizes() ...
SpoolModifyPriority() ...
StreamOpen() ...
StreamWrite() ...
SysGetPenMode() ...
SysShutdown() ...
TextSearchInString() ...
ThreadAttachToQueue() ...
ThreadGetError() ...
ThreadPSem() ...
TimerSleep() ...
TocNameArrayFind() ...
TokenDefineToken() ...
TokenLoadMonikerBuffer() ...
TokenLoadTokenChunk() ...
UserAllocObjBlock ...
UserRemoveAutoExec() ...
UtilAsciiToHex32() ...
VirtualSerialSetFormat() ...
VMClose() ...
VMGetMapBlock() ...
VMPreserveBlocksHandle() ...
WinAckUpdate() ...
WinGeodeSetInputObj() ...
WinScroll() ...
void AccessPointCommit();
This routine commits any access point data changes to permanent storage. The AccPnt library normally calls this routine when the device shuts down; applications thus need not call it. If you're trying to track down a bug which is likely to cause the system to crash before the changes can be committed, you may find this routine useful.
Include: accpnt.goh
void AccessPointCompareStandardProperty( AccessPointStandardProperty prop, char *str);
This routine compares the passed string to the name of the passed property.
Include: accpnt.goh
word AccessPointCreateEntry( word loc, AccessPointType apt);
This routine creates a new access point.
After calling this routine, you will probably want to use the
AccessPointSet...Property()
routines to provide some information about the new access point.
Pass:
AccessPointType
of the new access point. APT_INTERNET for an ISP, APT_TERMINAL for a dialup, etc.Return: ID number of the new access point.
Include: accpnt.goh
See Also: AccessPointSetStringProperty()
,
AccessPointSetIntegerProperty()
.
Boolean AccessPointDestroyEntry( word id);
This routine deletes an access point's information. If it returns non-zero, there was an error. (Perhaps the access point was locked or did not exist.)
Include: accpnt.goh
Boolean AccessPointDestroyProperty( word id, char *prop);
This routine destroys one of an access point's properties.
Pass:
AccessPointStandardProperty
value or a pointer to a buffer containing the property's name.Return: Zero if there was no error, true if there was (no such access point, no such property, access point locked).
Include: accpnt.goh
See Also: AccessPointSetStringProperty()
,
AccessPointSetIntegerProperty()
.
ChunkHandle AccessPointGetEntries( MemHandle mh, ChunkHandle chunk, AccessPointType apt);
This routine gets a chunk array of all the access point IDs corresponding to access points of a given
AccessPointType
. Each element of the arraay is word-sized.
Pass:
AccessPointType
we're interested in: APT_INTERNET, APT_TERMINAL, etc.
Return:
The
ChunkHandle
of the chunk array.
Include: accpnt.goh
Boolean AccessPointGetIntegerProperty( word id, char *prop, int *val);
This routine retrieves the value of one of an access point's property, representing the value as an integer.
Pass:
AccessPointStandardProperty
value or a pointer to a buffer containing the property's name.Return: Zero if there was no error, true if there was (no such access point, no such property).
Include: accpnt.goh
See Also: AccessPointGetStringPropertyBuffer()
,
AccessPointGetStringPropertyBlock()
.
BooleanAccessPointGetStringPropertyBlock( word id, char *prop, MemHandle *data, int *datalen);
This routine retrieves the value of one of an access point's property, returning the value as a string in a block of memory.
Pass:
AccessPointStandardProperty
value or a pointer to a buffer containing the property's name.
MemHandle
of block to fill with value (pass zero to request that the block be allocated).Return: Zero if there was no error, true if there was (no such access point, no such property).
Include: accpnt.goh
See Also: AccessPointGetStringPropertyBuffer()
,
AccessPointGetIntegerProperty()
.
Boolean AccessPointGetStringPropertyBuffer( word id, char *prop, char *buf, int *datalen);
This routine retrieves the value of one of an access point's property, returning the value as a string in a buffer of memory.
Pass:
AccessPointStandardProperty
value or a pointer to a buffer containing the property's name.Return: Zero if there was no error, true if there was (no such access point, no such property).
Include: accpnt.goh
See Also: AccessPointGetStringPropertyBlock()
,
AccessPointGetIntegerProperty()
.
AccessPointType AccessPointCommit( word id);
This routine returns the type of an access point: APT_INTERNET, APT_TELNET, etc.
Include: accpnt.goh
Boolean AccessPointInUse (word id);
If the access point with the ID id is being used by a connection, then this routine returns TRUE
(non-zero); otherwise, it returns FALSE
(zero).
Include: accpnt.goh
Boolean AccessPointIsEntryValid( word id);
This routine returns zero if the passed access point does not exist; it returns non-zero if it does exist.
Include: accpnt.goh
void AccessPointLock( word id);
This routine locks an access point, preventing changes to it.
Include: accpnt.goh
See Also: AccessPointUnlock()
.
Boolean AccessPointSetIntegerProperty( word id, char+ *prop, int val);
This routine sets the value of one of an access point's properties to an integer.
Pass:
AccessPointStandardProperty
value or a pointer to a buffer containing the property's name.Return: Zero if there was no error, true if there was (no such access point, access point locked).
Include: accpnt.goh
See Also: AccessPointSetStringProperty()
.
Boolean AccessPointSetStringProperty( word id, char *prop, char *val);
This routine sets the value of one of an access point's properties to a string.
Pass:
AccessPointStandardProperty
value or a pointer to a buffer containing the property's name.Return: Zero if there was no error, true if there was (no such access point, access point locked).
Include: accpnt.goh
See Also: AccessPointSetIntegerProperty()
.
void AccessPointUnlock( word id);
This routine unlocks an access point that was previously locked.
Include: accpnt.goh
See Also: AccessPointLock()
.
void ArrayQuickSort( void *array, /* Pointer to start of array */ word count, /* Number of elements in array */ word elementSize, /* Size of each element (in bytes) */ word valueForCallback, /* Passed to callback routine */ QuickSortParameters *parameters);
This routine sorts an array of uniform-sized elements. It uses a modified QuickSort algorithm, using an insertion sort for subarrays below a certain size. The routine calls a callback routine to actually compare elements.
ArrayQuickSort()
is passed five arguments: A pointer to the first element of the array, the number of elements in the array, the size of each element in bytes, a word of data (which is passed to all callback routines), and a pointer to a
QuickSortParameters
structure.
Before
ArrayQuickSort()
examines or changes any element, it calls a locking routine specified by the
QuickSortParameters
structure. This routine locks the element, if necessary, and takes any necessary prepatory steps. Similarly, after
ArrayQuickSort()
is finished with a routine, it calls an unlocking routine in the
QuickSortParameters
. Each of these routines is passed a pointer to the element and the word of callback data which was passed to
ArrayQuickSort()
.
The sort routine does not compare elements. Rather, it calls a comparison callback routine specified by the
QuickSortParameters
. This callback routine should be declared _pascal. Whenever
ArrayQuickSort()
needs to compare two elements, it calls the callback routine, passing the addresses of the elements and the
valueForCallback
word which was passed to
ChunkArraySort()
. The callback routine's return value determines which element will come first in the sorted array:
el1
ought to come before
el2
in the sorted array, the callback routine should return a negative integer.
el1
ought to come after
el2
in the sorted array, the callback routine should return a positive integer.
el1
comes before or after
el2
in the array, the callback routine should return zero.Include: chunkarr.h
Tips and Tricks: You may need to sort an array based on different criteria at different times. The simplest way to do this is to write one general-purpose callback routine and have the
valueForCallback
word determine how the sort is done. For example, the same callback routine could sort the array in ascending or descending order, depending on the
valueForCallback
.
Be Sure To: Lock the array on the global heap (unless it is in fixed memory).
Warnings: Do not have the callback routine do anything which might invalidate pointers to the array. For example, if the array is in a chunk, do not resize the chunks or allocate other chunks in the same LMem heap.
See Also: QuickSortParameters
,
ChunkArraySort()
.
VMBlockHandle BlockFromTransferBlockID(id); TransferBlockID id;
This macro extracts the VMBlockHandle from a
TransferBlockID
.
TransferBlockID BlockIDFromFileAndBlock(file, block); VMFileHandle file; VMBlockHandle block;
This macro creates the dword type
TransferBlockID
from a VMFileHandle and a VMBlockHandle.
extern void *_pascal bsearch( const void *key, const void *array, word count, word elementSize, PCB(int, compare, (const void *, const void *)));
This is a standard binary search routine. The callback routine must be declared _pascal.
void * calloc( word n, /* number of structures to allocate */ size_t size); /* size of each structure in bytes */
The
malloc()
family of routines is provided for Standard C compatibility. If a geode needs a small amount of fixed memory, it can call one of the routines. The kernel will allocate a fixed block to satisfy the geode's
malloc()
requests; it will allocate memory from this block. When the block is filled, it will allocate another fixed malloc-block. When all the memory in the block is freed, the memory manager will automatically free the block.
When a geode calls
calloc()
, it will be allocated a contiguous section of memory large enough for the specified number of structures of the specified size. The memory will be allocated out of its malloc-block, and the address of the start of the memory will be returned. The memory will be zero-initialized. If the request cannot be satisfied,
calloc()
will return a null pointer. The memory is guaranteed not to be moved until it is freed (with
free()
) or resized (with
realloc()
). When GEOS shuts down, all fixed blocks are freed, and any memory allocated with
calloc()
is lost.
Tips and Tricks: You can allocate memory in another geode's malloc-block by calling
GeoMalloc()
. However, that block will be freed when the other geode exits.
Be Sure To: Request a size small enough to fit in a malloc-block; that is, the size of the structure times the number of structures requested must be somewhat smaller than 64K.
Warnings: All memory allocated with
calloc()
is freed when GEOS shuts down.
See Also: malloc()
,
free()
,
GeoMalloc()
,
realloc()
.
#define CCB(return_type, pointer_name, args) \ return_type _cdecl (*pointer_name) args
This macro is useful for declaring pointers to functions that use the C calling conventions. For example, to declare a pointer to a function which is passed two strings and returns an integer, one could write
CCB(int, func_ptr, (const char *, const char *));
which would be expanded to
int _cdecl (*func_ptr) (const char *, const char *);
Different compilers have different syntax for the _cdecl keyword. Using this macro makes your callback compiler-independent.
See Also: PCB()
.
void * CellDeref( optr CellRef);
This routine translates an optr to a cell into the cell's address. The routine is simply a synonym for
LMemDeref()
.
Include:
cell.h
void CellDirty( void * ptr); /* pointer to anywhere in locked cell */
This routine marks a cell as "dirty"; i.e., the cell will have to be copied from memory back to the disk.
Include:
cell.h
Tips and Tricks: All the cells in an item block are marked dirty at once; thus, you can call this routine just once for several cells in the same item block. Only the segment portion of the pointer is significant; thus, you can pass a pointer to anywhere in the cell. This is useful if you have incremented the pointer to the cell.
DBGroupAndItem CellGetDBItem( CellFunctionParameters * cfp, word row, /* Get handles of cell in this row */ byte column); /*...and this column */
All cells are stored as ungrouped DB items. If you wish to manipulate the cells with standard DB routines, you will need to know their handles. The routine is passed the address of the
CellFunctionParameters
and the row and column indices of the desired cell. It returns the
DBGroupAndItem
value for the specified cell. If there is no cell at the specified coordinates, it returns a null
DBGroupAndItem
. The routine does not lock the cell or change it in any way.
Include:
cell.h
See Also: DBGroupAndItem
.
void CellGetExtent( CellFunctionParameters *cfp, RangeEnumParams *rep); /* write boundaries in REP_bounds field */
This routine returns the boundaries of the utilized portion of the cell file. The routine is passed the address of the cell file's
CellFunctionParameters
structure.) It writes the results into the
REP_bounds
field of the passed
RangeEnumParams
structure. The index of the first row to contain cells is written into
REP_bounds.R_top
; the index of the last occupied row is written to
REP_bounds.R_bottom
; the index of the first occupied column is written to
REP_bounds.R_left
; and the index of the last occupied row is written to
REP_bounds.R_right
. If the cell file contains no cells, all four fields will be set to -1..
Include: cell.h
void * CellLock( CellFunctionParameters* cfp, word row, /* Lock cell in this row... */ word column); /* ... and this column */
This routine is passed the address of the
CellFunctionParameters
of a cell file, and the row and column indices of a cell. It locks the cell and returns a pointer to it.
Include: cell.h
See Also: CellLockGetRef()
.
void * CellLockGetRef( CellFunctionParameters* cfp, word row, /* Lock cell in this row... */ word column, /* ... and this column */ optr * ref); /* Write handles here */
This routine is passed the address of the
CellFunctionParameters
of a cell file, and the row and column indices of a cell. It locks the cell and returns a pointer to it. It also writes the locked cell's item-block and chunk handles to the optr. If the cell moves (e.g. because another cell is allocated), you can translate the optr structure into a pointer by passing it to
CellDeref()
.
Include: cell.h
Warnings: The optr becomes invalid when the cell is unlocked.
See Also: CellGetDBItem().
,
CellLock()
.
void CellReplace{ CellFunctionParameters * cfp, word row, /* Insert/replace cell at this row... */ word column, /* ... and this column */ const void * cellData, /* Copy this data into the new cell */ word size); /* Size of new cell (in bytes) */
This routine is used for creating, deleting, and replacing cells in a cell file. To create or replace a cell, set
cellData
to point to the data to copy into the new cell, and set
size
to the length of the cell in bytes, and
row
and
column
the cell's coordinates. (As usual,
cfp
is a pointer to the cell file's
CellFunctionParameters
structure.) Any pre-existing cell at the specified coordinates will automatically be freed, and a new cell will be created.
To delete a cell, pass a size of zero. If there is a cell at the specified coordinates, it will be freed. (The cellData argument is ignored.)
Include: cell.h
Warnings: If a cell is allocated or replaced, pointers to all ungrouped items (including cells) in that VM file may be invalidated. The
CellFunctionParameters
structure must not move during the call; for this reason, it may not be in an ungrouped DB item. Never replace or free a locked cell; if you do, the cell's item block will not have its lock count decremented, which will prevent the block from being unlocked.
void CellUnlock( void * ptr); /* pointer to anywhere in locked cell */
This routine unlocks the cell pointed to by ptr . Note that a cell may be locked several times. When all locks on all cells in an item-block have been released, the block can be swapped back to the disk.
Include: cell.h
Tips and Tricks: The DB manager does not keep track of locks on individual items; instead, it keeps a count of the total number of locks on all the items in an item-block. For this reason, only the segment address of the cell is significant; thus, you can pass a pointer to somewhere within (or immediately after) a cell to unlock it. This is useful if you have incremented the pointer to the cell.
Be Sure To: If you change the cell, dirty it (with
CellDirty()
)
before
you unlock it.
void CFatalError( word code)
This routine generates a fatal error. It stores an error code passed for use by the debugger.
void * ChunkArrayAppend( optr array, /* optr to chunk array */ word elementSize) /* Size of new element (ignored if * elements are uniform-sized) */
This routine adds a new element to the end of a chunk array. It automatically expands the chunk to make room for the element and updates the
ChunkArrayHeader
. It returns a pointer to the new element.
One of the arguments is the size of the new element. This argument is significant if the array contains variable-sized elements. If the elements are uniform-sized, this argument is ignored. The array is specified with an optr.
Include: chunkarr.h
Be Sure To: Lock the block on the global heap (if it is not fixed).
Warnings: This routine resizes the chunk, which means it can cause heap compaction or resizing. Therefore, all existing pointers to within the LMem heap are invalidated.
See Also: ChunkArrayInsertAt()
,
ChunkArrayDelete()
.
void * ChunkArrayAppendHandles( MemHandle mh, /* Handle of LMem heap's block */ ChunkHandle ch, /* Handle of chunk array */ word size) /* Size of new element (ignored if * elements are uniform-sized) */
This routine is exactly like
ChunkArrayAppend()
, except that the chunk array is specified by its global and local handles instead of by an optr.
Include: chunkarr.h
Be Sure To: Lock the block on the global heap (if it is not fixed).
Warnings: This routine resizes the chunk, which means it can cause heap compaction or resizing. Therefore, all existing pointers to within the LMem heap are invalidated.
See Also: ChunkArrayInsertAt()
,
ChunkArrayDelete()
.
ChunkHandle ChunkArrayCreate( MemHandle mh, /* Handle of LMem heap's block */ word elementSize, /* Size of each element (or zero if elements are * variable-sized) */
word headerSize, /* Amount of chunk to use for header (or zero for * default size) */
ObjChunkFlags ocf);
This routine sets up a chunk array in the specified LMem heap. The heap must have already been initialized normally. The routine allocates a chunk and sets up a chunk array in it. It returns the chunk's handle. If it cannot create the chunk array, it returns a null handle.
If the chunk array will have uniform-size elements, you must specify the element size when you create the chunk array. You will not be able to change this. If the array will have variable-sized elements, pass an element size of zero.
The chunk array always begins with a
ChunkArrayHeader
. You can specify the total header size; this is useful if you want to begin the chunk array with a special header containing some extra data. However, the header must be large enough to accommodate a
ChunkArrayHeader
, which will begin the chunk. If you define a header structure, make sure that its first element is a
ChunkArrayHeader
. Only the chunk array code should access the actual
ChunkArrayHeader
. If you pass a
headerSize
of zero, the default header size will be used (namely,
sizeof(ChunkArrayHeader)
). If you pass a non-zero
headerSize
, any space between the
ChunkArrayHeader
and the heap will be zero-initialized.
To free a chunk array, call
LMemFree()
as you would for any chunk.
Include: chunkarr.h
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).
Warnings: Results are unpredictable if you pass a non-zero
headerSize
argument which is smaller than
sizeof(ChunkArrayHeader)
. Since the routine allocates a chunk, it can cause heap compaction or resizing; all pointers to within the block are invalidated.
ChunkHandle ChunkArrayCreateAt( optr array, /* Create chunk array in this chunk */ word elementSize, /* Size of each element (or zero if elements are * variable-sized) */
word headerSize, /* Amount of chunk to use for header (or zero for * default size) */
ObjChunkFlags ocf);
This routine is exactly like
ChunkArrayCreate()
, except that you specify the chunk which will be made into a chunk array. The chunk is specified with an optr. Note that any data already existing in the chunk will be overwritten.
Warnings: The chunk may be resized, which invalidates all pointers to within the LMem heap.
Include: chunkarr.h
ChunkHandle ChunkArrayCreateAtHandles( MemHandle mh, ChunkHandle ch, word elementSize, word headerSize, ObjChunkFlags ocf);
This routine is exactly like
ChunkArrayCreate()
, except that the chunk is specified with its global and chunk handles instead of with an optr.
Tips and Tricks: If you pass a null chunk handle, a new chunk will be allocated.
Warnings: The chunk may be resized, which would invalidate all pointers to within the LMem heap.
Include: chunkarr.h
void ChunkArrayDelete( optr array, /* optr to chunk array */ void * element); /* Address of element to delete */
This routine deletes an element from a chunk array. It is passed the address of that element, as well as the optr of the array.
Since the chunk is being decreased in size, the routine is guaranteed not to cause heap compaction or resizing.
Include: chunkarr.h
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).
Tips and Tricks: Only the chunk handle portion of the optr is significant; the memory block is determined from the pointer to the element.
Warnings: The addresses of all elements after the deleted one will change. No other addresses in the block will be affected. If the address passed is not the address of an element in the array, results are undefined.
See Also: ChunkArrayAppend()
,
ChunkArrayInsertAt()
,
ChunkArrayZero()
.
void ChunkArrayDeleteHandle( ChunkHandle ch, /* Handle of chunk array */ void * el); /* Address of element to delete */
This routine is exactly like
ChunkArrayDelete()
, except that the chunk array is specified with its chunk handle instead of with an optr. The global memory handle is not needed, as the memory block is implicit in the pointer to the element.
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).
Include: chunkarr.h
void ChunkArrayDeleteRange( optr array, /* optr to chunk array */ word firstElement, /* index of first element to delete */ word count); /* # of elements to delete (-1 to delete to * end of array) */
This routine deletes several consecutive elements from a chunk array. The routine is passed the optr of the chunk array, the index of the first element to delete, and the number of elements to delete. The routine is guaranteed not to cause heap compaction or resizing; thus, pointers to other elements in the array will remain valid.
void ChunkArrayElementResize( optr array, /* optr to chunk array */ word element, /* Index of element to resize */ word newSize); /* New size of element, in bytes */
This routine resizes an element in a chunk array. The chunk array must have variable-sized elements. The routine is passed an optr to the chunk array (which must be locked on the global heap), as well as the index of the element to resize and the new size (in bytes). It does not return anything.
If the new size is larger than the old, null bytes will be added to the end of the element. If the new size is smaller than the old, bytes will be removed from the end to truncate the element to the new size.
Warnings: If the element is resized larger, the chunk array may move within the LMem heap, and the heap itself may move on the global heap; thus, all pointers to within the LMem heap will be invalidated.
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).
Include: chunkarr.h
void ChunkArrayElementResizeHandles( Memhandle mh, /* Global handle of LMem heap */ ChunkHandle ch, /* Chunk handle of chunk array */ word el, /* Index of element to resize */ word ns); /* New size of element, in bytes */
This routine is exactly like
ChunkArrayElementResize()
except that the chunk array is specified with its global and chunk handles, instead of with its optr.
Warnings: If the element is resized to larger than the old, the chunk array may move within the LMem heap, and the heap itself may move on the global heap; thus, all pointers to within the LMem heap will be invalidated.
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).
Include: chunkarr.h
void * ChunkArrayElementToPtr( optr array, /* optr to chunk array */ word elementNumber, /* Element to get address of */ void * elementSize); /* Write element's size here */
This routine translates the index of an element into the element's address. The routine is passed an optr to the chunk array, the index of the element in question, and a pointer to a word-sized variable. It returns a pointer to the element. If the elements in the array are of variable size, it writes the size of the element to the variable pointed to by the elementSize pointer. If the elements are of uniform size, it does not do this.
If the array index is out of bounds, the routine returns a pointer to the last element in the array. The routine will also do this if you pass the constant CA_LAST_ELEMENT.
Include: chunkarr.h
Tips and Tricks: If you are not interested in the element's size, pass a null pointer as the third argument.
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).
Warnings: The error-checking version fatal-errors if passed the index CA_NULL_ELEMENT (i.e. 0xffff, or -1).
void * ChunkArrayElementToPtrHandles( Memhandle mh, /* Handle of LMem heap's block */ ChunkHandle chunk, /* Handle of chunk array */ word elementNumber, /* Element to get address of */ void * elementSize); /* Write element's size here */
This routine is just like ChunkArrayElementToPtr() , except that the chunk array is specified with its global and chunk handles, instead of with an optr.
Include: chunkarr.h
Tips and Tricks: If you are not interested in the element's size, pass a null pointer as the fourth argument.
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).
See Also: ChunkArrayPtrToElement().
Warnings: The error-checking version fatal-errors if passed the index CA_NULL_ELEMENT (i.e. 0xffff, or -1).
Boolean ChunkArrayEnum( optr array, /* optr to chunk array */ void * enumData, /* This is passed to callback routine */ Boolean _pascal (*callback) (void *element, void *enumData)); /* callback called for each element; returns TRUE to stop */
This routine lets you apply a procedure to every element in a
chunk array. The routine is passed an optr to the chunk array,
a pointer (which is passed to the callback routine), and a pointer
to a Boolean callback routine. The callback routine, in turn,
is called once for each element in the array, and is passed two
arguments: a pointer to an element and the pointer which was passed
to ChunkArrayEnum()
. If the callback routine ever
returns true for an element, ChunkArrayEnum()
will stop with that element and return true . If it enumerates
every element without being aborted, it returns false.
The callback routine can call such routines as
ChunkArrayAppend(),
ChunkArrayInsertAt(),
and ChunkArrayDelete()
. ChunkArrayEnum()
will see to it that every element
is enumerated exactly once. The callback routine can even make
a nested call to ChunkArrayEnum()
; the nested call
will be completed for every element before the outer call goes
to the next element. The callback routine should be declared _pascal.
You can get into trouble if more than one thread of execution is accessing a single ChunkArray and one or both of these threads is using one of the ChunkArrayEnum...() routines. The error-checking version of the kernel detects this situation and generates a CHUNK_ARRAY_ENUM_INSERT_OR_DELETE_RUN_BY_MULTIPLE_THREADS warning if it detects such. If your code is getting this warning, you should add some synchronization between threads. While one thread is enumerating through chunks in the chunk array, the other should do nothing to enumerate the same array, nor alter the array in any way.
Include: chunkarr.h
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).
Boolean ChunkArrayEnumHandles( MemHandle mh, /* Handle of LMem heap's block */ ChunkHandle ch, /* Handle of chunk array */ void * enumData, /* Buffer used by callback routine */ Boolean _pascal (*callback) (void *element, void *enumData)); /* callback called for each element; returns TRUE to stop */
This routine is exactly like ChunkArrayEnum() , except that the chunk array is specified by its global and chunk handles (instead of with an optr).
You can get into trouble if more than one thread of execution is accessing a single ChunkArray and one or both of these threads is using one of the ChunkArrayEnum...() routines. The error-checking version of the kernel detects this situation and generates a CHUNK_ARRAY_ENUM_INSERT_OR_DELETE_RUN_BY_MULTIPLE_THREADS warning if it detects such. If your code is getting this warning, you should add some synchronization between threads. While one thread is enumerating through chunks in the chunk array, the other should do nothing to enumerate the same array, nor alter the array in any way.
Include: chunkarr.h
Boolean ChunkArrayEnumRange( optr array, /* optr to chunk array */ word startElement, /* Start enumeration with this element */ word count, /* Process this many elements */ void * enumData, /* This is passed to the callback routine */ Boolean _pascal (*callback) /* Return TRUE to halt enumeration */ (void *element, void *enumData));
This routine is exactly like ChunkArrayEnum()
(described above), except that it acts on a limited portion of
the array. It is passed two additional arguments: the index of
the starting element, and the number of elements to process. It
will begin the enumeration with the element specified (remember,
the first element in a chunk array has an index of zero). If the
count passed would take the enumeration past the end of the array,
ChunkArrayEnumRange()
will automatically stop with
the last element. You can instruct ChunkArrayEnumRange()
to process all elements by passing a count
of CA_LAST_ELEMENT.
You can get into trouble if more than one thread of execution is accessing a single ChunkArray and one or both of these threads is using one of the ChunkArrayEnum...() routines. The error-checking version of the kernel detects this situation and generates a CHUNK_ARRAY_ENUM_INSERT_OR_DELETE_RUN_BY_MULTIPLE_THREADS warning if it detects such. If your code is getting this warning, you should add some synchronization between threads. While one thread is enumerating through chunks in the chunk array, the other should do nothing to enumerate the same array, nor alter the array in any way.
Include: chunkarr.h
Warnings: The start element must be within the bounds of the array.
See Also: ChunkArrayEnum().
Boolean ChunkArrayEnumRangeHandles( MemHandle mh, /* Handle of LMem heap's block */ ChunkHandle ch, /* Handle of chunk array */ word startElement, /* Start enumeration with this element */ word count, /* Process this many elements */ void * enumData, /* This is passed to the callback routine */ Boolean _pascal (*callback) /* Return TRUE to halt enumeration */ (void *element, void *enumData));
This routine is exactly like ChunkArrayEnumRange() , except that the chunk array is specified by its global and chunk handles (instead of with an optr).
You can get into trouble if more than one thread of execution is accessing a single ChunkArray and one or both of these threads is using one of the ChunkArrayEnum...() routines. The error-checking version of the kernel detects this situation and generates a CHUNK_ARRAY_ENUM_INSERT_OR_DELETE_RUN_BY_MULTIPLE_THREADS warning if it detects such. If your code is getting this warning, you should add some synchronization between threads. While one thread is enumerating through chunks in the chunk array, the other should do nothing to enumerate the same array, nor alter the array in any way.
word ChunkArrayGetCount( optr array); /* optr of chunk array */
This routine returns the number of elements in the specified chunk array.
Include: chunkarr.h
Tips and Tricks: It is usually faster to examine
the CAH _count
field of the ChunkArrayHeader
. This field is the first word of the ChunkArrayHeader
(and therefore of the chunk). It contains the number of elements
in the chunk array.
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).
See Also: ChunkArrayHeader.
word ChunkArrayGetCountHandles( MemHandle mh, /* Handle of LMem heap's block */ ChunkHandle ch); /* Handle of chunk array */
This routine is just like
ChunkArrayGetCount()
, except that the chunk array is specified by its global and local handles (instead of with an optr).
Include: chunkarr.h
void ChunkArrayGetElement( optr array, /* optr to chunk array */ word elementNumber, /* Index of element to copy */ void * buffer); /* Address to copy element to */
This routine copies an element in a chunk array into the passed buffer. It is your responsibility to make sure the buffer is large enough to hold the element.
Include: chunkarr.h
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed). Make sure the buffer is large enough to hold the element.
See Also: ChunkArrayPtrToElement()
,
ChunkArrayElementToPtr()
.
void ChunkArrayGetElementHandles( Memhandle mh, /* Handle of LMem heap's block */ ChunkHandle array, /* Handle of chunk array */ word elementNumber, /* Index of element to copy */ void * buffer); /* Address to copy element to */
This routine is just like
ChunkArrayGetElement()
, except that the chunk array is specified by its global and chunk handles (instead of with an optr).
Include: chunkarr.h
Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed). Make sure the buffer is large enough to hold the element.
See Also: ChunkArrayPtrToElement()
,
ChunkArrayElementToPtr()
.
void * ChunkArrayInsertAt( optr array, /* Handle of chunk array */ void * insertPointer, /* Address at which to insert * element */
word elementSize); /* Size of new element (ignored * if elements are uniform-sized) */
This routine inserts a new element in a chunk array. You specify the location by passing a pointer to an element. A new element will be allocated at that location; thus, the element which was pointed to will be shifted, so it ends up immediately after the new element. The new element will be zero-initialized.
The routine is passed three arguments: the optr of the array, the address where the new element should be inserted, and the size of the new element. (If the array is of uniform-size elements, the size argument will be ignored.)
Include: chunkarr.h
Tips and Tricks: Only the chunk-handle portion of the optr is significant; the memory block is implicit in the pointer to the element.
Be Sure To: Lock the block on the global heap (if it is not fixed).
Warnings: If the address passed is not the address of an element already in the chunk array, results are undefined. The routine may cause heap compaction or resizing; all pointers within the block are invalidated.
See Also: ChunkArrayAppend()
,
ChunkArrayDelete()
.
void * ChunkArrayInsertAtHandle( ChunkHandle chunk, /* Handle of chunk array */ void * insertPointer, /* Address at which to insert * element */
word elementSize); /* Size of new element (ignored * if elements are uniform-sized) */
This routine is just like
ChunkArrayInsertAt()
, except that the chunk array is specified by its chunk handle. (The global block is implicit in the pointer passed.)
Include: chunkarr.h
word ChunkArrayPtrToElement( optr array, /* Handle of chunk array */ void * element); /* Address of element */
This routine takes the address of an element in a chunk array, as well as an optr to the array. It returns the element's zero-based index.
Include: chunkarr.h
Tips and Tricks: Only the chunk-handle portion of the optr is significant; the memory block is implicit in the pointer to the element.
Be Sure To: Lock the block on the global heap (unless it is fixed).
Warnings: If the address passed is not the address of the beginning of an element, results are unpredictable.
See Also: ChunkArrayElementToPtr()
.
word ChunkArrayPtrToElementHandle( ChunkHandle array, /* chunk handle of chunk array */ void * element); /* Pointer to element to delete */
This routine is exactly like
ChunkArrayPtrToElement()
, except that the chunk array is indicated by its chunk handle. (The global block is implicit in the pointer passed.)
void ChunkArraySort( optr array, /* optr to chunk array */ word valueForCallback, /* Passed to callback routine */ sword _pascal (*callback) (void *el1, void * el2, word valueForCallback)) /* Sign of return value decides order of elements */
This is a general-purpose sort routine for chunk arrays. It does a modified Quicksort on the array, using an insertion sort for subarrays below a certain size.
The sort routine does not compare elements. Rather, it calls a comparison callback routine passed in the
callback
parameter. Whenever it needs to compare two elements, it calls the callback routine, passing the addresses of the elements and the
valueForCallback
word which was passed to
ChunkArraySort()
. The callback routine should be declared _pascal. The callback routine's return value determines which element will come first in the sorted array:
el1
ought to come before
el2
in the sorted array, the callback routine should return a negative integer.
el1
ought to come after
el2
in the sorted array, the callback routine should return a positive integer.
el1
comes before or after
el2
in the sorted array, the callback routine should return zero.Include: chunkarr.h
Tips and Tricks: You may need to sort an array based on different criteria at different times. The simplest way to do this is to write one general-purpose callback routine and have the
valueForCallback
word determine how the sort is done. For example, the same callback routine could sort the array in ascending or descending order, depending on the
valueForCallback
.
Be Sure To: Lock the block on the global heap (unless it is fixed).
Warnings: Do not have the callback routine do anything which might invalidate pointers to the array (such as allocate a new chunk or element).
See Also: ArrayQuickSort()
.
void ChunkArraySortHandles( MemHandle memHandle, /* Handle of LMem heap's block */ ChunkHandle chunkHandle, /* Handle chunk array */ word valueForCallback, /* Passed to callback routine */ sword _pascal(*callback)(void *el1, void * el2, word valueForCallback) /* Sign of return value decides order of elements */
This routine is exactly like
ChunkArraySort()
above, except that the chunk array is specified by its global and chunk handles (instead of by an optr).
Include: chunkarr.h
void ChunkArrayZero( optr array); /* optr to chunk array */
This routine destroys all the elements in an array. It does not affect the extra-space area between the
ChunkArrayHeader
and the elements. It is guaranteed not to cause heap compaction or resizing; thus, pointers to other chunks remain valid.
Include: chunkarr.h
Be Sure To: Lock the block on the global heap (unless it is fixed).
See Also: ChunkArrayDelete()
.
void ChunkArrayZeroHandles( MemHandle mh /* Global handle of LMem heap */ ChunkHandle ch); /* Chunk handle of chunk array */
This routine is exactly like
ChunkArrayZero()
above, except that the chunk array is specified by its global and chunk handles (instead of by an optr).
Include: chunkarr.h
void ClipboardAbortQuickTransfer(void);
This routine cancels a quick-transfer operation in progress. It is typically used when an object involved in a quick-transfer is shutting down or when an error occurs in a quick-transfer. This routine is usually used only by the object or Process which initiated the quick-transfer.
Include: clipbrd.goh
void ClipboardAddToNotificationList( optr notificationOD);
This routine registers the passed object or process for quick-transfer notification. This routine is typically called from within an object's
MSG_META_INITIALIZE
handler or within a Process object's
MSG_GEN_PROCESS_OPEN_APPLICATION
handler. Pass the optr of the object or the geode handle if the Process object should be registered.
Include: clipbrd.goh
See Also: ClipboardRemoveFromNotificationList()
.
void ClipboardClearQuickTransferNotification( optr notificationOD);
This routine removes an object or process from quick-transfer notification. It is typically used in the object's
MSG_META_DETACH
handler or in the Process object's
MSG_GEN_PROCESS_CLOSE_APPLICATION
to ensure that it is not notified after it has already detached.
Pass the optr of the object specified to receive notification in
ClipboardStartQuickTransfer()
(or the geode handle if a process).
Note that an object may also want to check if a quick-transfer is in progress when detaching and possibly abort it if there is one.
Include: clipbrd.goh
void ClipboardDoneWithItem( TransferBlockID header);
This routine is called when an object or Process is done using a transfer item. It relinquishes exclusive access to the item's transfer VM file after the caller had previously called
ClipboardQueryItem()
.
Include: clipbrd.goh
void ClipboardEndQuickTransfer( ClipboardQuickNotifyFlags flags);
This routine ends a quick-transfer operation by resetting the pointer image, clearing any quick-transfer region, clearing the quick-transfer item, and sending out any needed notification of the completed transfer.
Pass this routine a record of
ClipboardQuickNotifyFlags
. Pass the value CQNF_MOVE if the operation was completed and was a move; pass CQNF_COPY if the operation was completed and was a copy. If the operation could not be completed (e.g. incompatible data types), pass CQNF_NO_OPERATION or CQNF_ERROR.
The notification sent out by the UI will be in the form of the message
MSG_META_CLIPBOARD_NOTIFY_QUICK_TRANSFER_CONCLUDED
. This message notifies the originator of the transfer item of the type of operation; the originator can then respond if necessary.
Include: clipbrd.goh
word ClipboardEnumItemFormats( TransferBlockID header, word maxNumFormats, ClipboardFormatID * buffer);
This routine returns a list of all the formats supported by the current transfer item. To see whether a particular format is supported, you can use
ClipboardTestItemFormat()
instead.
Pass this routine the following:
header
ClipboardQueryItem()
.
maxNumFormats
buffer
ClipboardFormatID
structures, one for each format available. This buffer should be at least large enough to support the number of formats requested in
maxNumFormats
.
The word return value is the total number of formats returned. This number will be equal to or less than the number passed in
maxNumFormats
. The routine will also return the passed buffer filled with that number of
ClipboardFormatID
structures.
Include: clipbrd.goh
See Also: ClipboardTestItemFormat()
.
VMFileHandle ClipboardGetClipboardFile(void);
This routine returns the VM file handle of the current default transfer VM file.
Include: clipbrd.goh
optr ClipboardGetItemInfo( TransferBlockID header);
This routine returns the source identifier (CIH
_sourceID
) of the current transfer item. Pass the transfer item's header returned by
ClipboardQueryItem()
.
Include: clipbrd.goh
TransferBlockID ClipboardGetNormalItemInfo(void);
This routine returns information about the normal transfer item. It returns a
TransferBlockID
dword which contains the VM file handle of the transfer file and the VM block handle of the transfer item's header block.
To extract the file handle from the return value, use the macro
FileFromTransferBlockID()
. To extract the block handle, use the macro
BlockFromTransferBlockID()
.
Include: clipbrd.goh
TransferBlockID ClipboardGetQuickItemInfo(void);
This routine returns information about the quick-transfer transfer item. It returns a
TransferBlockID
dword which contains the VM file handle of the transfer file and the VM block handle of the transfer item's header block.
To extract the file handle from the return value, use the macro
FileFromTransferBlockID()
. To extract the block handle, use the macro
BlockFromTransferBlockID()
.
Include: clipbrd.goh
Boolean ClipboardGetQuickTransferStatus(void);
This routine returns
true
if a quick-transfer operation is in progress,
false
otherwise. It is often called when objects or Processes are shutting down in order to abort any quick-transfers originated by the caller.
Include: clipbrd.goh
TransferBlockID ClipboardGetUndoItemInfo(void);
This routine returns information about the undo transfer item. It returns a
TransferBlockID
dword which contains the VM file handle of the transfer file and the VM block handle of the transfer item's header block.
To extract the file handle from the return value, use the macro
FileFromTransferBlockID()
. To extract the block handle, use the macro
BlockFromTransferBlockID()
.
Include: clipbrd.goh
void ClipboardQueryItem( ClipboardItemFlags flags, ClipboardQueryArgs * retValues);
This routine locks the transfer item for the caller's exclusive access and returns information about the current transfer item. You should call this routine when beginning any paste or clipboard query operation. For operations in which you will change the clipboard's contents, you should instead use the routine
ClipboardRegisterItem()
.
Pass the following values:
flags
ClipboardItemFlags
indicating the transfer item you want to query. Use CIF_QUICK to get information on the quick transfer item, and pass zero (or TIF_NORMAL) to get information on the normal transfer item.
retValues
A pointer to an empty
ClipboardQueryArgs
structure into which return information about the transfer item will be passed. This structure is defined as follows:typedef struct { word CQA_numFormats; optr CQA_owner; TransferBlockID CQA_header; } ClipboardQueryArgs;
The
CQA_header
field of
ClipboardQueryArgs
is used as a pass value to several other clipboard routines. It contains the VM file handle of the transfer VM file and the VM block handle of the transfer item's header block. The
CQA_owner
field is the optr of the object that originated the transfer item. The
CQA_numFormats
field specifies the total number of formats available for this transfer item. To see if a particular format is supported by the transfer item, call the routine
ClipboardTestItemFormat()
.
Be Sure To: You must call
ClipboardDoneWithItem()
when you are done accessing the transfer item. This routine relinquishes your exclusive access to the transfer VM file.
Include: clipbrd.goh
See Also: ClipboardRequestItemFormat()
,
ClipboardDoneWithItem()
.
Boolean ClipboardRegisterItem( TransferBlockID header, ClipboardItemFlags flags);
This routine completes a change to the transfer item. You should use this routine whenever copying or cutting something into the clipboard or whenever attaching something as the quick-transfer item.
This routine puts the item specified by
header
into the transfer VM file. It frees any transfer item that may already be in the file. Pass this routine the following:
header
TransferBlockID
structure using the macro
BlockIDFromFileAndBlock()
.
flags
ClipboardItemFlags
indicating whether you're registering a clipboard item or a quick-transfer item. The flag CIF_QUICK indicates the item is a quick-transfer item; zero (or TIF_NORMAL) indicates the item is a normal clipboard item.Include: clipbrd.goh
See Also: ClipboardRequestItemFormat()
.
Boolean ClipboardRemoveFromNotificationList( optr notificationOD);
This routine removes an object or Process from the clipboard's change notification list. It is typically called when the object or Process is being detached or destroyed. Pass it the same optr that was added to the notification list with
ClipboardAddToNotificationList
().
This routine returns an error flag: The flag will be
true
if the object could not be found in the notification list,
false
if the object was successfully removed from the list.
Include: clipbrd.goh
See Also: ClipboardAddToNotificationList()
.
void ClipboardRequestItemFormat( ClipboardItemFormatID format, TransferBlockID header, ClipboardRequestArgs * retValue);
This routine returns specific information about a particular transfer item. Because some of the passed information must be retrieved with
ClipboardQueryItem()
, you must call
ClipboardQueryItem()
before calling this routine.
Pass this routine the following:
format
ClipboardItemFormatID
value with the macro
FormatIDFromManufacturerAndType()
.
header
TransferBlockID
structure using the macro
BlockIDFromFileAndBlock()
using returned information from
ClipboardQueryItem()
.
retValue
A pointer to an empty
ClipboardRequestArgs
structure that will be filled by the routine. This structure is defined as follows:typedef struct { VMFileHandle CRA_file; VMChain CRA_data; word CRA_extra1; word CRA_extra2; } ClipboardRequestArgs;
Upon return, the
CRA_file
field will contain the transfer VM file's VM file handle and the
CRA_data
field will contain the VM block handle of the transfer item's header block. If there is no transfer item,
CRA_data
will be zero.
Include: clipbrd.goh
See Also: ClipboardRegisterItem()
,
ClipboardQueryItem()
.
void ClipboardSetQuickTransferFeedback( ClipboardQuickTransferFeedback cursor, UIFunctionsActive buttonFlags);
This routine sets the image of the mouse pointer during a quick-transfer operation. Use this routine to provide visual feedback to the user during the quick-transfer. For example, an object that could not accept the quick-transfer item would set the "no operation" cursor while the mouse pointer was over its bounds.
Pass the two following values:
cursor
ClipboardQuickTransferFeedback
type indicating the type of cursor to set. The possible values are listed below.
buttonFlags
UIFunctionsActive
flags. These flags are defined in the Input Manager section and deal with user override of the move/copy behavior.
The cursor parameter contains a value of
ClipboardQuickTransferFeedback
. This is an enumerated type that defines the cursor to be set, and it has the following values:
Include: clipbrd.goh
Boolean ClipboardStartQuickTransfer( ClipboardQuickTransferFlags flags, ClipboardQuickTransferFeedback initialCursor, word mouseXPos, word mouseYPos, ClipboardQuickTransferRegionInfo * regionParams, optr notificationOD);
This routine signals the beginning of a quick-transfer operation. Typically, an object or process will call this routine in its
MSG_META_START_MOVE_COPY
handler.
Pass it the following parameters:
flags
ClipboardQuickTransferFlags
indicating whether an addition graphic region will be attached to the cursor and whether the caller wants notification of transfer completion. The flags allowed are listed below, after the parameter list.
initialCursor
ClipboardQuickTransferFeedback
, either CQTF_MOVE or CQTF_COPY. If -1 is passed in this parameter, the initial cursor will be the default no-operation cursor (i.e. the transfer source may not also act as the transfer destination).
mouseXPos
flags
. It is the horizontal position of the mouse in screen coordinates.
mouseYPos
flags
. It is the vertical position of the mouse in screen coordinates.
regionParams
ClipboardQuickTransferRegionInfo
structure defining the graphical region to be attached to the cursor during the transfer operation. This structure is only required if CQTF_USE_REGION is passed in
flags
. It is defined below.
notificationOD
MSG_META_CLIPBOARD_NOTIFY_QUICK_TRANSFER_CONCLUDED
and
MSG_..._FEEDBACK
.
The allowed
ClipboardQuickTransferFlags
are listed below:
If a graphical region is to be attached to the quick-transfer cursor, you must pass a pointer to a
ClipboardQuickTransferRegionInfo
in the
regionParams
parameter. This structure is defined below.
typedef struct { word CQTRI_paramAX; word CQTRI_paramBX; word CQTRI_paramCX; word CQTRI_paramDX; Point CQTRI_regionPos; dword CQTRI_strategy; dword CQTRI_region; } ClipboardQuickTransferRegionInfo;
This structure is passed on the stack to the routine. The first four fields represent the region's definition parameters.
CQTRI_regionPos
is a
Point
structure indicating where (in screen coordinates) the region is to be located.
CQTRI_strategy
is a pointer to the region strategy routine.
CQTRI_strategy
should be a video driver strategy. To find out the strategy of the video driver associated with your window, send your object a MSG_VIS_VUP_QUERY with VUQ_VIDEO_DRIVER. Pass the handle thus gained to
GeodeInfoDriver()
, which will return the strategy.
This routine returns an error flag: If a quick-transfer is already in progress, the return will be
true
. If the quick-transfer is successfully begun, the error flag will be
false
.
Include: clipbrd.goh
Boolean ClipboardTestItemFormat( TransferBlockID header, ClipboardFormatID format);
This routine tests whether the given format is supported by the specified transfer item. It returns
true
if the format is supported,
false
if the format is not supported. Pass the following values:
header
TransferBlockID
specifying the VM file handle and VM block handle of the transfer item to be checked. This is returned by the routines
ClipboardGetNormalItemInfo()
,
ClipboardGetQuickItemInfo()
,
ClipboardGetUndoItemInfo()
, and
ClipboardQueryItem()
. Most often the proper routine to use is
ClipboardQueryItem()
.
format
ClipboardFormatID
specifying the type and manufacturer ID of the format to be checked. It is most appropriate to create this parameter from its individual parts using the macro
FormatIDFromManufacturerAndType()
.Include: clipbrd.goh
void ClipboardUnregisterItem( optr owner);
This routine restores the transfer item to what it was before the last
ClipboardRegisterItem()
. Pass it the optr of the caller.
Only the object that last registered a transfer item is allowed to unregister it. If the transfer item is owned by a different object, or if there is no transfer item, nothing will be done. If the transfer item is owned by the caller, the transfer item will be unregistered and the clipboard will be restored to its previous state.
Include: clipbrd.goh
optr ConstructOptr( Handle han, ChunkHandle ch);
This macro constructs an optr type from the given handle (typically a MemHandle) and chunk handle.
See Also: HandleToOptr()
,
OptrToHandle()
,
OptrToChunk()
.
Boolean ContactCompareNumbers( TCHAR *number1, TCHAR *number2);
This function compares two phone number strings for equivalence. It ignores extraneous characters such as spaces. It returns zero if they are the same number, otherwise it returns a non-zero value.
Include: contdb.goh
MemHandle ContactCreateRecordFromTemplate( void );
This function creates a new Contact record in the Contacts database. It returns the handle of the new record. Make any desired changes to the record and then call
ContactSaveRecord()
to save the record or
FoamDBDiscardRecord()
to discard changes.
Include: contdb.goh
See Also: ContactSaveRecord()
,
ContactSetTemplateRecord()
.
FieldID ContactEnsureEmptyField( MemHandle record, optr fieldName, ContdbFieldType fieldType);
This function creates a field in a record, and clears the dat from the existing field of that name if one already existed. This function takes the following arguemnts:
FoamDBGetRecordFromID()
or
ContactCreateRecordFromTemplate()
.
NullOptr
to use the default name for the passed
ContdbFieldType
.Include: contdb.goh
See Also: ContactEnsureField()
,
FoamDBSetFieldData()
.
FieldID ContactEnsureField( MemHandle record, optr fieldName, ContdbFieldType fieldType);
This functionreturns the
FieldID
of a field within a record, or creates the field if it doesn't find it. This function takes the following arguemnts:
FoamDBGetRecordFromID()
or
ContactCreateRecordFromTemplate()
.
NullOptr
to use the default name for the passed
ContdbFieldType
.Include: contdb.goh
See Also: ContactEnsureEmptyField()
,
FoamDBSetFieldData()
.
ContactExportStatus ContactExportDBToTextFile( hptr fileExport, dword startElement, dword numOfRecords);
This function exports the Contact database's data as an ASCII file. On success, the function returns CES_NO_ERROR, otherwise it returns CES_FILE_ERROR. This function takes the following arguments:
RecordID
of the first record to export.To export all the records, pass a startElement of zero and a numOfRecords of CONTACT_EXPORT_ALL_RECORDS.
Include: contdb.goh
See Also: ContactExportDBToTextFile()
.
VMFileHandle ContactGetDBHandle( void );
This function returns the handle of the Contact database, the database that contains all of the "address book" data used by the
contdb
library. This handle is necessary for various operations with the library. When you're done with the handle, remember to call
ContactReleaseDBHandle()
.
Include: contdb.goh
See Also: ContactGetDBHandleNoBlock()
,
ContactReleaseDBHandle()
.
VMFileHandle ContactGetDBHandleNoBlock( void );
This function behaves in the same manner as
ContactGetDBHandle()
, except that if it cannot get the handle, it returns zero instead of waiting until the handleis available.When you're done with the handle, remember to call
ContactReleaseDBHandle()
.
Include: contdb.goh
See Also: ContactGetDBHandle()
.
Boolean ContactGetName( MemHandle record, TCHAR *dest);
This function gets the name associated with the record, filling in the dest buffer. If there was no name in the record, this function returns non-zero; otherwise, it returns zero.
Include: contdb.goh
See Also: ContactGetDBHandle()
.
Boolean ContactGetTrunactedName( MemHandle record, TCHAR *dest, word destSize); /* Size of dest buffer */
This function gets the name associated with the record, filling in the dest buffer. It will truncate the name, as necessary to make it fit inside the buffer. Remember to leave space for the null terminator when determining how big a buffer you'll need. If there was no name in the record, this function returns non-zero; otherwise, it returns zero.
Include: contdb.goh
See Also: ContactGetDBHandle()
.
RecordID ContactGetUserDataID( void );
This functionreturns the
RecordID
of the special Contacts database record containing the user's own contact data.
Include: contdb.goh
See Also: FoamDBGetRecordFromID()
.
void ContactImportDBFromTextFile( hptr fileImport); /* file's handle */
This function imports contact database information from an ASCII text file. This file's format is described below. The function will compare imported records to those already in the Contacts database. Any identical records will be merged.
A short sample file is shown below.
[RECORD] [FIELD] Name [FIELD-NAME] [FIELD-DATA] Hudson W. [FIELD-END] [FIELD]
Company [FIELD-NAME] [FIELD-DATA] Space Marines [FIELD-END] [FIELD] Title [FIELD-NAME] [FIELD-DATA] Private [FIELD-END] [RECORD-END]
[RECORD] [FIELD] Name [FIELD-NAME] [FIELD-DATA]
Adams, John Quincy [FIELD-END] [FIELD] Tel [FIELD-NAME] [FIELD-DATA] 1<PHONE_NUMBER> [FIELD-END] [FIELD] [FIELD-NAME] Company [FIELD-DATA] [FIELD-END] USA Government [FIELD] Notes [FIELD-NAME] Note(Birthday) [FIELD-DATA] July 11, 1767 Gift ideas: flowers [FIELD-END] [RECORD-END]
The ASCII file follows these rules:
Include: contdb.goh
See Also: ContactExportDBToTextFile()
.
RecordID ContactMatchName( TCHAR name, ContdbFieldType type, Boolean stopEarly, FieldID *field, word *numMatches );
This function takes aname, searches all fields of the specified type in all records of the Contact database, returning the
RecordID
and
FieldID
of the matching field, if any; if there was no match, it returns -1.
The comparison of names does not consider case.
This function takes the following arguments:
FieldID
buffer. The function will fill this buffer in with the
FieldID
of the matching field, if any.Include: contdb.goh
See Also: ContactEnsureEmptyField()
,
FoamDBSetFieldData()
.
RecordID ContactMatchNumber( TCHAR number, ContdbCallType type, FieldID *field, word *numMatches );
This function takes a phone number, searches all fields of the specified type in all records of the Contact database, returning the
RecordID
and
FieldID
of the matching field, if any; if there was no match, it returns -1.
This function takes the following arguments:
FieldID
buffer. The function will fill this buffer in with the
FieldID
of the matching field, if any.Include: contdb.goh
See Also: ContactEnsureEmptyField()
,
FoamDBSetFieldData()
.
void ContdbRecreateFieldLabel( TCHAR *subLabel, TCHAR *destination, int fieldType);
This utility function takes a field sub-label (e.g., "GSM/PCN") and field type and creates a label from them (e.g. "Tel(GSM)". It will translate standard labels from English to the user's language. (Some field sublabels are standard, such as the "GSM" in "Tel(GSM)" and will be translated; the user's custom sublabels will not be translated.) This function takes the following arguments:
ContdbFieldType
value of the field.Include: contdb.goh
See Also: ContactImportDBFromTextFile()
.
void ContactReleaseDBHandle( void );
This function releases the Contact database's handle, signalling that the application is done with the database for now.
Include: contdb.goh
See Also: ContactGetDBHandle()
,
ContactReleaseDBHandle()
.
dword ContactSaveRecord( MemHandle record);
This functionsaves the passed record in the database, inserting it in the proper sort order. It returns the record's
RecordID
number.
Include: contdb.goh
See Also: FoamDBDiscardRecord()
,
FoamDBDeleteRecord()
.
void ContactSetTemplateRecord( MemHandle record);
This functionmakes the passed record the Contact database's template record. It also frees that contact's handle.
Include: contdb.goh
See Also: ContactCreateRecordFromTemplate()
.
void ContdbTranslateSubFieldLabelToEnglish( TCHAR *subLabel, TCHAR *destination);
This function translates a foreign sub-label to its english equivalent. This function only recognizes certain "standard" sublabels; the user's custom labels will not be translated. This function takes two arguments: a buffer containing the string to translate and a string buffer to hold the translation.
See Also: DBAllocUngrouped()
.
DataStoreStructureError DataStoreAddField( word dsToken, FieldDescriptor *fieldDescPtr, FieldID *fieldIDPtr);
Adds a field to the datastore and writes the new field's
FieldID
to fieldIDPtr. Returns a
DataStoreStructureError
value (DSSE_NO_ERROR if successful). Takes the following arguments:
FieldDescriptor
structure. Set FD
_flags
to FF_PRIMARY_KEY if the field is part of the key.typedef struct { FieldData FD_data; TCHAR *FD_name; } FieldDescriptor;
typedef struct { FieldType FD_type; FieldCategory FD_category; FieldFlags FD_flags; } FieldData;
FieldID
of the added field.Include: datastor.h
DataStoreStructureError DataStoreBuildIndex( word dsToken, MemHandle *indexBlockHan, word dataSize, DataStoreIndexCallbackParams *paramsPtr, sword _pascal (*CallbackRoutine) ( word dsToken, DataStoreIndexCallbackParams *paramsPtr));
Builds an index of
RecordNum
s (low word only) based on either a specified field or a callback function. Returns a
DataStoreStructureError
value (DSSE_NO_ERROR if successful). Takes the following arguments:
DataStoreIndexCallbackParams
structure. To build an index on a field, specify the field in DSICP
_indexField
. Set DSICP
_sortOrder
to SO_ASCENDING or SO_DESCENDING. If you specify a callback, the caller will pass DSICP
_cbData
, DSICP
_rec1
and DSICP
_rec2
to the callback.typedef struct { FieldID DSICP_indexField; SortOrder DSICP_sortOrder; void *DSICP_cbData; RecordHeader *DSICP_rec1; RecordHeader *DSICP_rec1; } DataStoreIndexCallbackParams;
DSICP_rec1
comes before
DSICP_rec2
1 if
DSICP_rec1
comes after
DSICP_rec2
Warnings: Cannot call this routine on datastores that contain more than 4,000 records (will return DSSE_INDEX_RECORD_NUMBER_LIMIT_EXCEEDED).
Include: datastor.h
DataStoreError DataStoreClose( word dsToken); /* session token to opened datastore */
Closes the datastore if no other application has it open; otherwise, closes the "session" associated with
dsToken
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Warnings: Returns DSE_CLOSE_WITH_LOCKED_RECORD if the calling session has a record locked.
Include: datastor.h
DataStoreError DataStoreCreate( DataStoreCreateParams *paramsPtr, word dsToken);
Creates a new datastore, opens a session to it and writes the session token to
dsToken
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful). Takes the following arguments:
DataStoreCreateParams
structure.
DSCP_name
contains the name of the datastore. You can pass DSF_PRIVATE, DSF_TIMESTAMP and/or DSF_NO_PRIMARY_KEY to
DSCP_flags. DSCP_keyList
and
DSCP_keyCount
contain the list and number of key field(s), respectively. Specify the object to receive notification of datastore changes in
DSCP_notifObject
.typedef struct { TCHAR *DSCP_name; DataStoreFlags DSCP_flags; FieldDescriptor *DSCP_keyList; word DSCP_keyCount; optr DSCP_notifObject; } DataStoreCreateParams;
Include: datastor.h
DataStoreError DataStoreDelete( TCHAR *dsNamePtr);
Deletes the named datastore if no other application(s) has(have) it open. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreStructureError DataStoreDeleteField( word dsToken, /* session token to opened datastore */ TCHAR *fieldNamePtr, FieldID fieldID);
Deletes the passed field from the datastore. Returns a
DataStoreStructureError
value (DSSE_NO_ERROR if successful).
You can reference a field by its name or
FieldID
. If referencing by name, pass "0" in
fieldID
; if referencing by
FieldID
, pass NULL in
fieldNamePtr
.
Warnings: Cannot delete key fields.
Cannot delete a field if an application has locked any record in the datastore (will return DSSE_ACCESS_DENIED).
Include: datastor.h
See Also: DataStoreRemoveFieldFromRecord()
.
DataStoreDataError DataStoreDeleteRecord( word dsToken, /* session token to opened datastore */ RecordID recordID);
Deletes the passed record (referenced by its
RecordID
) and flushes it from the record buffer if it is the current record. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Warnings: Cannot delete a record that has been locked or loaded into memory (will return DSDE_RECORD_IN_USE).
Include: datastor.h
See Also: DataStoreDeleteRecordNum()
.
DataStoreDataError DataStoreDeleteRecordNum( word dsToken, /* session token to opened datastore */ RecordNum recordNum);
Deletes the passed record (referenced by its
RecordNum
) and flushes it from the record buffer if it is the current record. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Warnings: Cannot delete a record that has been locked or loaded into memory (will return DSDE_RECORD_IN_USE).
Include: datastor.h
See Also: DataStoreDeleteRecord()
.
DataStoreDataError DataStoreDiscardRecord( word dsToken); /* session token to opened datastore */
Flushes the current record from the record buffer (without saving any changes). Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Include: datastor.h
See Also: DataStoreSaveRecord()
.
DataStoreError DataStoreFieldEnum( word dsToken, RecordHeader *recordPtr, void *enumDataPtr, Boolean _pascal (*CallbackRoutine) ( void *fieldDataPtr, word fieldDataSize, FieldType fieldType, FieldCategory fieldCat, FieldID fieldID, FieldFlags flags, void *enumDataPtr));
Enumerates through the fields in the passed record. When the callback returns TRUE, stops enumeration and returns DSE_NO_ERROR. Takes the following arguments:recordPtr
RecordHeader
structure.typedef struct { RecordID RH_id; word RH_size; byte RH_fieldCount; } RecordHeader;
Be Sure To: Lock the record first with
DataStoreLockRecord()
before calling this routine.
Warnings: Callback can modify data passed in enumDataPtr but cannot modify any actual field data.
Include: datastor.h
See Also: DataStoreRecordEnum()
.
DataStoreStructureError DataStoreFieldIDToName( word dsToken, /* session token to opened datastore */ FieldID fieldID, TCHAR *fieldNamePtr, word *nameSizePtr);
Writes the field name corresponding to the passed
FieldID
(
fieldID
) to
fieldNamePtr
. Copies no more than nameSizePtr bytes and overwrites this same parameter with the number of bytes actually copied. Returns a
DataStoreStructureError
value (DSSE_NO_ERROR if successful).
Include: datastor.h
See Also: DataStoreFieldNameToID()
.
DataStoreStructureError DataStoreFieldNameToID( word dsToken, /* session token to opened datastore */ TCHAR *fieldNamePtr, FieldID *fieldIDPtr);
Writes the
FieldID
corresponding to the passed field name
(fieldNamePtr
) to
fieldIDPtr
. Returns a
DataStoreStructureError
value (DSSE_NO_ERROR if successful).
Include: datastor.h
See Also: DataStoreFieldIDToName()
.
DataStoreError DataStoreGetExtraData( word dsToken, /* session token to opened datastore */ void *dataPtr, /* data read from file header */ word *dataSizePtr);
Writes any extra data for this datastore to
dataPtr
. Writes the number of bytes copied to
dataSizePtr
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreDataError DataStoreGetField( word dsToken, /* session token to opened datastore */ TCHAR *fieldNamePtr, FieldID fieldID, void **blockPtrPtr, word *blockSizePtr, MemHandle *blockHanPtr);
Writes contents of the passed field to a block. If
blockPtrPtr
is NULL, allocates a block and writes its handle to
blockHanPtr
and its size to
blockSizePtr
. If
blockPtrPtr
is not NULL and field data exceeds block size, copies
blockSizePtr
bytes to the block and returns DSDE_EXCEEDS_BUFFER_SIZE. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
If referencing field by name, pass "0" in
fieldID
; if referencing field by
FieldID
, pass NULL in
fieldNamePtr
.
Warnings: If the passed field is not present, writes "0" to blockSizePtr and returns DSDE_NO_ERROR.
Include: datastor.h
See Also: DataStoreGetFieldChunk()
.
DataStoreDataError DataStoreGetFieldChunk( word dsToken, /* session token to opened datastore */ TCHAR *fieldNamePtr, FieldID fieldID, MemHandle blockHan, ChunkHandle *chunkHanPtr, word *dataSizePtr);
Writes contents of the passed field to a chunk in the passed block. If
chunkHanPtr
is NULL, allocates a chunk and writes its handle to
chunkHanPtr
. If
chunkHanPtr
is not NULL dataSizePtrand field data exceeds chunk size, resizes the chunk and writes the number of bytes copied to
dataSizePtr
. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
If referencing field by name, pass "0" in
fieldID
; if referencing field by
FieldID
, pass NULL in
fieldNamePtr
.
Warnings: If the passed field is not present, writes "0" to dataSizePtr and returns DSDE_NO_ERROR.
Include: datastor.h
See Also: DataStoreGetField()
.
DataStoreError DataStoreGetFieldCount( word dsToken, /* session token to opened datastore */ word *fieldCountPtr);
Writes the number of fields defined for this datastore to
fieldCountPtr
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
See Also: DataStoreGetRecordCount()
.
DataStoreStructureError DataStoreGetFieldInfo( word dsToken, /* session token to opened datastore */ FieldDescriptor *fieldDescPtr, FieldID fieldID, word fieldNameSize);
Writes
FieldDescriptor
for passed field to fieldDescPtr. For
FD_name
, writes
fieldNameSize
bytes only; pass "0" (and set
FD_name
to NULL) if you don't need the field name. Returns a
DataStoreStructureError
value (DSSE_NO_ERROR if successful).
Include: datastor.h
DataStoreDataError DataStoreGetFieldPtr( word dsToken, /* session token to opened datastore */ RecordHeader *recordPtr, FieldID fieldID, void **fieldContentPtrPtr, FieldType *fieldTypePtr, word *fieldSizePtr);
Gets a pointer to the field specified by
fieldID
. Writes the field's content to
fieldContentPtrPtr
, its
FieldType
to
fieldTypePtr
, and its size to
fieldSizePtr
. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Include: datastor.h
DataStoreDataError DataStoreGetFieldSize( word dsToken, /* session token to opened datastore */ TCHAR *fieldNamePtr, FieldID fieldID, word *fieldSizePtr);
Writes the number of bytes in the passed field to
fieldSizePtr
. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
If referencing field by name, pass "0" in
fieldID
; if referencing field by
FieldID
, pass NULL in
fieldNamePtr
.
Warnings: If the field is not present, writes "0" to fieldSizePtr and returns DSDE_NO_ERROR.
Include: datastor.h
DataStoreError DataStoreGetFlags( word dsToken, /* session token to opened datastore */ DataStoreFlags *FlagPtr);
Writes the
DataStoreFlags
set for this datastore to
flagPtr
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreError DataStoreGetNextRecordID( word dsToken, /* session token to opened datastore */ RecordID *nextIDPtr);
Writes the next
RecordID
to be assigned to
nextIDPtr
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreDataError DataStoreGetNumFields( word dsToken, /* session token to opened datastore */ word *fieldCountPtr);
Writes the number of fields in the current record to
fieldCountPtr
. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Include: datastor.h
DataStoreError DataStoreGetOwner( word dsToken, /* session token to opened datastore */ GeodeToken *tokenPtr);
Writes the GeodeToken of the application that created the datastore to
tokenPtr
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreError DataStoreGetRecordCount( word dsToken, /* session token to opened datastore */ dword *RecordCountPtr);
Writes the number of records in the datastore to
recordCountPtr
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Warnings: Does not count new records that have not yet been saved.
Include: datastor.h
See Also: DataStoreGetFieldCount()
.
DataStoreDataError DataStoreGetRecordID( word dsToken, /* session token to opened datastore */ RecordID *recordIDPtr);
Writes the
RecordID
of the current record to
recordIDPtr
. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Warnings: If no record is loaded, returns DSDE_RECORD_BUFFER_EMPTY.
Include: datastor.h
DataStoreError DataStoreGetTimeStamp( word dsToken, /* session token to opened datastore */ FileDateAndTime *timestampPtr);
Writes the date and time that the datastore was last modified to
timestampPtr
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreError DataStoreGetVersion( word dsToken, /* session token to opened datastore */ ProtocolNumber *versionPtr);
Writes the protocol number of the datastore to
versionPtr
. (Protocol numbers are useful for keeping track of different versions of a datastore.) Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreDataError DataStoreLoadRecord( word dsToken, /* session token to opened datastore */ RecordID recordID, RecordNum *recordNumPtr);
Loads the record referenced by
recordID
into memory and makes it the current record. Writes the
RecordNum
of the loaded record to
recordNumPtr
. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Warnings: Returns DSDE_RECORD_BUFFER_NOT_EMPTY if there is already a record loaded in the session's record buffer.
Returns DSDE_INVALID_RECORD_NUMBER if there is no such record.
Returns DSDE_RECORD_IN_USE if another session has already locked the record.
Include: datastor.h
See Also: DataStoreLoadRecordNum()
.
DataStoreDataError DataStoreLoadRecordNum( word dsToken, /* session token to opened datastore */ RecordNum recordNum, RecordID *recordIDPtr);
Loads the record referenced by
recordNum
into memory and makes it the current record. Writes the
RecordID
of the loaded record to
recordIDPtr
. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Warnings: Returns DSDE_RECORD_BUFFER_NOT_EMPTY if there is already a record loaded in the session's record buffer.
Returns DSDE_INVALID_RECORD_NUMBER if there is no such record.
Returns DSDE_RECORD_IN_USE if another session has already locked the record.
Include: datastor.h
See Also: DataStoreLoadRecord()
.
DataStoreDataError DataStoreLockRecord( word dsToken, /* session token to opened datastore */ RecordHeader **recordPtrPtr);
Locks the current record. Used primarily when calling
DataStoreFieldEnum()
. Also used when calling
DataStoreGetFieldPtr()
. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Be Sure To: Unlock the locked record with
DataStoreUnlockRecord()
when you are through with the record.
Warnings: Returns DSDE_RECORD_BUFFER_EMPTY if there is no record loaded in the buffer.
Include: datastor.h
See Also: DataStoreUnlockRecord()
.
DataStoreDataError DataStoreMapRecordNumToID( word dsToken, /* session token to opened datastore */ RecordNum recordNum, RecordID *recordIDPtr);
Writes the
RecordID
corresponding to the passed
RecordNum
to
recordIDPtr
. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Include: datastor.h
DataStoreDataError DataStoreNewRecord( word dsToken); /* session token to opened datastore */
Creates a new (empty) record and makes it the current record. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Warnings: A new record becomes a permanent part of the datatstore only after it is saved (with
DataStoreSaveRecord()
).
Include: datastor.h
DataStoreError DataStoreOpen( TCHAR *dsNamePtr, optr notifyObject, DataStoreOpenFlags openFlag, word *dsTokenPtr);
Opens the datastore referenced by
dsNamePtr
and writes the session token to
dsTokenPtr
. Passing DSOF_EXCLUSIVE in
openFlag
opens the datastore with access restricted to the caller; if another application already has the datastore open, returns DSE_ACCESS_DENIED. Passing NullOptr in
notifyObject
means no object will receive GWNT_DATASTORE_CHANGE notifications. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreError DataStoreRecordEnum( word dsToken, RecordNum *startRecordPtr, DataStoreRecordEnumFlags flags, void *enumDataPtr, Boolean _pascal (*CallbackRoutine) ( RecordHeader record, void *enumDataPtr));
Enumerates through the records of a datastore in storage order. When CallbackRoutine returns TRUE, stops enumeration, updates
startRecordPtr
with the
RecordNum
of the last record examined, and returns DSE_NO_ERROR. (To continue enumeration, increment
startRecordPtr
.) Returns DSE_NO_MORE_RECORDS if first or last record is reached.
Takes the following arguments:
RecordNum
at which to start enumeration (unless DSREF_START_AT_END is passed [in flags] in which case this argument is ignored).
DataStoreRecordEnumFlags
to pass. Passing DSREF_BACKWARDS causes enumeration to go backwards. Passing DSREF_START_AT_END with DSREF_BACKWARDS causes enumeration to go backwards starting at the last record. (Passing DSREF_START_AT_END without DSREF_BACKWARDS causes enumeration to start at the first record, ignoring whatever value is in startRecordPtr.)
RecordHeader
of the current record and enumDataPtr. Returning TRUE ends enumeration.Warnings: Callback can modify data passed in enumDataPtr but cannot modify any actual data in the record.
Datastore cannot be modified during enumeration.
Include: datastor.h
See Also: DataStoreFieldEnum()
,
DataStoreStringSearch()
.
DataStoreDataError DataStoreRemoveFieldFromRecord( word dsToken, /* session token to opened datastore */ TCHAR *fieldNamePtr, FieldID fieldID);
Deletes the passed field from the current record. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
If referencing field by name, pass "0" in
fieldID
; if referencing field by
FieldID
, pass NULL in
fieldNamePtr
.
Include: datastor.h
See Also: DataStoreDeleteField()
.
DataStoreError DataStoreRename( TCHAR *oldNamePtr, TCHAR *newNamePtr);
Changes the name of a datastore from
oldNamePtr
to
newNamePtr
. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreStructureError DataStoreRenameField( word dsToken, /* session token to opened datastore */ TCHAR *newNamePtr, TCHAR *oldNamePtr, FieldID fieldID);
Changes the name of a field from
oldNamePtr
to
newNamePtr
. Returns a
DataStoreStructureError
value (DSSE_NO_ERROR if successful).
If referencing field by name, pass "0" in
fieldID
; if referencing field by
FieldID
, pass NULL in
oldNamePtr
.
Warnings: Returns DSSE_FIELD_NAME_TOO_LONG if new name exceeds MAX_FIELD_NAME_LENGTH ( i.e. , 40 * sizeof(TCHAR)).
Include: datastor.h
DataStoreDataError DataStoreSaveRecord( word dsToken, void *dataPtr, sword _pascal (*CallbackRoutine) ( RecordHeader *Rec1Ptr, RecordHeader *Rec2Ptr, word dsToken, void *dataPtr), RecordNum *recordNumPtr, RecordID *recordIDPtr);
Writes the current record to the datastore (saving any changes made to the record) and flushes the record from the buffer. If CallbackRoutine is "0", inserts saved record to the key (if a key exists) or appends the record to the end of the datastore if no key exists. Writes the
RecordNum
and
RecordID
of the saved record to recordNumPtr and recordIDPtr, respectively. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful). Takes the following arguments:
RecordHeader
s of two records to compare. Caller can also pass extra data with dataPtr. The function should return:
RecordNum
of saved record.
RecordID
of saved record.Include: datastor.h
See Also: DataStoreDiscardRecord()
.
DataStoreError DataStoreSetExtraData( word dsToken, /* session token to opened datastore */ void *extraDataPtr, /* data to write to file header */ word extraDataSize);
Writes
extraDataSize
bytes of extra data to the datastore file header, replacing any existing extra data. Passing "0" in
extraDataSize
deletes any existing extra data. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreDataError DataStoreSetField( word dsToken, /* session token to opened datastore */ TCHAR *fieldNamePtr, FieldID fieldID, void *dataPtr, word dataSize);
Writes
dataSize
bytes of data (dataPtr) to the passed field. Passing "0" in
dataSize
deletes the field from the record. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
If referencing field by name, pass "0" in
fieldID
; if referencing field by
FieldID
, pass NULL in
fieldNamePtr
.
Include: datastor.hblockHan
DataStoreError DataStoreSetNextRecordID( word dsToken, /* session token to opened datastore */ RecordID nextID);
Sets the next
RecordID
to be assigned to nextID. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
See Also: DataStoreSetRecordID()
.
DataStoreDataError DataStoreSetRecordID( word dsToken, /* session token to opened datastore */ RecordID recordID);
Sets the
RecordID
of the current record to recordID; datastore must be opened for exclusive access. If the passed
RecordID
is greater than the next
RecordID
to be assigned, updates the latter with the passed
RecordID
+ 1. Returns a
DataStoreDataError
value (DSDE_NO_ERROR if successful).
Warnings: Overwrites any existing record with the same
RecordID
as the passed value.
Include: datastor.h
See Also: DataStoreSetNextRecordID()
.
DataStoreError DataStoreSetTimeStamp( word dsToken, /* session token to opened datastore */ FileDateAndTime timestamp);
Sets date and time that datastore was last modified to timestamp.
Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreError DataStoreSetVersion( word dsToken, /* session token to opened datastore */ ProtocolNumber version);
Sets the datastore's protocol number; this is useful for keeping track of different versions of a datastore. Returns a
DataStoreError
value (DSE_NO_ERROR if successful).
Include: datastor.h
DataStoreError DataStoreStringSearch( word dsToken, /* session token to opened datastore */ SearchParams *paramsPtr);
Performs a string search on the datastore. If it finds a match, updates SP
_startRecord
with the
RecordNum
of the matching record and returns DSE_NO_ERROR. If it reaches the first or last record without finding a match, returns DSE_NO_MORE_RECORDS. Takes the following arguments:
SearchParams
structure.typedef struct { SearchType SP_searchType; RecordNum SP_startRecord; dword SP_maxRecords; FieldID SP_startField; FieldCategory SP_category; TCHAR *SP_searchString; SearchFlags SP_flags; } SearchParams;
Warnings: Returns DSSE_INDEX_RECORD_NUMBER_LIMIT_EXCEEDED if you call this routine on a datastore with more than 4,000 records.
Include: datastor.h
See Also: DataStoreRecordEnum()
,
DataStoreFieldEnum()
.
void DataStoreUnlockRecord( word dsToken); /* session token to opened datastore */
Unlocks the current record. If you lock a record with
DataStoreLock()
, you must unlock it with this routine.
Include: datastor.h
See Also: DataStoreLockRecord()
.
DBItem DBAlloc( VMFileHandle file, DBGroup group, word size);
This routine allocates an item in the specified file and group. It is passed the handles for the file and group which will contain the new item. It returns the new item's item-handle.
Warnings: All pointers to items in the group may be invalidated.
Include: dbase.h
See Also: DBAllocUngrouped()
.
DBGroupAndItem DBAllocUngrouped( VMFileHandle file, word size);
This routine allocates an ungrouped item in the specified file. It is passed the handle of the file which will contain the new item. It returns the item's
DBGroupAndItem
value.
Warnings: All pointers to ungrouped items may be invalidated.
Include: dbase.h
See Also: DBAlloc()
.
DBGroupAndItem DBCombineGroupAndItem( DBGroup group, DBItem item);
This macro combines group and item handles into a dword-sized
DBGroupAndItem
value.
Include: dbase.h
See Also: DBGroupFromGroupAndItem()
,
DBItemFromGroupAndItem()
.
DBItem DBCopyDBItem( VMFileHandle srcFile, DBGroup srcGroup, DBItem srcItem, VMFileHandle destFile, DBGroup destGroup);
This routine makes a duplicate of a DB item in the specified DB file and group. It is passed the file handle, group handle, and item handle of the source item, as well as the file handle and group handle of the destination group. It makes a copy of the DB item and returns its
DBItem
handle.
Warnings: All pointers to items in the destination group may be invalidated.
Include: dbase.h
See Also: VMCopyVMChain()
.
DBGroupAndItem DBCopyDBItemUngrouped( VMFileHandle srcFile, DBGroupAndItem srcID, /* source item */ VMFileHandle destFile);
This routine makes a duplicate of a specified DB item. It is passed the file handle and
DBGroupAndItem
value specifying the source item, and the file handle of the destination file. It allocates the item as an ungrouped item in the specified file and returns its
DBGroupAndItem
value.
Tips and Tricks: If the source item is not ungrouped, you can combine the group and item handles into a
DBGroupAndItem
value by calling the macro
DBCombineGroupAndItem()
.
Warnings: All pointers to ungrouped items in the destination file may be invalidated.
Include: dbase.h
See Also: VMCopyVMChain()
.
void DBDeleteAt( VMFileHandle file, DBGroup group, DBItem item, word deleteOffset, word deleteCount);
This routine deletes a sequence of bytes from within an item. It does not invalidate pointers to other items. The routine is passed the file, group, and item handles specifying the item, as well as an offset within the item and a number of bytes to delete. It will delete the specified number of bytes from within the item, starting with the byte at the specified offset.
Include: dbase.h
void DBDeleteAtUngrouped( VMFileHandle file, DBGroupAndItem id, word deleteOffset, word deleteCount);
This routine is just like
DBDeleteAt()
, except it is passed a
DBGroupAndItem
value instead of separate group and item handles. It does not invalidate pointers to other items.
Include: dbase.h
void * DBDeref( optr *ref);
This routine is passed an optr to a locked DB item. The routine returns the address of the item.
Warnings: The optr becomes invalid when the DB item is unlocked.
Include: dbase.h
void DBUnlock( const void * ptr);
This routine marks a DB item as dirty; this insures that the VM manager will copy its item-block back to the disk before freeing its memory. The routine is passed a pointer to anywhere within the item.
Tips and Tricks: All the items in an item block are marked dirty at once; thus, you can call this routine just once for several items in the same item block. Only the segment portion of the pointer is significant; thus, you can pass a pointer to anywhere in the item. This is useful if you have incremented the pointer to the item.
Include: dbase.h
void DBFree( VMFileHandle file, DBGroup group, DBItem item);
This routine frees the specified item. It does not invalidate pointers to other items in the group. It is passed the file, group, and item handles specifying the item; it does not return anything.
Never Use Situations:
Never call
DBFree()
on a locked item. If you do, the item-block's lock count will not be decremented, which will prevent the item block from ever being properly unlocked.
Include: dbase.h
See Also: DBFreeUngrouped()
.
void DBFreeUngrouped( VMFileHandle file, DBGroupAndItem id);
This routine frees the specified item. It does not invalidate pointers to other ungrouped items. It is passed the file handle and
DBGroupAndItem
value specifying the item; it does not return anything.
Never Use Situations: Never call
DBFreeUngrouped()
on a locked item. If you do, the item-block's lock count will not be decremented, which will prevent the item block from ever being properly unlocked.
Include: dbase.h
See Also: DBFree()
.
DBGroupAndItem DBGetmap( VMFileHandle file);
This routine returns the
DBGroupAndItem
structure for the passed file's map item. If there is no map item, it returns a null handle.
Include: dbase.h
See Also: DBSetMap()
,
DBLockMap()
.
DBGroup DBGroupAlloc( VMFileHandle file);
This routine allocates a new DB group in the specified file and returns its handle. If the group cannot be allocated,
DBGroupAlloc()
returns a null handle.
Include: dbase.h
void DBGroupFree( VMFileHandle file, DBGroup group);
This routine frees the specified group. This deletes all items and item-blocks associated with the group. It is passed the file and group handle specifying the group. Note that you can free a group even if some of its items are locked; those locked items will also be freed.
Include: dbase.h
DBGroup DBGroupFromGroupAndItem( DBGroupAndItem id);
This macro returns the
DBGroup
portion of a
DBGroupAndItem
value.
Include: dbase.h
void DBInsertAt( VMFileHandle file, DBGroup group, DBItem item, word insertOffset, word insertCount);
This routine inserts bytes at a specified offset within a DB item. The bytes are zero-initialized. It is passed the file, group, and item handles specifying a DB item, as well as an offset within the cell and a number of bytes to insert. It inserts the specified number of bytes beginning at the specified offset; the data which was at the passed offset will end up immediately after the inserted bytes.
Warnings: This routine invalidates pointers to other items in the same group.
Include: dbase.h
void DBInsertAtUngrouped( VMFileHandle file, DBGroupAndItem id, word insertOffset, word insertCount);
This routine is just like
DBInsertAt()
, except it is passed a
DBGroupAndItem
value instead of separate group and item handles.
Warnings: This routine invalidates pointers to other ungrouped items.
Include: dbase.h
DBItem DBItemFromGroupAndItem( DBGroupAndItem id);
This macro returns the
DBItem
portion of a
DBGroupAndItem
value.
Include: dbase.h
void * DBLock( VMFileHandle file, DBGroup group, DBItem item);
This routine locks the specified item and returns a pointer to it. It is passed the file, group, and item handles specifying a DB item. If it fails, it returns a null pointer.
Include: dbase.h
See Also: DBLockGetRef()
,
DBLockUngrouped()
.
void * DBLockGetRef( VMFileHandle file, DBGroup group, DBItem item, optr * ref);
This routine is just like
DBLock()
, except that it writes the item's optr to the passed address.
Include: dbase.h
Warnings: The optr is only valid until the DB item is unlocked.
void * DBLockGetRefUngrouped( VMFileHandle file, DBGroupAndItem id, optr * ref);
This routine is the same as
DBLockGetRef()
, except that it is passed a
DBGroupAndItem
value.
Include: dbase.h
void * DBLockMap( VMFileHandle file);
This routine locks the specified file's map item and returns its address. To unlock the map item, call
DBUnlock()
normally.
Include: dbase.h
See Also: DBLockMap()
.
void * DBLockUngrouped( VMFileHandle file, DBGroupAndItem id);
This routine is the same as
DBLock()
, except that it is passed a
DBGroupAndItem
value.
Include: dbase.h
void DBReAlloc( VMFileHandle file, DBGroup group, DBItem item, word size);
This routine changes the size of a DB item. It is passed the file, group, and item handles specifying the DB item, and a new size for the item (in bytes). If the new size is larger than the old, space will be added to the end of the item; if the new size is smaller than the old, the item will be truncated to fit.
Warnings: If the new size is larger than the old, all pointers to items in the group are invalidated. Space added is not zero-initialized.
Include: dbase.h
void DBReAllocUngrouped( VMFileHandle file, DBGroupAndItem id, word size);
This routine is just like
DBReAlloc()
, except it is passed a
DBGroupAndItem
value instead of separate group and item handles.
Warnings: If the new size is larger than the old, all pointers to ungrouped items are invalidated. Space added is not zero-initialized.
Include: dbase.h
void DBSetMap( VMFileHandle file, DBGroup group, DBItem item);
This routine sets the DB map item. You can later retrieve a
DBGroupAndItem
structure identifying this item by calling
DBGetMap()
. The routine is passed the file, group, and item handles specifying the new map item; it does not return anything.
Include: dbase.h
void DBSetMapUngrouped( VMFileHandle file, DBGroupAndItem id);
This routine is just like
DBSetMap()
, except it is passed a
DBGroupAndItem
value instead of separate group and item handles.
Include: dbase.h
void DBUnlock( void * ptr); /* address of item to unlock */
This routine unlocks the DB item whose address is passed.
Tips and Tricks: Only the segment address of the pointer is significant. Thus, you can pass a pointer to somewhere within an item (or immediately after it) to unlock it.
Be Sure To: If the item has been changed, make sure you call
DBDirty()
before
you unlock it.
Include: dbase.h
Boolean DiskCheckInUse( DiskHandle disk);
This routine checks if a registered disk is being used. If a file on that disk is open, or if a path on that disk is on some thread's directory stack, the routine will return true (i.e. non-zero); otherwise it will return false (i.e. zero). Note that a disk may be "in use" even if it is not currently in any drive.
Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file (which is guaranteed to be in use).
Include: disk.h
Boolean DiskCheckUnnamed( /* returns true if disk is unnamed */ DiskHandle disk);
This routine checks if a registered disk has a permanent name. If the disk does not have a name, the routine returns
true
(i.e. non-zero); otherwise it returns
false
. Note that GEOS assigns a temporary name to unnamed disks when they are registered. To find out a disk's temporary or permanent name, call
DiskGetVolumeName()
.
Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.
See Also: DiskGetVolumeName()
.
Include: disk.h
Boolean DiskCheckWritable( DiskHandle disk);
DiskCheckWritable()
checks if a disk is currently writable. It returns
false
(i.e. zero) if the disk is not writable, whether by nature (e.g. a CD-ROM disk) or because the write-protect tab is on; otherwise it returns
true
(i.e. non-zero).
Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.
Include: disk.h
DiskCopyError DiskCopy( word source, word dest, Boolean _pascal (*callback) (DiskCopyCallback code, DiskHandle disk, word param));
This routine copies one disk onto another. The destination disk must be formattable to be the same type as the source disk. The first two arguments specify the source and destination drive. These drives may or may not be the same. If they are different, they must take compatible disks.
A disk copy requires frequent interaction with the user. For example, the copy routine must prompt the user to swap disks when necessary. For this reason,
DiskCopy()
is passed a pointer to a callback routine. This routine handles all interaction with the user. It must be declared _pascal. Each time it is called, it is passed three arguments. The first is a member of the
DiskCopyCallback
enumerated type; this argument specifies what the callback routine should do. The second argument is a disk handle; its significance depends on the value of the
DiskCopyCallback
argument. The third argument is a word-sized piece of data whose significance depends on the value of the
DiskCopyCallback
argument. Note that either of these arguments may be null values, depending on the value of the
DiskCopyCallback
argument.
The callback routine can abort the copy by returning
true
(i.e. non-zero); otherwise, it should return
false
(i.e. zero). The callback routine is called for several situations, identified by the value of
DiskCopyCallback
associated with them:
DriveGetName()
to find the name for this drive.
DiskCopy()
will periodically call the callback routine with this parameter. The callback routine may wish to notify the user how the format is progressing. In this case, the second argument will be meaningless; the third parameter will be the percentage of the destination disk which has been formatted. The callback routine may wish to notify the user how the format is progressing.
DiskCopy()
will periodically call the callback routine with this parameter. The callback routine may wish to notify the user how the copy is progressing. In this case, the second parameter will be meaningless; the third parameter will be the percentage of the copy which has been completed.
If the copy was successful,
DiskCopy()
returns zero. Otherwise, it returns a member of the
DiskCopyError
enumerated type. That type has the following members:
Include: disk.h
DiskHandle DiskFind( const char * fname, /* Null-terminated volume name */ DiskFindResult * code); /* DiskFindResult written here */
This routine returns the handle of the disk with the specified name. If there is no registered disk with the specified name,
DiskFind()
returns a null handle. Note that while disk handles are unique, volume names are not; therefore, there may be several registered disks with identical volume names. For this reason,
DiskFind()
writes a member of the
DiskFindResults
enumerated type (described below) into the space pointed to by the
code
pointer.
Structures:
DiskFind()
uses the
DiskFindResult
enumerated type, which has the following values:
Tips and Tricks: If you want to find all the disks with a given volume name, call
DiskForEach()
and have the callback routine check each disk's name with
DiskGetVolumeName()
.
See Also: DiskRegisterDisk()
.
Include: disk.h
DiskHandle DiskForEach( Boolean _pascal (* callback) (DiskHandle disk)) /* callback returns true * to cancel */
This routine lets you perform an action on every registered disk. It calls the callback routine once for each disk, passing the disk's handle. The callback routine must be declared _pascal. The callback routine can force an early termination by returning
true
(i.e. non-zero). If the callback routine ever returns
true
,
DiskForEach()
terminates and returns the handle of the last disk passed to the callback routine. If the callback routine examines every disk without returning
true
,
DiskForEach()
returns a null handle.
Tips and Tricks:
DiskForEach()
is commonly used to look for a specific disk. The callback routine checks each disk to see if it's the one; if it finds a match, the callback routine simply returns
true
, and
DiskForEach()
returns the disk's handle.
Include: disk.h
FormatError DiskFormat( word driveNumber, MediaType media, /* Format to this size */ DiskFormatFlags flags, /* See flags below */ dword *goodClusters, /* These are filled in at the */ dword *badClusters, /* of the format */ Boolean _pascal (*callback) (word percentDone)); /* Return true to cancel */
This routine formats a disk to the specified size. When it is finished, it fills in the passed pointers to contain the number of good and bad clusters on the disk. (To find out the size of each cluster, call
DiskGetVolumeInfo()
.) The routine returns a member of the
FormatError
enumerated type (whose members are described below).
DiskFormat()
can be instructed to call a callback routine periodically. This allows the application to keep the user informed about how the format is progressing. The callback routine is passed either the percent of the disk which has been formatted, or the cylinder and head currently being formatted. The callback routine must be declared _pascal. The callback routine can cancel the format by returning
true
(i.e. non-zero); otherwise, it should return
false
(i.e. zero).
The third argument passed is a word-length flag field. Currently, only three flags are defined:
DiskFormat()
will do a "soft format" if possible; it will check the sectors and write a blank file allocation table, but it will not necessarily erase the data from the disk.
DiskFormat()
returns a member of the
FormatError
enumerated type. If the format was successful, it will return the constant FMT_DONE (which is guaranteed to equal zero). Otherwise, it will return one of the following constants:
FMT_DRIVE_NOT_READY FMT_ERROR_WRITING_BOOT FMT_ERROR_WRITING_ROOT_DIR FMT_ERROR_WRITING_FAT FMT_ABORTED FMT_SET_VOLUME_NAME_ERROR FMT_CANNOT_FORMAT_FIXED_DISKS_IN_CUR_RELEASE FMT_BAD_PARTITION_TABLE FMT_ERR_NO_PARTITION_FOUND FMT_ERR_CANNOT_ALLOC_SECTOR_BUFFER FMT_ERR_DISK_IS_IN_USE FMT_ERR_WRITE_PROTECTED FMT_ERR_DRIVE_CANNOT_SUPPORT_GIVEN_FORMAT FMT_ERR_INVALID_DRIVE_SPECIFIED FMT_ERR_DRIVE_CANNOT_BE_FORMATTED FMT_ERR_DISK_UNAVAILABLE
Include: disk.h
word DiskGetDrive( DiskHandle dh);
This routine returns the drive number associated with a registered disk. Note that it will do this even if the drive is no longer usable (e.g. if a network drive has been unmapped).
Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.
See Also: DiskFind()
,
DiskRegisterDisk()
.
Include: disk.h
dword DiskGetVolumeFreeSpace( DiskHandle dh);
This routine returns the amount of free space (measured in bytes) on the specified disk. If the disk is, by nature, not writable (e.g. a CD-ROM disk),
DiskGetVolumeFreeSpace()
returns zero and clears the thread's error value. If an error condition exists,
DiskGetVolumeFreeSpace()
returns zero and sets the thread's error value.
Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.
See Also: DiskGetVolumeInfo()
.
Include: disk.h
word DiskGetVolumeInfo( /* Returns 0 if successful */ DiskHandle dh, DiskInfoStruct *info); /* Routine fills this structure */
This routine returns general information about a disk. It returns the following four pieces of information:
The information is written to the passed
DiskInfoStruct
. If an error condition occurs,
DiskGetVolumeInfo()
will return the error code and set the thread's error value; otherwise, it will return zero.
Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.
Include: disk.h
void DiskGetVolumeName( DiskHandle dh, char * buffer); /* Must be VOLUME_NAME_LENGTH_ZT bytes * long */
This routine copies the disk's volume name (as a null-terminated string) to the passed buffer. If an error occurs, it sets the thread's error value. If the volume has no name, the routine returns the current temporary name.
Warnings:
DiskGetVolumeName()
does not check the size of the buffer passed. If the buffer is not at least VOLUME_NAME_LENGTH_ZT bytes long, the routine may write beyond its boundaries.
Tips and Tricks: If you pass a standard path constant, this routine will return information about the disk containing the main geos.ini file.
See Also: DiskGetVolumeInfo()
,
DiskSetVolumeName()
.
DiskHandle DiskRegisterDisk( word driveNumber);
This routine registers a disk in the specified drive and assigns it a disk handle. (The disk handle persists only to the end of the current session of GEOS.) If the disk already has a handle,
DiskRegisterDisk()
will return it. If the disk does not have a name, GEOS will assign it a temporary name (such as "UNNAMED1") and display an alert box telling the user what the temporary name is. (This is done only the first time the disk is registered in each session.) Note that the temporary name is not written to the disk; thus, it persists only until the end of the current session of GEOS.
If this routine returns a disk handle, there's a disk in the drive; if it doesn't, there may still be a disk in the drive, but the disk is unformatted.
Tips and Tricks: There is no harm in registering the same disk several times. Thus, if you want to get the disk handle for the disk in a specific drive, you can simply call
DiskRegisterDisk()
.
See Also: DiskRegisterDiskSilently()
.
Include: disk.h
DiskHandle DiskRegisterDiskSilently( word driveNumber);
This routine is almost identical to
DiskRegisterDisk()
(described immediately above). There is only one difference: If GEOS assigns a temporary name to the disk, it will not present an alert box to the user.
See Also: DiskRegisterDisk()
.
Include: disk.h
DiskHandle DiskRestore( void * buffer, /* buffer written by DiskSave() */ DiskRestoreError _pascal (*callback) (const char *driveName, const char *diskName, void **bufferPtr,
DiskRestoreError error);
DiskRestore()
examines a buffer written by
DiskSave()
and returns the handle of the disk described by that buffer. If that disk is already registered,
DiskRestore()
will simply return its handle. If the disk is not registered and is not in the drive,
DiskRestore()
will call the specified callback routine. The callback routine should be declared _pascal. The callback routine is passed four arguments:
DiskRestore()
routine. This variable is itself a pointer to the opaque data structure provided by
DiskSave()
. If the callback routine takes any action which causes that structure to move (e.g. if it causes the global or local heap containing the buffer to be shuffled), it should update the pointer in
DiskRestore()
.
DiskRestoreError
enumerated type. This is the error which
DiskRestore()
would have returned if there had not been a callback routine. This is usually DRE_REMOVABLE_DRIVE_DOESNT_HOLD_DISK.
The callback routine should prompt the user to insert a disk. If the callback routine was successful, it should return DRE_DISK_IN_DRIVE (which is guaranteed to be equal to zero). Otherwise, it should return a member of the
DiskRestoreError
enumerated type; usually it will return DRE_USER_CANCELLED_RESTORE. Note that the callback routine will not generally know if the user has inserted a disk; it generally just displays an alert box and returns when the user clicks "OK." After the callback routine returns,
DiskRestore()
registers the disk and makes sure that it's the correct one; if it is not, it calls the callback routine again.
You can pass a null function pointer to
DiskRestore()
instead of providing a callback routine. In this case,
DiskRestore()
will fail if the disk has not been registered and is not currently in the drive.
DiskRestore()
returns the handle of the disk. If it fails for any reason, it returns a null handle and sets the thread's error value to a member of the
DiskRestorenError
enumerated type. This type has the following members:
DiskRestore()
will call it under these circumstances.
DiskRestore()
was unable to register the disk in the appropriate drive because it couldn't create a new disk handle.
See Also: DiskSave()
.
Include: disk.h
Boolean DiskSave( DiskHandle disk, void * buffer, /* data will be written here */ word * bufferSize); /* Size of buffer (in bytes) */
This routine writes information about a disk in the specified buffer.
DiskRestore()
can use this information to return the disk handle, even in another session of GEOS. The
bufferSize
argument should point to a word containing the size of the buffer (in bytes). If the buffer is large enough,
DiskSave()
will write an opaque data structure into the buffer, and change the value of
*bufferSize
to the actual size of the data structure; any extra buffer space can be freed or otherwise used. In this case,
DiskSave()
will return
true
(i.e. non-zero). If the buffer was too small,
DiskSave()
will return
false
(i.e. zero) and write the size needed into
*bufferSize
.  If
DiskSave()
failed for some other reason, it will return
false
and set
*bufferSize
to zero.
See Also: DiskRestore()
.
Include: disk.h
word DiskSetVolumeName( DiskHandle dh, const char * name); /* Change the name to this */
This routine changes the disk's volume label. If it is successful, it returns zero; otherwise it returns an error code. It also sets or clears the thread's error value appropriately. The following error codes may be returned:
Include: disk.h
word DosExec( const char * prog, DiskHandle progDisk, const char * arguments, const char * execDir, DiskHandle execDisk, DosExecFlags flags);
This routine shuts down GEOS to run a DOS program. It returns an error code if an error occurs or zero if successful. Its parameters are listed below:
prog
progDisk
arguments
execDir
execDisk
is zero, the program will be run in the directory in which GEOS was first started.
execDisk
execDir
.
flags
DosExecFlags
indicating whether the DOS program will give a prompt to the user to return to GEOS. The possible flags are DEF_PROMPT, DEF_FORCED_SHUTDOWN, and DEF_INTERACTIVE. For more information, see the entry for
DosExecFlags
.
If there was no error,
DosExec()
will return zero. Otherwise it will return one of the following error values: ERROR_FILE_NOT_FOUND, ERROR_DOS_EXEC_IN_PROGRESS, ERROR_INSUFFICIENT_MEMORY, or ERROR_ARGS_TOO_LONG.
Include: system.h
MediaType DriveGetDefaultMedia( word driveNumber);
This routine returns the default media type for the specified drive. It returns a member of the
MediaType
enumerated type (described in the Data Structures reference). Note that a drive can be used for media types other than the default. For example, a high-density 3.5-inch drive will have a default media type of MEDIA_1M44, but it can read from, write to, and format 3.5-inch disks with size MEDIA_720K.
See Also: DriveTestMediaSupport()
.
Include: drive.h
word DriveGetExtStatus( word driveNumber);
This routine is much like
DriveGetStatus()
(described immediately below). However, in addition to returning all of the flags set by
DriveGetStatus()
, it also sets additional flags in the upper byte of the return value. It returns the following additional flags:
If an error condition exists,
DriveGetExtStatus()
returns zero.
See Also: DriveGetStatus()
.
Include: drive.h
char * DriveGetName( word driveNumber, /* Get name of this drive */ char * buffer, /* Write name to this buffer */ word bufferSize); /* Size of buffer (in bytes) */
This routine finds the name of a specified drive. You should use this name when prompting the user to take any action regarding this drive (e.g. to insert a disk). The routine writes the name, as a null terminated string, to the buffer passed. It returns a pointer to the trailing null. If the drive does not exist, or the buffer is too small,
DriveGetName()
returns a null pointer.
Include: drive.h
word DriveGetStatus( word driveNumber);
This routine returns the current status of a drive. The drive is specified by its drive number. The routine returns a word of
DriveStatus
flags. These flags are listed below:
DriveType
enumerated type.
If an error condition exists,
DriveGetStatus()
returns zero.
See Also: DriveGetExtStatus()
.
Include: drive.h
Boolean DriveTestMediaSupport( word DriveNumber, MediaType media); /* Desired disk size */
This routine checks whether the specified drive can support disks in the specified size. It returns true (i.e., non-zero) if the drive supports the size.
See Also: DriveGetDefaultMedia()
.
Include: drive.h
void EC(line);
This macro defines a line of code that will only be compiled into the error-checking version of the geode. The
line
parameter of the macro is the actual line of code. When the EC version of the program is compiled, the line will be treated as a normal line of code; when the non-EC version is compiled, the line will be ignored.
See Also: NEC()
.
void EC_BOUNDS(addr);
This macro adds an address check to the error-checking version of a program. When the EC version of the program is compiled, the address check will be included; when the non-EC version is compiled, the address check will be left out. The
addr
parameter is the address or pointer to be checked.
The macro expands to a call to
ECCheckBounds()
on the specified address or pointer. If the address is out of bounds, the program will stop with a call to
FatalError()
.
See Also: ECCheckBounds()
.
void EC_ERROR(code);
This macro inserts a call to
FatalError()
in the error-checking version of the program and does nothing to the non-EC version. When the program gets to this point, it will halt and put up an error message corresponding to the specified error
code
. If a condition should be checked before calling
FatalError()
, you can use EC_ERROR_IF() instead.
void EC_ERROR_IF(test, code);
This macro inserts a conditional call to
FatalError()
in the error-checking version of a program; it does nothing for the non-EC version. The
test
parameter is a Boolean value that, if
true
, will cause the
FatalError()
call to be made. If
test
is
false
,
FatalError()
will not be called.
EC_WARNING(word warningCode);
This macro generates a warning for the debugger when executed by error-checking code; it has no effect when in non-EC code.
Include: ec.h
EC_WARNING_IF(<expr>, word warningCode)
When this macro is executed in error-checking code, it tests <expr>; if <expr> is non-zero, it generates a warning with code
warningCode
for the debugger.
In non-EC code, the macro has no effect (and <expr> is not evaluated).
Include: ec.h
void ECCheckBounds( void *address);
This routine checks to see if the given pointer is within bounds of the block into which it points. If assertions fail, a fatal error will occur. If the "lmem" EC flag is turned on and the pointer points within an LMem block, then this routine will also check that the pointer points to a valid chunk handle or a chunk within the LMem block.
Include: ec.h
void ECCheckChunkArray( optr o);
This routine checks the validity of the specified chunk array. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckChunkArrayHandles( MemHandle mh, ChunkHandle ch);
This routine checks the validity of the specified chunk array. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckClass( ClassStruct *class);
This routine checks that the given pointer actually references a class definition. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckDriverHandle( GeodeHandle gh);
This routine checks that the passed handle actually references a driver. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckEventHandle( EventHandle eh);
This routine checks that the passed handle actually references a stored message. If the assertions fail, a fatal error will occur.
void ECCheckFileHandle( FileHandle file);
This routine checks that the passed handle actually is a file handle and references a file. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckGeodeHandle( GeodeHandle gh);
This routine checks that the passed handle references a loaded geode. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckGStateHandle( GStateHandle gsh);
This routine checks that the passed handle references a GState. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckHugeArray( VMFileHandle vmFile, VMBlockHandle vmBlock);
This routine checks the validity of the passed Huge Array. If the block passed is not the directory block of a Huge Array, the routine fails.
Include: ec.h
void ECCheckLibraryHandle( GeodeHandle gh);
This routine checks that the passed handle references a library. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckLMemChunk( void * chunkPtr);
This routine checks the validity of the chunk pointed to by
chunkPtr
. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckLMemHandle( MemHandle mh);
This routine checks that the passed handle is a memory handle and actually references a local memory block. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckLMemHandleNS( MemHandle mh);
This routine checks that the passed handle is a local memory handle; unlike
ECCheckLMemHandle()
, however, it does not check sharing violations (when threads are illegally using non-sharable memory). If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckLMemObject( optr obj); /* Object must be locked down. */
This routine checks the validity of an object to ensure that it is an object stored in an object block. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckLMemObjectHandles( MemHandle mh, ChunkHandle ch);
This routine checks the validity of an object to ensure that it is an object stored in an object block. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckLMemOD( optr o);
This routine checks the validity of the given local-memory-based object. If assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckLMemODHandles( MemHandle objHan, ChunkHandle objCh);
This routine checks the validity of the given local-memory-based object. If assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckMemHandle( MemHandle mh);
This routine checks that the passed handle is a memory handle that references a memory block. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckMemHandleNS( MemHandle mh);
This routine checks that the passed handle references a memory block; unlike
ECCheckMemHandle()
, however, it will not check for sharing violations (when a thread illegally accesses a non-sharable block). If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckObject( optr obj);
This routine checks the validity of the given locked object. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckObjectHandles( Memhandle mh, ChunkHandle ch);
This routine checks the validity of the given locked object. If the assertions fail, a fatal error will occur.
void ECCheckOD( optr obj);
This routine checks the validity of the given object. Unlike
ECCheckLMemObject()
, however, it allows optrs of Process objects to be specified. If assertions fail, a fatal error will occur.
void ECCheckODHandles( MemHandle objHan, ChunkHandle objCh);
This routine checks the validity of the given object. Unlike
ECCheckLMemObjectHandles()
, however, it allows processes to be specified. If assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckProcessHandle( GeodeHandle gh);
This routine checks that the passed handle actually references a process. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckQueueHandle( QueueHandle qh);
This routine ensures the passed handle references an event queue. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckResourceHandle( MemHandle mh);
This routine ensures that the passed handle references a geode resource. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckStack();
This routine checks to make sure the current stack has not overflown (and is not about to). This routine also enforces a 100-byte gap between the stack bottom and the stack pointer. If assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckThreadHandle( ThreadHandle th);
This routine checks that the passed handle actually references a thread. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECCheckWindowHandle( WindowHandle wh);
This routine checks that the passed handle actually references a window. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECLMemExists( optr o);
This routine checks to see if the specified chunk exists. This routine should be called by applications to check the chunk handle's validity. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECLMemExistsHandles( MemHandle mh, ChunkHandle ch);
This routine checks to see if the specified chunk exists. This routine should be called by applications to check the chunk handle's validity. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECLMemValidateHandle( optr o);
This routine checks that the passed optr points to a local memory chunk. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECLMemValidateHandleHandles( MemHandle mh, ChunkHandle ch);
This routine checks that the passed memory and chunk handles actually reference a local memory chunk. If the assertions fail, a fatal error will occur.
Include: ec.h
void ECLMemValidateHeap( MemHandle mh);
This routine does a complete error-check of the LMem heap. It is used internally and should not be needed by application programmers.
Include: ec.h
void ECMemVerifyHeap()
This routine makes sure the global heap is in a consistent state. If the assertions fail, a fatal error will occur. This routine should likely not be called by anything other than the EC kernel.
Include: ec.h
void ECVMCheckMemHandle( MemHandle han);
This routine checks that the given memory handle is actually linked to a VM block handle. If assertions fail, a fatal error will occur.
Include: ec.h
void ECVMCheckVMBlockHandle( VMFileHandle file, VMBlockHandle block);
This routine checks the validity of the given VM file and block handles. If assertions fail, a fatal error will occur.
Include: ec.h
void ECVMCheckVMFile( VMFileHandle file);
This routine checks the validity of the given VM file handle. If assertions fail, a fatal error will occur.
Include: ec.h
word ElementArrayAddElement( optr arr, /* Handle of element array */ void * element, /* Element to add (if necessary) */ dword callBackData, /* This is passed to the Callback routine */ Boolean _pascal (*callback) (void *elementToAdd, void *elementFromArray, dword valueForCallback));
This routine is used to add elements to an array. It is passed the address of a potential element. It compares the element with each member of an element array. If there are no matches, it adds the element to the array and sets the reference count to one. If there is a match, it increments the reference count of the matching element in the array and returns; it does not add the new element. When you pass the address of an element, make sure you pass the address of the data portion of the element (not the reference-count header).
You can pass a callback routine to
ElementArrayAddElement()
.
ElementArrayAddElement()
will call the callback routine to compare elements and see if they match. The callback routine should be declared _pascal.
ElementArrayAddElement()
passes the callback routine the address of the element you passed it, as well as the address of the data-portion of the element in the array (the part after the
RefElementHeader
structure). If the two elements match (by whatever criteria you use), return
true
; otherwise, return
false