3.6 Routines Q-T


qsort

extern void _pascal qsort(
		void *array, 
		word count, 
		word elementSize,
		PCB(int, compare, (const void *, const void *))); This is a standard quicksort routine. The callback routine must be decared  _pascal.

QueueGetInfo()

word	QueueGetInfo(
		QueueHandle qh);			/* queue to query */ This routine returns information about a specific event queue. Pass the  handle of the queue; for information about the current process' queue, pass a  null handle. This routine returns the number of events (or messages)  currently in the queue.

Include: geode.h


QueueGetMessage()

EventHandle QueueGetMessage(
		QueueHandle qh);			/* queue to query */ This routine returns the next message on the given queue, blocking if the  queue is empty. When a new message is added to the empty queue, this  routine will unblock the thread and return the message. This routine is used  almost exclusively by the kernel.

Include: geode.h


QueuePostMessage()

void	QueuePostMessage(
		QueueHandle		qh,			/* queue to add event to */
		EventHandle		event,		/* event to be added to queue */
		MessageFlags	flags);		/* MF_INSERT_AT_FRONT or zero */ This routine adds the specified *event* to the passed queue. The only valid flag  for this routine is MF_INSERT_AT_FRONT, which will put the event in the  first spot of the queue.

Include: geode.h


RangeEnum()

Boolean	RangeEnum(
		CellFunctionParameters	* cfp,		/* cell function parameters */
		RangeEnumParams			* params);	/* special other parameters */ This routine calls a callback routine for each cell in a specified range. This  routine is passed pointers to two structures, both of which are shown below.  It returns *false* if all the cells were processed, *true* if any of the cells caused  the routine to abort before the end of the range was reached.

Callback Parameters: The callback routine, which must be declared _pascal, receives a RangeEnumCallbackParams structure, which has the following definition:

typedef struct {
	RangeEnumParams			*RECP_params;		/* see below */
/* current row, column, and cell data of cell */
	word			RECP_row;
	word			RECP_column;
	word			RECP_cellData;
} RangeEnumCallbackParams;

The callback routine can do anything with the cell information. It should return false after successfully processing the cell; if an error occurs, or if it wants to abort the RangeEnum(), it should return true.

Structures: The CellFunctionParameters structure has the following definition:

typedef struct {
	CellFunctionParameterFlags		CFP_flags;
		/* can have the following flags:
		 * CFPF_DIRTY
		 *	set parameter block dirty
		 * CFPF_NO_FREE_COUNT
		 *	counts the number of calls to
		 *	a non-special RangeEnum() */
	VMFileHandle			CFP_file;
		/* VM file handle of cell file */
	VMBlockHandle			CFP_rowBlocks[N_ROW_BLOCKS];
		/* array of handles to grouped row blocks */
} CellFunctionParameters;

Include: cell.h


RangeExists()

Boolean	RangeExists( /* returns non-zero if there are cells in range */
		CellFunctionParameters	* cfp,			/* see RangeEnum() */
		word					firstRow,		/* range delimiters */
		byte					firstColumn,
		word					lastRow,
		byte					lastColumn); This routine returns *true* if there are any cells in the specified range. It is  passed a pointer to the **CellFunctionParameters** structure for the cell file,  as well as the indices of the first and last row, and the first and last column,  of the range to check.

Include: cell.h


RangeInsert()

void	RangeInsert(
		CellFunctionParameters	* cfp,		/* see RangeEnum() */
		RangeInsertParams		* rep);		/* parameters structure */ This routine shifts existing cells to make room for new ones. (It does not  actually create new cells.) Which cells are shifted, and in what direction, is  specified by the **RangeInsertParams()** structure. This structure has three  fields:

RIP_bounds - A Rectangle structure which specifies which cells should be shifted. The cells currently in this range will be shifted across or down, depending on the value of RIP_delta; the shifted cells displace more cells, and so on, to the edge of the visible portion of the cell file. To insert an entire row (which is much faster than inserting a partial row), set RIP_bounds.R_left = 0 and RIP_bounds.R_right = LARGEST_COLUMN.

RIP_delta - A Point structure which specifies how far the cells should be shifted and in which direction. If the range of cells is to be shifted horizontally, RIP_delta.P_x should specify how far the cells should be shifted over, and RIP_delta.P_y should be zero. If the cells are to be shifted vertically, RIP_delta.P_y should specify how far the cells should be shifted down, and RIP_delta.P_x should be zero.

RIP_cfp - This is the address of the CellFunctionParameters structure. You don’t have to initialize this; the routine will do so automatically.

Include: cell.h

Warnings: If cells are shifted off the “visible” portion of the cell file, you will be unable to access them by row or column numbers; but they will not be deleted. For this reason, you should free all such cells before calling RangeInsert(). (You can find out if there are any cells at the edges by calling RangeExists().) For an explanation of the “visible” and “scratch-pad” portions of a cell file, see Section 19.4.1 of the Concepts book.


realloc()

void *	realloc(
		void *		blockPtr,		/* address of memory to resize */
		size_t		newSize);		/* New size of memory 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.

If a geode needs to change the size of a section of memory assigned to it by the malloc() family of routines, it should use realloc(). realloc() resizes the piece of memory specified and returns the memory’s new base address.

If the new size is smaller then the previous size, bytes will be cut off from the end. The request is guaranteed to succeed. Furthermore, the memory will not be moved; the address returned will be the same as the address passed.

If the new size is larger than the previous size, realloc() may move the data to accommodate the request. If so, it will return the new address. The new memory added will not be zero-initialized. If realloc() cannot fulfill the request, it will return a null pointer, and the memory will not be altered.

Resizing a stretch of memory down to zero bytes is exactly the same as freeing it with free(). If you pass a null address to realloc(), it will allocate the memory the same way malloc() does.

The memory must be in a malloc-block assigned to the geode calling realloc(). If you want to resize memory in another geode’s malloc-block, call GeoReAlloc().

Warnings: Pass exactly the same address as the one returned to you when you allocated the memory. If you pass a different address, the results are undefined.

See Also: calloc(), free(), malloc(), GeoReAlloc()


SerialClose()

StreamError SerialClose(
		GeodeHandle 		driver,
		SerialUnit 			unit,
		Boolean 			linger); Close the stream to a serial port.

SerialCloseWithoutReset()

StreamError SerialClose(
		GeodeHandle 		driver,
		SerialUnit 			unit,
		Boolean 			linger); Close the stream to a serial port, without actually resetting the port.

SerialFlush()

StreamError SerialFlush(
		GeodeHandle 		driver,
		SerialUnit			unit,
		StreamRoles 		roles); Flush all data pending in a serial port's input or output buffer (depending on  the value of *roles*).

SerialGetFormat()

StreamError SerialGetFormat(
		GeodeHandle 		driver,
		SerialUnit 			unit,
		SerialFormat *		format,
		SerialMode *		mode,
		SerialBaud *		baud); Get the format of a stream to a specified serial port.

SerialGetModem()

StreamError SerialGetModem(
		GeodeHandle 		driver,
		SerialUnit			unit,
		SerialModem *		modem); Read a modem's hardware flow control bits.

SerialOpen()

StreamError SerialOpen(
		GeodeHandle 		driver,
		SerialUnit 			unit,
		StreamOpenFlags 	flags,
		word 				inBuffSize,
		word				outBuffSize,
		word 				timeout); This routine opens a stream to the specified serial port. It is passed the  following arguments:

driver - The GeodeToken of the serial driver.

unit - The serial port to open.

flags - This specifies whether the call should fail if the port is busy, or wait for a time to see if it will become free.

inBuffSize - The size of the stream buffer used for input from the serial port.

outBuffSize - The size of the stream buffer used for output to the serial port.

timeout - The number of clock ticks to wait for the port to become free. (This argument is ignored if flags is not STREAM_OPEN_TIMEOUT.)

If the routine is successful, it returns zero. If it is unsuccessful, it returns a member of the StreamError enumerated type.


SerialQuery()

StreamError SerialQuery(
		GeodeHandle 		driver,
		SerialUnit 			unit,
		StreamRoles			role,
		word *				bytesAvailable); Find out how much space is available in a serial buffer, or how much data is  waiting to be read.

SerialRead()

StreamError SerialRead (
		GeodeHandle 	driver,
		SerialUnit 		unit,
		StreamBlocker 	blocker,
		word 			buffSize,
		byte *			buffer,
		word *			numBytesRead); Read data from a serial port and write it to a passed buffer.

SerialReadByte()

StreamError SerialReadByte (
		GeodeHandle 	driver,
		SerialUnit 		unit,
		StreamBlocker 	blocker,
		word 			buffSize,
		byte *			dataByte); Read a byte of data from a serial port and write it to a passed variable.

SerialSetFormat()

StreamError SerialSetFormat(
		GeodeHandle 		driver,
		SerialUnit 		unit,
		SerialFormat 		format,
		SerialMode		mode,
		SerialBaud 		baud); Set the format for a stream to a specified serial port.

SerialSetModem()

StreamError SerialSetModem(
		GeodeHandle 		driver,
		SerialUnit			unit,
		SerialModem 		modem); Set a modem's hardware flow control bits.

SerialWrite()

StreamError SerialWrite(
		GeodeHandle 		driver,
		SerialUnit 			unit,
		StreamBlocker 		blocker,
		word 				buffSize,
		const byte *		buffer,
		word *				numBytesWritten); Write data to a serial port.

SerialWriteByte()

StreamError SerialWrite(
		GeodeHandle 		driver,
		SerialUnit 			unit,
		StreamBlocker 		blocker,
		word 				buffSize,
		byte				dataByte); Write one byte of data to a serial port.

SGC_MACHINE

byte	SGC_MACHINE(val);
		dword	val; This macro is used to extract the machine type from a **SysGetConfig()**  return value.

Include: system.goh


SGC_PROCESSOR

byte	SGC_PROCESSOR(val);
		dword	val; This macro is used to extract the processor type from a **SysGetConfig()**  return value.

Include: system.goh


SoundAllocMusic()

MemHandle 	SoundAllocMusic(
		const word 		*song, 
		word 			voices ); This routine takes a pointer to a fixed buffer of music and returns a  **MemHandle** which may then be passed to **SoundPlayMusic()** to play the  music. If the music buffer is in a movable resource, you must initialize it  using **SoundInitMusic()** instead of **SoundAllocMusic()**. To find out how to  set up one of these buffers of music, see "Sound Library," Chapter 13 of the  Concepts book. The *voices* argument is the number of voices in the buffer. 

SoundAllocMusicNote()

MemHandle SoundAllocMusicNote(
		word _far 		instrument, 
		word 			frequency, 
		word 			volume,
		word 			DeltaType, 
		word 			duration); This routine allocates a **MemHandle** which may be passed to  **SoundPlayMusicNote()**. You must provide all information about the note:  its frequency, volume, and duration. You may specify an instrument, passing  a value corresponding to a standard *instrument* (such as IP_PIANO). Specify  the frequency in Hertz or use one of the constants such as MIDDLE_C_b to  specify a standard note frequency. Volume ranges from zero to 0xffff-you  may wish to use a constant value such as DYNAMIC_FFF if you want help  trying to choose a loudness. The note's duration is determined by its delta  type, one of SSDTT_MSEC, SSDTT_TICKS, and SSDTT_TEMPO. If you pass  SSDTT_MSEC or SSDTT_TICKS, the duration is measured in milliseconds or  ticks (each tick is one sixtieth of a second). If you pass SSDTT_TEMPO, you  may set the size of your time unit when you call **SoundPlayMusicNote()**.  The *duration* determines how many time units the note should play. If the  delta type is SSDTT_TICKS and *duration* is 30, then the note will sound for  half a second.

SoundAllocMusicStream()

MemHandle 	SoundAllocMusicStream(
		word 		streamType,
		word 		priority,
		word 		voices,
		word 		tempo); This routine returns a token suitable for passing to  **SoundPlayMusicToStream()**. It is passed several arguments. The  **SoundStreamType** determines how much space to allocate for the stream  and will determine how much data can be written to the stream at one time.  If you pass SST_ONE_SHOT, it indicates that the stream will not be explicitly  destroyed, and that your stream should destroy the stream when the song is  done. You must specify how many voices there are in the music buffer. You  must also pass a starting *tempo* for the music stream.

SoundAllocSampleStream()

MemHandle SoundAllocSampleStream(void); This routine allocates a sample stream handle. If the returned handle is *null*,  the library was unavailable (i.e. some other thread has grabbed exclusive  access).

SoundDisableSampleStream()

void 	SoundDisableSampleStream(
		MemHandle 		mh); This routine disassociates the DAC player from the passed sample handle.  Before you play more sounds using the handle, you will have to call  **SoundEnableSampleStream()** again. 

SoundEnableSampleStream()

Boolean 	SoundEnableSampleStream(
		MemHandle 		mh,
		word 			priority,
		word 			rate,
		word 			manufacturerID,
		word 			format); This routine associates a DAC player with the allocated sample handle. You  must pass the sound handle, as returned by **SoundAllocSampleStream()**.  You must also pass certain pieces of information about the sound you will be  playing on the DAC device: the *priority* with which to grab the DAC player  (e.g. SP_STANDARD), the sampling rate, and the *format* of the sample (as  identified by a *manufacturerID* and a **DACSampleFormat** value).

SoundFreeMusic()

void 	SoundFreeMusic(
		MemHandle 		mh); This routine frees up a music handle. The music must not be playing; call  **SoundStopMusic()** if you are not sure. You may not use the music handle  after calling this routine on it.

SoundFreeMusicNote()

void SoundFreeMusicNote(
		MemHandle 		mh); This routine frees up the passed note handle. The note must not be playing  when you call this routine; call **SoundStopMusicNote()** if you are not sure.  You should not try to use the note's handle after freeing it.

SoundFreeMusicStream()

void SoundFreeMusicStream(
		MemHandle 		mh); This routine frees up the music stream's token. No music must be playing via  the stream; call **SoundDisableMusicStream()** if you are not sure. Do not  try to use the stream after calling this routine on it.

SoundFreeSampleStream()

void 	SoundFreeSampleStream(
		MemHandle 		mh); This routine frees the passed sampled sound handle. You must not try to use  this handle after calling this routine on it.

SoundGetExclusive()

void	SoundGetExclusive(void); This routine grabs the exclusive semaphore for the sound library; if another  thread has already grabbed the exclusive, this routine will wait until the  exclusive is released. Sounds which are playing now will be permitted to  finish, but from now on, only the thread calling this routine will be allowed  to play new sounds. When done with the sound library exclusive, call  **SoundReleaseExclusive()**.

SoundGetExclusiveNB()

Boolean	SoundGetExclusiveNB(void); This routine grabs the exclusive semaphore for the sound library, doing so  even if some other thread has already grabbed the exclusive. Sounds which  are playing now will be permitted to finish, but from now on, only the thread  calling this routine will be allowed to play new sounds. This routine will  return *true* if another thread already has exclusive access.

When done with the sound library exclusive, call SoundReleaseExclusive().


SoundInitMusic()

void SoundInitMusic(
		MemHandle 		mh, 
		byte 			voices); This routine initializes a pre-defined simple music buffer structure. If the  music buffer is stored in a fixed block, you can call **SoundAllocMusic()**  instead. This allows a music buffer stored in a block referenced by a pointer  to be playable using **SoundPlayMusic()**.

SoundPlayMusic()

Boolean 	SoundPlayMusic(
		MemHandle 		mh, 
		word			priority,
		word 			tempo, 
		char 			flags); This routine plays a buffer of music previously initialized by  **SoundInitMusic()** or allocated by **SoundAllocMusic()**. The *priority* value  will determine whether your sound will play if other sounds are already  occupying the voices - pass a value such as SP_STANDARD. The *tempo* value  will be used to determine the length of a 1/128th note. If your music buffer  contained any notes whose lengths were measured by SSDTT_TEMPO delta  type, then you should set this value accordingly. The *flags* argument  determines whether the music's handle should be automatically freed when  the sound is done playing. You may pass either or both of the flags  UNLOCK_ON_EOS or DESTROY_ON_EOS.

Remember that you must have called SoundInitMusic() on the music handle before you may use it to play music.

Include: sound.h


SoundPlayMusicNote()

Boolean 	SoundPlayMusicNote(
		MemHandle 		mh,				/* handle of note */
		word 			priority, 
		word			tempo,
		word 			flags); This routine plays a buffer of music previously allocated by  **SoundAllocMusicNote()** - the return value of that function is passed as  *mh*. The *priority* value will determine whether your sound will play if other  sounds are already occupying the voices - pass a value such as  SP_STANDARD. The *tempo* value will be used to determine the length of a  1/128th note. If your note's delta type is SSDTT_TEMPO, then you should set  this value accordingly. The *flags* argument determines whether the notes's  handle should be automatically freed when the note is done playing. You may  pass either or both of the flags UNLOCK_ON_EOS or DESTROY_ON_EOS.

This routine returns true if the library was unavailable (i.e. if some other thread had grabbed the sound exclusive).

Include: sound.h


SoundPlayToMusicStream()

Boolean 	SoundPlayToMusicStream(
		MemHandle 					mh,
		const word					* sample,
		word 						size,
		SampleFormatDescription 	*format); This routine plays a music buffer to a stream. Specify which stream to play  to by means of the token returned by **SoundAllocMusicStream()**. To play  music to the buffer, pass the size of the buffer you are playing and a pointer  to the start of the piece. This piece of buffer must be made up of whole  events - it should not start or end in the middle of an event (e.g. you can't  specify that you want to play a note but not give its frequency, even if you  plan to play another buffer to the stream that might begin with a frequency). 

If you don’t know the size of the buffer, it may be all right - any data in the buffer after the GE_END_OF_SONG will be ignored.


SoundPlayToSampleStream()

Boolean SoundPlayToSampleStream(
		MemHandle 					mh,
		word _far					* sample,
		word 						size,
		SampleFormatDescription 	* format); This routine passes sampled sound data to a DAC player. You must pass a  sample sound handle to this routine - to acquire such a handle, call  **SoundAllocSampleStream()**. The sample sound handle must be  associated with a DAC player - to so associate the handle, call  **SoundEnableSampleStream()**. You must pass a pointer to the *sample*  data, along with the *size* of the sample as measured in bytes. You may change  the *format* information which will determine how the DAC player handles the  data.

SoundReallocMusic()

Boolean 	SoundReallocMusic(
		MemHandle 		mh,
		word _far 		* song); This routine allows you to associate a new music buffer with an existing  music handle. The new music buffer must not have more voices than was  originally requested with **SoundAllocMusic()**. Do not call this routine with  the handle of a sound that may be playing; call **SoundStopMusic()** on the  handle if you are not sure. See "Sound Library," Chapter 13 of the Concepts  book to find out how to set up the buffer of music.

SoundReallocMusicNote()

Boolean 	SoundReallocMusicNote(
		MemHandle 		mh,
		word 			freq,
		word 			vol,
		word 			timer,
		word 			durat,
		word _far		* instrum); This routine allows you to associate new note values with an existing note  handle. Do not call this routine with the handle of a note that may be playing;  call **SoundStopMusicNote()** on the handle if you are not sure. 

SoundReleaseExclusive()

void	SoundReleaseExclusive(void); This routine releases the sound library exclusive semaphore. You will not  need to call this routine unless your code calls **SoundGrabExclusive()** or  **SoundGrabExclusiveNB()**. This routine allows other threads to play  sounds. If another thread called **SoundGrabExclusive()** while your thread  had the exclusive, it will now grab the exclusive.

SoundStopMusic()

Boolean 	SoundStopMusic(
		MemHandle 		mh); 		/* Handle of music buffer */ This routine stops the playing of a simple music buffer. It returns *true* if the  library was unavailable (i.e. some other thread has grabbed the exclusive).

SoundStopMusicNote()

Boolean 	SoundStopMusicNote(
		MemHandle 		mh); This routine stops a note that is playing. Pass the handle of the note, as was  returned by **SoundAllocMusicNote()**. This routine returns true if the  sound library was unavailable (i.e. some other thread has grabbed the  exclusive). 

SoundStopMusicStream()

Boolean 	SoundStopMusicStream(
		MemHandle 		mh); This routine stops any music being played to the stream. All sounds are  flushed from the stream. It takes one argument, the token of the sound  stream, as returned by **SoundAllocMusicStream()**.

SoundStopSampleStream()

void 	SoundStopSampleStream(
		MemHandle 		mh); This routine stops a sound playing through a previously allocated sampled  sound stream.

SpoolConvertPaperSize()

word 	SpoolConvertPaperSize(
		int 		width,			/* width of paper */
		int 		height,			/* height of paper */
		PageType 	pt);			/* type of page */ This routine converts a width and height into a page size number.

Include: spool.goh


SpoolCreatePaperSize()

Boolean 	SpoolCreatePaperSize( /* Returns true if failed */
		word 		* retValue,	/* returns paper size value */
		char 		* name,		/* name of paper size */
		int 		width,		/* width of paper */
		int 		length,		/* length of paper */
		PageLayout	layout);	/* default page layout / This routine defines and stores a new paper size for later use by the user.

Include: spool.goh


SpoolCreatePrinter()

Boolean	SpoolCreatePrinter( 	/* Returns true if error 
								   (printer already exists) */
		char 				*name,		/* name of printer */
		PrinterDriverType 	type,		/* driver type */
		int 				* retVal); 	/* Will hold printer number */ Adds the printer to the list of currently installed printers and returns the  new printer number. This routine is normally called from within the  Preferences manager. Returns *true* if the printer already exists.

Include: spool.goh


SpoolDeletePaperSize()

Boolean 	SpoolDeletePaperSize(
		word 	size);		/* size number to delete */ This routine deletes a user-defined paper size.

Include: spool.goh


SpoolDeletePrinter()

void 	SpoolDeletePrinter(
		int 	prtrNum);		/* printer number to delete */ Deletes the requested printer from the system.

Include: spool.goh


SpoolGetDefaultPrinter()

int 	SpoolGetDefaultPrinter(); /* Returns printer number */ Returns the system-default printer, which is used (for example) by the  **PrintControlClass** as the default printer to print to.

Include: spool.goh


SpoolGetNumPaperSizes()

int 	SpoolGetNumPaperSizes(
		PageType 	type);		/* type of page */ Use this routine to find the number of paper sizes, both pre-defined and  user-defined, that should appear in a paper size list.

Include: spool.goh


SpoolGetNumPrinters()

int 	SpoolGetNumPrinters(
		PrinterDriverType		type);			/* driver type */ This routine returns the number of installed printers with the given type.

Structures:

typedef ByteEnum PrinterDriverType;
/* The driver type may be one of the following:
		PDT_PRINTER,
		PDT_PLOTTER,
		PDT_FACSIMILE,
		PDT_CAMERA,
		PDT_OTHER,
		PDT_ALL		*/

Include: spool.goh


SpoolGetPaperSize()

XYSizeAsDWord SpoolGetPaperSize(
		int 		size, 		/* This must be between 0 and the return 
				 				 * value of SpoolGetNumPaperSizes() */
		PageType 	pt,	 		/* type of page */
		PageLayout 	*layout);	/* Will hold returned page layout */ Use this routine to determine the dimensions of a paper size.

Include: spool.goh


SpoolGetPaperSizeOrder()

dword 	SpoolGetPaperSizeOrder( /* High byte is number of unused sizes;
								 * Low byte is # of ordered sizes */
		PageType 	type,
		byte 		*order, 	/* buffer of size MAX_PAPER_SIZES */
								/* On return, this buffer will be 
								 * filled with the page size numbers
								 * arranged in the order 
								 * corresponding to their display */
		byte 		*userSizes); /* buffer of size MAX_PAPER_SIZES */
							 	 /* On return, will hold ordered 
								 * array of user paper sizes. */

SpoolGetPaperSizeString()

Boolean 	SpoolGetPaperSizeString( /* true if error*/
		char 		* retValue,	/* buffer for returned value */
		int 		size,		/* Must be between 0 and the return
								 * value of SpoolGetNumPaperSizes() */
		PageType	pt);		/* type of page */ Use this routine to determine the string to be displayed for a specific paper  size. Upon return, *retValue* will point to a character string and the Boolean  return value will be *false* if successful. If any error occurs, or if the page type  couldn't be found, the returned value will be *true*.

Include: spool.goh


SpoolGetPrinterString()

Boolean	SpoolGetPrinterString( /* Returns true if error */
		int 	*retValue,	/* On return, will point to length of string */
		char 	*string,	/* returned name string */
		int 	prtrNum);	/* printer number */ This routine fills a buffer with the requested null-terminated printer name  string. If the printer could not be found, the return value will be *true* (set for  error).

Include: spool.goh


SpoolSetDefaultPrinter()

void 	SpoolSetDefaultPrinter(
		int prtrNum);		/* printer number */ Sets the system-default printer, used (for example) by **PrintControlClass**  as the default printer. This routine is normally called from within the  Preferences manager.

Include: spool.goh


SpoolSetDocSize()

void 	SpoolSetDocSize(
		Boolean 		open;			/* false if document is closed */
		PageSizeInfo 	* psr);			/* NULL if document is closed */ This routine tells the application's **PageSizeControl** object the document's  size.

Include: spool.goh


SpoolSetPaperSizeOrder()

void 	SpoolSetPaperSizeOrder(
		void 	* ptr, 		/* Array of PageSizeOrder entries */
		word 	number);	/* number of entries in array */ This routine resets the order in which paper sizes are displayed to the user.

Include: spool.goh


SpreadsheetInitFile()

VMBlockHandle SpreadsheetInitFile(
		const SpreadsheetInitFileData			* ifd); This routine initializes a VM file for use by the spreadsheet object. It allocates  a spreadsheet map block in the file and initializes this block. The routine  returns the map block's handle; applications will need to remember this  handle. It does not change any existing blocks in the VM file.

The ifd parameter is pointer to a SpreadsheetInitFileData structure containing the file handle and the number of rows and columns to allocate.

Structures: The SpreadsheetInitFileData structure is defined as follows:

typedef struct {
	word					SIFD_file;
	word					SIFD_numRows;
	word 					SIFD_numCols;
	SpreadsheetDrawFlags	SIFD_drawFlags;
} SpreadsheetInitFileData;

/* SpreadsheetDrawFlags:
 * SDF_DRAW_GRAPHICS
 * SDF_DRAW_NOTE_BUTTON
 * SDF_DRAW_HEADER_FOOTER_BUTTON
 * SDF_DRAW_GRID				*/

Include: ssheet.goh


StreamClose()

StreamError StreamClose (
		GeodeHandle 		driver,
		StreamToken 		stream,
		Boolean 			linger); This routine shuts down a stream. It is passed the following arguments:

driver - The GeodeToken of the stream driver.

stream - The StreamToken of the stream.

linger - Set true (i.e., non-zero) if the data currently in the stream should be kept until it’s read; set false to flush the data immediately.

If the routine is successful, it returns zero. If it is unsuccessful, it returns a member of the StreamError enumerated type.


StreamFlush()

StreamError StreamFlush (
		GeodeHandle 		driver,
		StreamToken 		stream); This routine flushes all the data pending in a stream. It is passed the  following arguments:

driver - The GeodeToken of the stream driver.

stream - The StreamToken of the stream.

If the routine is successful, it returns zero. If it is unsuccessful, it returns a member of the StreamError enumerated type.


StreamOpen()

StreamError	 StreamOpen (
		GeodeHandle 		driver,
		word 				buffSize,
		GeodeHandle			owner,
		HeapFlags 			heapFlags,
		StreamToken *		stream); This routine opens a stream. It is passed the following:

driver - The GeodeToken of the stream driver.

buffSize - The size of the stream buffer, in bytes.

owner - The geode which will own the stream.

heapFlags - The flags for the creation of the buffer block.

*stream - The stream token will be written here.

If StreamOpen() is successful, it returns zero and writes the stream’s token to stream*. If it is unsuccessful, it returns a member of the **StreamError enumerated type.


StreamQuery()

StreamError StreamQuery (
		GeodeHandle 		driver,
		StreamToken 		stream,
		StreamRoles 		role,
		word *				bytesAvailable); This routine finds out either how much free space is available in a stream's  buffer, or how much data is waiting to be read. It is passed the following  arguments:

driver - The GeodeToken of the stream driver.

stream - The StreamToken of the stream.

role - If this is STREAM_ROLES_WRITER, the routine will return the amount of free space available in the stream buffer. If it is STREAM_ROLES_READER, it will return the amount of data waiting to be read.

*bytesAvailable - The routine will write the number of bytes available (for writing or reading) to this variable.

If the routine is successful, it returns zero. If it is unsuccessful, it returns a member of the StreamError enumerated type.


StreamRead()

StreamError StreamRead (
		GeodeHandle 		driver,
		StreamToken 		stream,
		StreamBlocker 		blocker,
		word 				buffSize,
		byte *				buffer,
		word *				numBytesRead); This routine reads data from a stream. The routine takes the following  arguments:

driver - The GeodeToken of the stream driver.

stream - The StreamToken of the stream.

blocker - Specify whether to block if there is not enough data waiting to be read.

buffsize - Size of passed buffer (i.e. amount of data to read from stream).

buffer - Pointer to buffer where data from stream will be written.

numBytesReadRead* - **StreamRead() will write to this variable the number of bytes actually read from the stream.

If StreamRead() is successful, it returns zero. If it is unsuccessful, or could not read all the data requested from the stream, it returns a member of the StreamError enumerated type.


StreamReadByte()

StreamError StreamWriteByte (
		GeodeHandle 		driver,
		StreamToken 		stream,
		StreamBlocker 		blocker,
		byte *		dataByte); This routine reads a single byte from a stream. It takes the following  arguments:

driver - The GeodeToken of the stream driver.

stream - The StreamToken of the stream.

blocker - Specify whether to block if there is not enough room to write the data.

*dataByte - Read a byte from the stream, and write it to this variable.

If the routine is successful, it returns zero. If it is unsuccessful, it returns a member of the StreamError enumerated type.


StreamWrite()

StreamError StreamWrite (
		GeodeHandle 		driver,
		StreamToken 		stream,
		StreamBlocker 		blocker,
		word 				buffSize,
		const byte *		buffer,
		word *				numBytesWritten); This routine writes data to a stream. The routine takes the following  arguments:

driver - The GeodeToken of the stream driver.

stream - The StreamToken of the stream.

blocker - Specify whether to block if there is not enough room to write all the data.

buffsize - Size of passed data buffer (i.e. amount of data to write to stream).

buffer - Pointer to data to write to stream.

*numBytesWritten - StreamWrite() will write to this variable the number of bytes actually written to the stream.

If StreamWrite() is successful, it returns zero. If it is unsuccessful, or could not write all the data to the stream, it returns a member of the StreamError enumerated type.


StreamWriteByte()

StreamError StreamWriteByte (
		GeodeHandle 		driver,
		StreamToken 		stream,
		StreamBlocker 		blocker,
		byte 				dataByte); This routine writes a single byte to a stream. It takes the following  arguments:

driver - The GeodeToken of the stream driver.

stream - The StreamToken of the stream.

blocker - Specify whether to block if there is not enough room to write the data.

dataByte - Write this byte to the stream.

If the routine is successful, it returns zero. If it is unsuccessful, it returns a member of the StreamError enumerated type.


SysGetConfig()

dword	SysGetConfig(); This routine returns a set of values defining the system configuration. The  returned dword contains four byte values, listed below from least significant  byte to most significant byte:

configuration flags
This byte contains a record of SysConfigFlags reflecting the system status. This record includes information on how the system was started, whether Swat is running it, whether the system was restarted, etc.

reserved byte
This byte contains reserved information unusable by applications.

processor type
This byte contains a value reflecting the processor type of the machine running GEOS. This is of type SysProcessorType and is one of SPT_8088, SPT_8086, SPT_80186, SPT_80286, SPT_80386, or SPT_80486. Use the macro SGC_PROCESSOR to extract this value from the returned dword.

machine type
This byte contains a value of SysMachineType indicating the type of the machine running GEOS. It may be one of the following values: SMT_UNKNOWN, SMT_PC, SMT_PC_CONV, SMT_PC_JR, SMT_PC_XT, SMT_PC_XT_286, SMT_PC_AT, SMT_PS2_30, SMT_PS2_50, SMT_PS2_60, SMT_PS2_80, or SMT_PS1. Use the macro SGC_MACHINE to extract this value from the returned dword.

Include: system.h


SysGetDosEnvironment()

Boolean	SysGetDosEnvironment( /* true if error (not found) */
		const char		* variable,		/* environment variable */
		char			* buffer,		/* buffer for return value */
		word			bufSize);		/* maximum return string length */ This routine looks up a specified DOS environment variable in the  environment buffer. It takes three parameters:

variable - A pointer to the null-terminated character string representing the name of the variable to be searched for.

buffer - A pointer to a locked or fixed buffer in which the variable’s value will be returned.

bufSize - The size of the passed buffer in bytes (the maximum number of characters that can be returned including the terminating null character).

If the variable is not found, the error flag returned will be true.

Include: system.h


SysGetECLevel()

ErrorCheckingFlags SysGetECLevel(
		MemHandle * checksumBlock); This routine checks the current error-checking level of the system. The  returned record of **ErrorCheckingFlags** describes which levels of error  checking are turned on and which are off. If checksum error checking  (ECF_BLOCK_CHECKSUM) is on, pass a pointer to the handle of a block on  which the checksum will be done.

Include: ec.h


SysGetInfo()

dword	SysGetInfo(
		SysGetInfoType info);		/* type of information to retrieve */ This routine returns general system information. Pass the type of  information to be returned; the value returned depends on the type passed in  info. Note that the largest returned value is a dword; many different return  values should be cast to the appropriate type when calling **SysGetInfo()**.

The info parameter (of SysGetInfoType) can have one of the following values:

SGIT_TOTAL_HANDLES
Returns the total number of handles in the kernel’s handle table.

SGIT_HEAP_SIZE
Returns the total heap size in bytes.

SGIT_LARGEST_FREE_BLOCK
Returns the size (in bytes) of the largest possible block that may be allocated at the moment.

SGIT_TOTAL_COUNT
Returns the total number of clock ticks since the current session of GEOS started (subtracts the initial system clock value from the current time).

SGIT_NUMBER_OF_VOLUMES
Returns the total number of volumes registered with the system.

SGIT_TOTAL_GEODES
Returns the total number of geodes currently loaded.

SGIT_NUMBER_OF_PROCESSES
Returns the total number of processes currently loaded.

SGIT_NUMBER_OF_LIBRARIES
Returns the total number of libraries currently loaded.

SGIT_NUMBER_OF_DRIVERS
Returns the total number of drivers currently loaded.

SGIT_CPU_SPEED
Returns the CPU speed of the processor. The value returned will be ten times the ratio of the CPU speed relative to a base XT processor.

SGIT_SYSTEM_DISK
Returns the disk handle of the disk on which GEOS (the GEOS.INI file) resides.

SGIT_UI_PROCESS

Include: sysstats.h


SysGetPenMode()

Boolean	SysGetPenMode(); This routine returns true if GEOS is running on a pen-based system, false if  it is not.

Include: system.h


SysLocateFileInDosPath()

DiskHandle SysLocateFileInDosPath( /* sets thread's error value */
		const char		* fname,		/* file name */
		char			* buffer);		/* returned path of file */ This routine searches for a specified file along the search path specified in the  DOS environment variable PATH. The parameters are

fname - A pointer to the null-terminated file name to search for.

buffer - A pointer to a locked or fixed buffer into which the full path of the file will be placed.

This routine returns the disk handle of the disk on which the file resides as well as the file’s full path (with drive name) in the buffer pointed to by buffer. The path returned is a null-terminated character string. If the file could not be found, a null disk handle will be returned. The error value can be retrieved with ThreadGetError().

Include: system.h


SysNotify()

word	SysNotify(
		SysNotifyFlags		flags,			/* options to offer user */
		const char 			* string1,		/* first string to display */
		const char 			* string2);		/* second string to display */ This routine causes the kernel to put up a standard notification dialog box on  the screen. This dialog box is white with a black border and is used nearly  exclusively for error notification by the kernel. Pass this routine the following  parameters:

flags - A record of SysNotifyFlags indicating the options the dialog presents to the user. These flags are shown below.

string1 - A pointer to a null-terminated character string put up in the dialog box (may be a null pointer).

string2 - A pointer to a second null-terminated string presented in the dialog box (may be a null pointer).

The returned word is the user’s response, based on the SysNotifyFlags passed (see below).

Structures: SysNotifyFlags is a record of several flags; none, any, or all of the flags may be set at a time. The five flags are

SNF_RETRY
Allow the user to retry the operation that brought up the notification box. If the user selects this option, it will be returned by the routine.

SNF_EXIT
Allow the user to exit GEOS entirely. If the user selects this option, it will be returned by the routine after an SST_CLEAN_FORCED shutdown has been initiated.

SNF_ABORT
Allow the user to abort the operation that brought up the notification box. If the user selects this option, it will be returned by the routine.

SNF_CONTINUE
Allow the user to continue the operation. If the user selects this option, it will be returned by the routine.

SNF_REBOOT
Allow the user to shut down and reboot GEOS directly. If the user selects this option, the routine will not return.

Include: system.h


SysRegisterScreen()

void	SysRegisterScreen(
		GeodeHandle		driver,
		WindowHandle		root);

SysSetECLevel()

void	SysSetECLevel(
		ErrorCheckingFlags	flags,			/* level of error checking */
		MemHandle			checksumBlock);	/* block to check, if any */	 This routine sets the error-checking level of the software. Pass it a record of  **ErrorCheckingFlags** indicating which levels of error checking should be  employed. If checksum checking (ECF_BLOCK_CHECKSUM) is turned on,  also pass the handle of a block on which the checksum will be performed.

Include: ec.h


SysSetExitFlags()

word	SysGetExitFlags(
		ExitFlags		bitsToSet,
		ExitFlags		bitsToClear);

SysShutdown()

Boolean	SysShutdown(
		SysShutdownType		type,
		...);

This routine causes the system to shut down, exiting to the native operating system (typically DOS). It takes variable parameters depending on the first parameter. The first parameter is the type of shutdown requested, and it determines the calling format of the routine. SysShutdown() returns a Boolean value dependent on the type of shutdown.

The parameters and calling format for this routine depend on the value in the type parameter. The possible values (SysShutdownType) are listed below with the associated parameter and return information.

SST_CLEAN
Shut down all applications cleanly, allowing any that wish to to abort the shutdown. The routine will return true if a system shutdown is already in progress at the time of the call. This type of shutdown will send MSG_META_CONFIRM_SHUTDOWN to all objects registered on the MANUFACTURER_ID_GEOWORKS:GCNSLT_SHUTDOWN_CONTROL GCN list (but only if the shutdown is not cancelled). Each object on that list must return an acknowledgment of the shutdown. The parameter format and parameters are

Boolean SysShutdown(
	SysShutdownType		type,
	optr				notificationOD,
	Message				msg);

notificationOD - The optr of an object which will receive the message passed in msg after the shutdown has been acknowledged. Pass a null optr to use the default notification (MSG_META_DETACH sent to the UI).

msg - The message to be sent to the object in notificationOD.

SST_CLEAN_FORCED
Shut down all applications cleanly without the possibility of cancellation. This type takes no additional parameters and does not allow other geodes to abort the shutdown. It will return, but the return value will be meaningless.

SST_DIRTY
Attempt to exit device drivers and close all files without shutting down applications. Does not return. The parameters of this type are

Boolean SysShutdown{
	SysShutdownType		type,		/* SST_DIRTY */
	const char			* reason);

The reason parameter is a pointer to a text string presented to the user as a reason for the dirty shutdown. The string is null-terminated. Pass -1 if no reason is to be given.

SST_PANIC
Exit system device drivers (GA_SYSTEM) without exiting applications or closing files. This can be bad for the system and should be used only in emergency situations. This type of shutdown takes no additional parameters and does not return.

SST_REBOOT
This is used by GEOS when the user hits Ctrl-Alt-Del. Applications should not call it.

SST_RESTART
This is like SST_CLEAN_FORCED above, but it reloads GEOS after shutting down rather than exit completely. It takes no additional parameters; it will return TRUE if the system could not be restarted, FALSE if the shutdown has been initiated.

SST_FINAL
Perform the final phase of a shutdown. This routine is called only by the UI when the SST_CLEAN_FORCED shutdown is complete. This type does not return, and it takes one additional parameter. The calling format and parameters of this type are

Boolean SysShutdown(
	SysShutdownType			type,
	const char				* reason);

The reason parameter is a character string explaining the reason (typically an error) for the final shutdown.

SST_SUSPEND
Suspend system operation in preparation for task switching, and broadcast MSG_META_CONFIRM_SHUTDOWN to all objects on the MANUFACTURER_ID_GEOWORKS:GCNSLT_SHUTDOWN_CONTROL GCN list (see MetaClass). All notified objects must return acknowledgment of the shutdown. This type of SysShutdown() returns true if another system shutdown is already in progress. It takes two additional parameters:

Boolean SysShutdown(
	SysShutdownType		type,
	optr				notificationOD,
	Message				msg);

notificationOD - The optr of an object which will receive the message passed in msg after the shutdown has been acknowledged. Pass a null optr to use the default notification (MSG_META_DETACH sent to the UI), though this is not usually the intent of the call.

msg - The message to be sent to the object in notificationOD.

SST_CONFIRM_START
Called by the recipient of MSG_META_CONFIRM_SHUTDOWN; this allows shutdown confirmation dialog boxes to be presented in order to the user. The caller of this type will be blocked until all previous callers have finished their confirmation procedure. When SysShutdown() returns, the caller may present its confirmation dialog and continue or abort the shutdown. If SysShutdown() returns true from a call with this type, the caller should not present the confirmation dialog to the user and need not call SysShutdown() with SST_CONFIRM_END; another thread has already cancelled the shutdown. This type takes no additional parameters.

SST_CONFIRM_END
The counterpart of SST_CONFIRM_START, this ends the confirmation sequence in an object’s MSG_META_CONFIRM_SHUTDOWN handler. It takes one additional parameter and returns nothing. The calling format is shown below:

void	SysShutdown(
	SysShutdownType		type,
	Boolean				confirm);

The confirm parameter should be TRUE if the shutdown is to be continued, FALSE if the shutdown should be aborted.

Include: system.h

Warnings: Most applications should not call SysShutdown(). Any that do should do so with extreme care.


SysStatistics()

void	SysStatistics(
		SysStats * stats);			/* returned statistics */ This routine returns system performance statistics. Pass it a pointer to an  empty **SysStats** structure; the routine will fill in the appropriate fields.  **SysStats** has the following structure:

typedef struct {
	dword			SS_idleCount;
	SysSwapInfo		SS_swapOuts;
	SysSwapInfo		SS_swapIns;
	word			SS_contextSwitches;
	word			SS_interrupts;
	word			SS_runQueue;
} SysStats;

Include: sysstats.h


SysUnlockBIOS()

void	SysUnlockBIOS(void);

TextSearchInString()

char *	TextSearchInSTring(
		const char		*str1,
		conat char		*startPtr,
		const char		*endPtr,
		word			strSize,
		const char		*str2,
		word			str2Size,
		word			searchOptions,
		word			*matchLen); TextSearchInString() searches in a single text chunk for a passed text string.  If a match is found, a pointer to that match (and the length of the match) are  returned in passed buffers. 

str1 is a pointer to the main string you will be searching in.

startPtr and endPtr are pointers to locations within str1 to begin and end the search.

strSize stores the size of str1, or zero if null-terminated.

str2 stores the match string, which may include wildcards (type WildCard).

str2Size stores the size of str2, or zero if null-terminated.

searchOptions stores the SearchOptions to use by the search mechanism. The high byte should be zeroed.

matchLen stores a buffer to store the size of the matched word. (The matched word itself is returned by the routine.)

Include: Objects/vTextC.goh


TextSearchInHugeArray()

dword	TextSearchInSTring(
		char			*str2,
		word			str2Size,
		dword			str1Size,
		dword			curOffset,
		dword			endOffset,
		FileHandle		hugeArrayFile,
		VMBlockHandle	hugeArrayBlock,
		word			searchOptions,
		word			*matchLen); TextSearchInHugeArray() searches in a huge array for a passed text string.  If a match is found, a dword offset to the match (and the length of the match)  are returned in passed buffers. 

str2 stores the match string, which may include wildcards (type WildCard).

str2Size stores the size of str2, or zero if null-terminated.

str1Size stores the total length of the string being searched.

curOffset stores the offset from the start of str1 to the first character to check.

endOffset stores the offset from the start of str1 to the last character to check.

hugeArrayFile stores the file handle of the huge array.

hugeArrayBlock stores the VM block handle of the huge array.

searchOptions stores the SearchOptions to use by the search mechanism. The high byte should be zeroed.

matchLen stores a buffer to store the size of the matched word. (The matched word itself is returned by the routine.)

Include: Objects/vTextC.goh


TGI_PRIORITY()

byte	TGI_PRIORITY(val);
		word	val; This macro extracts the thread priority from the value returned by  **ThreadGetInfo()**.

TGI_RECENT_CPU_USAGE()

byte	TGI_RECENT_CPU_USAGE(val);
		word	val; This macro extracts the recent CPU usage from the value returned by  **ThreadGetInfo()**.

ThreadAllocSem()

SemaphoreHandle ThreadAllocSem(
		word	value);			/* allowable locks on the semaphore */ This routine allocates and initializes a new semaphore for private use by a  multithreaded application. Pass the value with which to initialize the  semaphore; this value represents the number of threads that can grab the  semaphore before other grab attempts will block. Typically, the passed value  will be one. The routine returns the handle of the new semaphore.

Include: sem.h


ThreadAllocThreadLock()

ThreadLockHandle ThreadAllocThreadLock(); This routine allocates a special semaphore called a thread lock. With a  normal semaphore, a thread that grabs the semaphore twice without  releasing it will deadlock; with a thread lock, a thread can grab it more than  once in succession. The thread has to release it once for each time it grabs the  thread lock, however.

In all other aspects, however, the thread lock resembles a normal semaphore. ThreadAllocThreadLock() returns the handle of the new thread lock.

Include: sem.h


ThreadAttachToQueue()

void	ThreadAttachToQueue(
		QueueHandle		qh,				/* queue to attach */
		ClassStruct		* class);		/* primary class of thread */ This routine attaches the calling thread to the passed event queue. This is  used only for event-driven threads. Typically, this routine is called when a  thread is created; attaching to queues is automatic in nearly all cases, and  you will rarely need this routine.

Pass the handle of the queue in qh and a class pointer in class. The class will be attached to the event queue and will handle all messages sent directly to the thread. This class should nearly always be a subclass of ProcessClass.

If a queue handle of zero is passed, the thread wants to “reattach” to the current queue. This is used typically during shutdown of event-driven threads, and it is nearly always taken care of automatically by ProcessClass.

Include: thread.h


ThreadCreate()

ThreadHandle ThreadCreate(
		word	priority,		/* Initial base priority of new thread */
		word	valueToPass,	/* Optional data to pass to new thread */
		word	(*startRoutine)(word valuePassed),
								/* Pointer to entry routine */
		word	stackSize,		/* Size of the stack for the new thread */
		GeodeHandle owner);		/* Geode that will own the new thread */ This routine creates a new procedural thread for a process. If you need a new  event-driven thread, send MSG_PROCESS_CREATE_EVENT_THREAD to your  process object instead.

Pass the following parameters to this routine:

priority - The priority of the new thread. Typically this will be one of the standard thread priorities (see below).

valueToPass - A word of optional data to be passed to the entry routine of the new thread. This can be used, for example, to indicate the thread’s initial context or for initializing thread variables.

startRoutine - A pointer to the entry routine to be executed immediately for the thread. This may be in either fixed or movable memory. The segment must be a virtual segment. Note that if the routine is in movable memory, it may degrade heap performance for the life of the thread (its movable block will remain locked for extended stretches of time). The routine may return the thread’s exit code or may call ThreadDestroy() directly.

stackSize - The stack size allocated for the thread. 512 bytes is typically enough for threads doing neither UI nor file system work; threads working with the file system will require 1 K. Threads working with UI objects will require 3 K.

owner - The geode handle of the geode that will own the thread. If the calling thread’s geode will own the new thread, it can call GeodeGetProcessHandle() prior to calling ThreadCreate().

ThreadCreate() returns the thread handle of the new thread. If an error occurs, the calling thread’s error code will be set and a null handle returned; you should likely call ThreadGetError() to retrieve the error code after creating the new thread. A return of NO_ERROR_RETURNED from ThreadGetError() means no error occurred.

The standard thread priorities that may be passed in the priority parameter are listed below:

PRIORITY_TIME_CRITICAL
The highest priority of all; you should not use this in general because it will pre-empt nearly all other threads. (It may be useful, however, during debugging.)

PRIORITY_HIGH
A high priority; generally only used for highly important threads.

PRIORITY_UI
Another high priority; this is used for User Interface threads to provide quick response to user actions.

PRIORITY_FOCUS
A medium-level priority; this is used for whatever thread has the current input focus (whichever thread the user is currently working with).

PRIORITY_STANDAR D The standard application thread priority; you should typically use this when creating new threads.

PRIORITY_LOW
A low priority for tasks that can be done in the background.

PRIORITY_LOWEST
The lowest standard priority; it is used for threads that can take any amount of time to complete.

Include: thread.h


ThreadDestroy()

void	ThreadDestroy(
		word	errorCode,	/* Error code to indicate cause of destruction */
		optr	ackObject,	/* Object to receive destruction acknowledgment */
		word	ackData);	/* Additional word of data to pass (as the low
							 * word of optr for source of MSG_META_ACK) */ This routine causes the current (calling) thread to exit and then destroy  itself. The thread is responsible for ensuring that it has no leftover resources  allocated or semaphores locked.

Pass it an error code or exit code meaningful to the application and the other threads in the application. This error code will be used by the debugger to determine the cause of the thread’s exit; a null error code usually indicates successful completion of the thread’s task.

Pass also the optr of the object to receive acknowledgement of the thread’s destruction. The object specified will receive MSG_META_ACK after the calling thread is completely destroyed.

Be Sure To: Always clean up before exiting a thread. Unlock locked resources, free allocated memory, etc. You do not have to do these things for the application’s primary thread; the process object (the primary thread) will automatically clean up after itself.

Include: thread.h


ThreadFreeSem()

void	ThreadFreeSem(
		SemaphoreHandle sem);			/* semaphore to be freed */ This routine frees the specified semaphore that had been allocated with  **ThreadAllocSem()**. You must be sure that no threads are using the  semaphore or will use it after it has been freed. Subsequent access attempts  could cause illegal handle errors or worse.

Include: sem.h


ThreadFreeThreadLock()

void	ThreadFreeThreadLock(
		ThreadLockHandle sem);				/* thread lock to be freed */ This routine frees the specified thread lock that had been allocated with  **ThreadAllocThreadLock()**. You must be sure that no threads are using or  will use the thread lock after it has been freed. Subsequent attempts to grab  or release the thread lock could cause illegal handle errors.

Include: sem.h


ThreadGetError()

word	ThreadGetError(void) This routine returns the thread's current error value.

ThreadGetInfo()

word	ThreadGetInfo(
		ThreadHandle		th,		/* thread to get information about */
		ThreadGetInfoType 	info);	/* type of information to get */ This routine gets information about the specified thread. The information  desired is specified in the *info* parameter; the subject thread is specified in  the *th* parameter. If the thread handle passed is zero or a null handle, the  routine will return information about the calling thread.

The info parameter is one of the following values of ThreadGetInfoType, specifying the type of information to be returned by ThreadGetInfo():

TGIT_PRIORITY_AND_USAGE
The returned word will contain both the thread’s priority and the thread’s recent CPU usage. To extract the priority of the thread, use the macro TGI_PRIORITY; to extract the recent CPU usage, use the macro TGI_RECENT_CPU_USAGE.

TGIT_THREAD_HANDLE
Useful only when the th parameter is zero, this will return the thread handle of the subject thread. If th is zero, the handle of the calling thread will be returned.

TGIT_QUEUE_HANDLE
The returned word will contain the queue handle of the event-driven thread specified in th. If the thread specified is not event-driven, a null queue handle will be returned.

Include: thread.h


ThreadGrabThreadLock()

void	ThreadGrabThreadLock(
		ThreadLockHandle sem);				/* thread lock to grab */ This routine attempts to grab the thread lock for the calling thread. If the  thread lock is currently held by another thread, the caller will block until the  lock becomes available. If the caller already has the thread lock, it will grab  the lock again and continue executing.

Be Sure To: Thread locks must be released with ThreadReleaseThreadLock() once for each time they are grabbed.

Warnings: This routine provides no deadlock protection for multiple threads. If multiple threads will be grabbing multiple thread locks, the locks should always be grabbed in the same order to minimize the potential for deadlock.

Include: sem.h


ThreadHandleException()

void	ThreadHandleException(
		ThreadHandle		th,			/* thread to handle the exception */
		ThreadExceptions	exception,	/* exception to handle */
		void	(*handler)	());		/* pointer to handler */ This routine allows a thread to set up a handler for a processor exception.  This can be useful for debugging purposes. Pass the following three  parameters:

th - The handle of the thread to handle the exception. Pass zero for the current thread.

exception - A ThreadException type (see below).

handler - A pointer to a handler in fixed or locked memory. Pass a null pointer to use the GEOS default exception handler.

Structures: The ThreadException type has the following values:

TE_DIVIDE_BY_ZERO
TE_OVERFLOW
TE_BOUND
TE_FPU_EXCEPTION
TE_SINGLE_STEP
TE_BREAKPOINT

Include: thread.h


ThreadModify()

void	ThreadModify(
		ThreadHandle		th,					/* thread to modify */
		word				newBasePriority,	/* thread's new base priority */
		ThreadModifyFlags	flags);				/* flags (see below) */ This routine modifies the priority of the specified thread. Use it to either set  the base priority of the thread or reset the current CPU usage to zero. The  parameters should have the following values:

th - The thread handle; pass zero to change the priority of the calling thread.

newBasePriority - The new base priority of the thread. Use one of the standard priorities - see ThreadCreate() - or use a value between zero and 255.

flags A record of ThreadModifyFlags; pass TMF_BASE_PRIO to change the thread’s base priority or TMF_ZERO_USAGE to reset the thread’s recent CPU usage to zero.

Warnings: Unless the thread is timing-critical, you should not set the base priority to zero.

Include: thread.h


ThreadPrivAlloc()

word	ThreadPrivAlloc(
		word			wordsRequested,		/* number of words to allocate */
		GeodeHandle		owner);				/* handle of geode to own data */ This routine allocates a number of contiguous words in the private data of all  geodes (loaded and yet-to-be loaded). It is exactly the same as  **GeodePrivAlloc()**; see the entry for that routine.

Include: thread.h

See Also: GeodePrivAlloc()


ThreadPrivFree()

void	ThreadPrivFree(
		word	range,				/* offset to first word to be freed */
		word	wordsRequested);	/* number of words to free */ This routine frees a number of contiguous private-data words previously  allocated with **ThreadPrivAlloc()**. It is similar to **GeodePrivFree()**; see  the entry for that routine for full information.

Include: thread.h

See Also: GeodePrivFree()


ThreadPSem()

SemaphoreError ThreadPSem(
		SemaphoreHandle sem);				/* semaphore to grab */ This routine attempts to grab the passed semaphore via a "P" operation. If  the semaphore has already been grabbed, the thread will block until the  semaphore becomes available, even if it was grabbed by the same thread.

ThreadPSem() returns an error code of type SemaphoreError, described in ThreadPTimedSem(), below. The error code is intended to indicate abnormal return by the previous thread; if the semaphore never becomes available, the thread will block indefinitely and the routine will not return.

Be Sure To: When the thread no longer needs the semaphore, it should release it with ThreadVSem().

Warnings: This routine provides no deadlock protection. If threads will grab multiple common semaphores, they should always grab/release them in the same order, minimizing the chances for deadlock.

A thread may not try to grab a particular semaphore twice without releasing it in between grabs. The thread will block on itself and will deadlock. If a thread may need to grab the semaphore twice in a row, it should use a thread lock instead (see ThreadAllocThreadLock() for more information).

Include: sem.h


ThreadPTimedSem()

SemaphoreError ThreadPTimedSem(
		SemaphoreHandle		sem,		/* semaphore to grab */
		word				timeout);	/* ticks before timeout */ This routine attempts to grab the passed semaphore via a "P" operation. If  the semaphore has already been grabbed, the thread will block for at most  the number of ticks specified in *timeout*.

ThreadPTimedSem() returns an error code of type SemaphoreError, which has three values:

SE_NO_ERROR
No error occurred and the semaphore was grabbed properly.

SE_TIMEOUT
The time elapsed and the semaphore was not grabbed. If this value is returned, the thread should not proceed with whatever protected operation was to happen. Instead, it should either attempt to grab the semaphore again or should proceed with other tasks.

SE_PREVIOUS_OWNER_DIED
The previous owner of the semaphore exited abnormally. If the thread currently holding the semaphore exited without releasing the semaphore, for example, this would be returned.

Often timeout is passed as zero to indicate that if the semaphore isn’t available right now, the thread will go on with some other action.

Be Sure To: When the thread no longer needs the semaphore, it should release it with ThreadVSem().

Warnings: This routine provides no deadlock protection. If threads will grab multiple common semaphores, they should always grab/release them in the same order, minimizing the chances for deadlock.

A thread may not try to grab a particular semaphore twice without releasing it in between grabs. The thread will block on itself and will deadlock. If a thread may need to grab the semaphore twice in a row, it should use a thread lock instead, though there is no timeout equivalent for thread locks (see ThreadAllocThreadLock() for more information).

Include: sem.h


ThreadReleaseThreadLock()

void	ThreadReleaseThreadLock(
		ThreadLockHandle sem);				/* threadlock to release */ This routine releases the specified thread lock previously grabbed with  **ThreadGrabThreadLock()**. Pass the handle of the thread lock as returned  by **ThreadAllocThreadLock()**.

Do not try to release a thread lock that has not previously been grabbed. The results are unpredictable.

Include: sem.h


ThreadVSem()

void	ThreadVSem(
		SemaphoreHandle sem);				/* semaphore to release */ This routine releases a semaphore that was grabbed with ThreadPSem() or  **ThreadPTimedSem()**. Pass the handle of the semaphore as returned by  **ThreadAllocSem()**.

Do not try to release a semaphore that has not previously been grabbed with one of the above routines. The results are unpredictable.

Include: sem.h


TimerGetCount()

dword	TimerGetCount(); This routine returns the value of the system counter. The returned value is  the number of ticks since GEOS started.

Include: timer.h


TimerGetDateAndTime()

void	TimerGetDateAndTime(
		TimerDateAndTime * dateAndTime);	/* buffer for returned values */ This routine returns the current time and date. Pass it a pointer to an empty  **TimerDateAndTime** structure to be filled in by the routine.

Include: timedate.h


TimerSetDateAndTime()

void	TimerSetDateAndTime(
		word					flags,			/* which item to set */
		const TimerDateAndTime	* dateAndTime);	/* new values */ This routine sets the current date and/or time of the system. Pass it the  following:

flags - A word of flags. Pass TIME_SET_DATE to set the day, month, and year; pass TIME_SET_TIME to set the hour, minute, and second. Pass both to set both.

dateAndTime - A pointer to a TimerDateAndTime structure containing the information to be set.

Include: timedate.h


TimerSleep()

void	TimerSleep(
		word	ticks);		/* number of ticks the thread should sleep */ This routine invokes a "sleep timer" that will put the calling thread to sleep  for the given number of ticks. At the end of the time, the thread will continue  executing with the next instruction.

Warnings: Do not use sleep timers as a substitute for semaphores for thread synchronization.

Include: timer.h


TimerStart()

TimerHandle TimerStart(
		TimerType	timerType,		/* type of timer to start */
		optr		destObject,		/* object to receive notification
									 * message when timer expires */
		word		ticks,			/* amount of time to run */
		Message		msg,			/* notification message */
		word		interval,		/* interval for continual timers */
		word		* id);			/* buffer for returned timer ID */ This routine starts a timer of any type. The timer will run for the specified  number of ticks and then will send the given message to the destination  object. The message is sent with the flags MF_FORCE_QUEUE,  MF_CHECK_DUPLICATE and MF_REPLACE, so it will always be put in the  recipient's queue and will always replace any duplicates already in the  queue. Pass this routine the following:

timerType - A value of TimerType indicating the type of timer to start.

destObject - The optr of the object that will be sent the specified message when the time is up.

ticks - The number of ticks for the timer to run. (Sixty ticks equals one second.)

msg - The message to be sent to the destination object when time is up.

interval - For continual timers, the interval (number of ticks) at which to send out the message to the destination object. The timer will send the message once at the end of each interval. The first message will be sent ticks ticks after the timer is started. The second message will be sent interval ticks after that.

id - A pointer to a word in which the timer’s ID will be returned. You will need this ID for TimerStop().

This routine returns the handle of the timer as well as an ID pointed to by the id parameter. You will need the handle and the ID for TimerStop().

TimerType: The TimerType enumerated type defines what type of timer should be initiated. It has the following values:

TIMER_ROUTINE_ONE_SHOT
Start a timer that will call a routine and then free itself when the time is expired. This type is supported in assembly but not in C.

TIMER_ROUTINE_CONTINUAL
Start a timer that will call a routine once per time interval until TimerStop() is called. This type is supported in assembly but not in C.

TIMER_EVENT_ONE_SHOT
Start a timer that will send a message to a given object, then free itself, when time is expired.

TIMER_EVENT_CONTINUAL
Start a timer that will send a message to a given object once per time interval until TimerStop() is called.

TIMER_MS_ROUTINE_ONE_SHOT
Start a timer that has millisecond accuracy. For this timer, the number of ticks will actually be the number of milliseconds. The timer will call a specified routine and then free itself when time is expired. This type is supported in assembly but not in C.

TIMER_EVENT_REAL_TIME
Start a timer that will call a routine at some particular date and time. On devices that support such a timer, this event will wake a sleeping machine.

Include: timer.h


TimerStop()

Boolean	TimerStop(
		TimerHandle		th,		/* handle of timer to be stopped */
		word			id);	/* timer ID (returned by TimerStart() */ This routine stops a timer that had been started with **TimerStart()**. Pass it  the timer handle and the ID as returned by that routine (the ID of a continual  timer will always be zero).

The returned error flag will be true if the timer could not be found.

Warnings: If you call TimerStop() to stop a continual timer that sends its message across threads, there may be timer events left in the recipient’s event queue. It is unsafe in this situation to assume that all timer events have been handled. To ensure the timer message has been handled, you can send the destination an “all-safe” message with the MF_FORCE_QUEUE flag.

Include: timer.h


TocDBLock()

void * TocDBLock(
		DBGroupAndItem 		thing); Use this routine to lock a name array maintained by a PrefTocList object.

Include: config.goh


TocDBLockGetRef()

void * TocDBLockGetRef(
		DBGroupAndItem 		thing,
		optr				*refPtr); This routine locks a name array maintained by a PrefTocList object,  returning the item's pointer and optr.

Include: config.goh


TocFindCategory()

Boolean TocFindCategory(
		TocCategoryStruct 		*cat); This routine searches a PrefTocList object's name list for a given token.

Structures:

typedef struct {
	TokenChars 		TCS_tokenChars;
	DBGroupAndItem 	TCS_files; 			/* file name array */
	DBGroupAndItem 	TCS_devices; 		/* device name array--only if
										 * TCF_EXTENDED_DEVICE_DRIVERS
										 * is set. */
} TocCategoryStruct;

Include: config.goh


TocGetFileHandle()

word TocGetFileHandle(); Use this routine to get the handle of the file used by PrefTocLists to store  their name array data.

Include: config.goh


TocNameArrayAdd()

word TocNameArrayAdd(
		DBGroupAndItem 		array, 
		const char 			*nameToFind,
		const void 			*data); Use this routine to add a name to a name array maintained by a PrefTocList  object.

Include: config.h


TocNameArrayFind()

word TocNameArrayGetElement(
		DBGroupAndItem 		array, 
		word 				element,
		void 				*buffer); Use this routine to find a name in the name list maintained by a PrefTocList  object.

Include: config.goh


TocNameArrayGetElement()

word TocNameArrayGetElement(
		DBGroupAndItem 		array, 
		word 		element,
		void 		*buffer); Use this routine to retrieve a given element from a name array maintained  by a PrefTocList object. 

Include: config.goh


TocSortedNameArrayAdd()

word TocSortedNameArrayAdd(
		word 				arr, 
		const char 			*nameToAdd,
		NameArrayAddFlags 	flags,
		const void 			*data); This routine adds a name to a sorted name array associated with a  PrefTocList object. 

Structures:

typedef WordFlags NameArrayAddFlags;
#define NAAF_SET_DATA_ON_REPLACE 0x8000

Include: config.goh


TocSortedNameArrayFind()

Boolean TocSortedNameArrayFind(
		word 						arr, 
		const char 					*nameToFind,
		SortedNameArrayFindFlags 	flags,
		void 						*buffer, 
		word 						*elementNum); This routine looks up a name in a sorted name array associated with a  PrefTocList object.

Structures:

typedef WordFlags SortedNameArrayFindFlags;
#define SNAFF_IGNORE_CASE 0x0080

Include: config.goh


TocUpdateCategory()

void TocUpdateCategory(
		TocUpdateCategoryParams *params); Use this routine to update a PrefTocList object based upon the files in a given  directory with a given token.

Structures:

typedef struct {
	TocUpdateCategoryFlags 	TUCP_flags;
	TokenChars 				TUCP_tokenChars;
	byte 					TUCP_fileArrayElementSize;
	TocUpdateAddCallback 	*TUCP_addCallback;
	byte 					TUCP_pad; /* Wants to be word-aligned */
} TocUpdateCategoryParams;

typedef word _pascal TocUpdateAddCallback(
	const char *filename,
	optr chunkArray);
/* Return 0 if add aborted, else return offset of new element within
 * block */

Include: config.goh


TOKEN_CHARS()

dword	TOKEN_CHARS(a, b, c, d);
		char	a, b, c, d; This macro creates a single dword value from four given characters. This is  useful when creating a token characters value for a specific token.

TokenDefineToken()

word	TokenDefineToken(
		dword			tokenChars,			/* four token characters */
		ManufacturerID	manufacturerID,		/* manufacturer ID for token */
		optr			monikerList,		/* optr of moniker list */
		TokenFlags		flags);				/* token flags */ This routine adds a new token and moniker list to the token database. If the  token already exists in the token DB, the old will be replaced with the new.  This routine must only be called by a thread that can lock the block in which  the passed moniker or moniker list resides. This routine must be passed the  following parameters:

tokenChars - The four token characters that identify this moniker or moniker list in the token database. Create this dword value from the four characters with the macro TOKEN_CHARS.

manufacturerID - The manufacturer ID number of the manufacturer responsible for the token database entry.

monikerList - The optr of the moniker list to be added to the token database.

flags - A record of TokenFlags indicating the relocation status of the moniker list.

Warnings: This routine may legally move locked LMem blocks (token database items), thereby invalidating all pointers to token database items.

Include: token.h


TokenGetTokenInfo()

Boolean	TokenGetTokenInfo(
		dword			tokenChars,			/* four characters of token */
		ManufacturerID	manufacturerID,		/* manufacturer ID of token */
		TokenFlags		* flags);			/* returned token flags */ This routine returns information about a specified token. Pass it the  following:

tokenChars - The four token characters that identify the token database entry. Create this dword from the four characters with the macro TOKEN_CHARS.

manufacturerID - The manufacturer ID number of the manufacturer responsible for the token database entry.

flags - A pointer to an empty flags record; the flags set (if any) for the specified token (if it exists) will be returned here.

This routine returns a (non-zero) value of VMStatus if the token was not found in the token database. It returns zero if successful.

Include: token.h


TokenListTokens()

dword	TokenListTokens(
		TokenRangeFlags 	tokenRangeFlags,
		word 				headerSize,
		ManufacturerID 		manufacturerID)); This routine lists all the tokens in the token database. It allocates a new  block on the global heap and writes in it an array of **GeodeToken** structures.  This routine returns the actual tokens, not the token groups.

The returned dword consists of two values: The high word represents the number of tokens in the returned block and may be extracted with the macro TokenListTokensCountFromDWord(). The low word represents the handle of the newly-allocated block and can be extracted with the macro TokenListTokensHandleFromDWord().

Include: token.h


TokenListTokensCountFromDWord()

word	TokenListTokensCountFromDWord(d);
		dword	d; This macro extracts the number of tokens from the value returned by  **TokenListTokens()**.

TokenListTokensHandleFromDWord()

word	TokenListTokensHandleFromDWord(d);
		dword	d; This routine extracts the MemHandle from the value returned by  **TokenListTokens()**.

TokenLoadMonikerBlock()

Boolean	TokenLoadMonikerBlock(
		dword					tokenChars,		/* four characters of token */
		ManufacturerID			manufacturerID,	/* manufacturer ID of token */
		DisplayType				displayType,	/* type of display for token */
		VisMonikerSearchFlags	searchFlags,	/* flags for finding token */
		word					* blockSize,	/* returned block size */
		MemHandle				* blockHandle);	/* returned block handle */ This routine loads a specified token's moniker, allocating a new global  memory block for the moniker. The returned Boolean will be *true* if the  moniker was found, *false* otherwise. Information about the moniker is  returned in the values pointed to by *blockSize* (the size of the newly allocated  block) and *blockHandle* (the handle of the new block). If the moniker is not  found, both return pointers will be NULL and no block will be allocated.

Pass this routine the following:

tokenChars - The four token characters that identify the token database entry. Create this dword from the four characters with the macro TOKEN_CHARS.

manufacturerID - The manufacturer ID number of the manufacturer responsible for the token database entry.

displayType - A value of DisplayType indicating the size of the display (used to indicate small-screen devices, primarily).

searchFlags - A record of VisMonikerSearchFlags indicating what type of moniker is being requested.

blockSize - A pointer to a word in which the new block’s size will be returned.

blockHandle - A pointer to a handle in which the new block’s handle will be returned.

Include: token.h


TokenLoadMonikerBuffer()

Boolean	TokenLoadMonikerBuffer(
		dword					tokenChars,			/* four characters of token */
		ManufacturerID			manufacturerID,		/* manufacturer ID of token */
		DisplayType				displayType,		/* type of display for token */
		VisMonikerSearchFlags	searchFlags,		/* flags for finding token */
		void					* buffer,			/* pointer to buffer for token */
		word					bufSize,			/* size of passed buffer */
		word					* bytesReturned);	/* number of bytes returned */ This routine loads a specified token's moniker into a provided buffer. The  returned Boolean will be *true* if the moniker was found, *false* otherwise. The size  of the returned moniker will be returned in the word pointed to by the  *bytesReturned* parameter.

Pass this routine the following:

tokenChars - The four token characters that identify the token database entry. Create this dword from the four characters with the macro TOKEN_CHARS.

manufacturerID - The manufacturer ID number of the manufacturer responsible for the token database entry.

displayType - A value of DisplayType indicating the size of the display (used to indicate small-screen devices, primarily).

searchFlags - A record of VisMonikerSearchFlags indicating what type of moniker is being requested.

buffer - A pointer to a locked or fixed buffer into which the moniker will be copied.

bufSize - The size of the passed buffer; also the maximum size of the moniker that may be returned.

bytesReturned - The size of the moniker actually returned in the buffer.

Include: token.h


TokenLoadMonikerChunk()

Boolean	TokenLoadMonikerChunk(
		dword					tokenChars,		/* four characters of token */
		ManufacturerID			manufacturerID,	/* manufacturer ID of token */
		DisplayType				displayType,	/* type of display for token */
		VisMonikerSearchFlags	searchFlags,	/* flags for finding token */
		MemHandle				lmemBlock,		/* locked block for new chunk */
		word					* chunkSize,	/* returned new chunk size */
		ChunkHandle				* chunkHandle);	/* returned new chunk handle */ This routine loads a specified token's moniker, allocating a new chunk in a  local memory block for the moniker. The returned Boolean will be *true* if the  moniker was found, *false* otherwise.

Pass this routine the following:

tokenChars - The four token characters that identify the token database entry. Create this dword from the four characters with the macro TOKEN_CHARS.

manufacturerID - The manufacturer ID number of the manufacturer responsible for the token database entry.

displayType - A value of DisplayType indicating the size of the display (used to indicate small-screen devices, primarily).

searchFlags - A record of VisMonikerSearchFlags indicating what type of moniker is being requested.

lmemBlock - The MemHandle of the local memory block in which the new chunk will be allocated. If the block is locked, you must dereference the global handle after calling this routine.

chunkSize - A pointer to a word in which the size of the allocated chunk will be returned.

chunkhandle - A pointer to a chunk handle in which the handle of the newly allocated chunk will be returned.

Warnings: This routine can move chunks in the passed block, thereby invalidating pointers to any chunk in the block.

Include: token.h


TokenLoadTokenBlock()

Boolean	TokenLoadTokenBlock(
		dword			tokenChars,			/* four characters of token */
		ManufacturerID	manufacturerID,		/* manufacturer ID of token */
		word			* blockSize,		/* returned size of new block */
		MemHandle		* blockHandle);		/* returned handle of block */ This routine loads the specified token's **TokenEntry** structure into a  newly-allocated global memory block. The returned Boolean will be *true* if the  token was found, *false* otherwise.

Pass this routine the following:

tokenChars - The four token characters that identify the token database entry. Create this dword from the four characters with the macro TOKEN_CHARS.

manufacturerID - The manufacturer ID number of the manufacturer responsible for the token database entry.

blockSize - A pointer to a word in which the size of the newly-allocated block will be returned.

blockHandle - A pointer to a global handle in which the handle of the newly-allocated block will be returned.

Include: token.h


TokenLoadTokenBuffer()

Boolean	TokenLoadTokenBuffer(
		dword			tokenChars,			/* four characters of token */
		ManufacturerID	manufacturerID,		/* manufacturer ID of token */
		TokenEntry		* buffer);			/* buffer for returned token */ This routine loads the specified token's **TokenEntry** structure into a passed  buffer. The returned Boolean will be *true* if the token was found, *false*  otherwise. Pass this routine the following:

tokenChars - The four token characters that identify the token database entry. Create this dword from the four characters with the macro TOKEN_CHARS.

manufacturerID - The manufacturer ID number of the manufacturer responsible for the token database entry.

buffer - A pointer to a locked or fixed buffer into which the token entry will be copied.

Include: token.h


TokenLoadTokenChunk()

Boolean	TokenLoadTokenChunk(
		dword			tokenChars,			/* four characters of token */
		ManufacturerID	manufacturerID,		/* manufacturer ID of token */
		MemHandle		lmemBlock,			/* handle of block for chunk */
		word			* chunkSize,		/* returned size of new chunk */
		ChunkHandle		* chunkHandle);		/* returned chunk handle */ This routine loads the specified token's **TokenEntry** structure into a  newly-allocated chunk. The returned Boolean will be *true* if the token was found,  *false* otherwise.

Pass this routine the following:

tokenChars - The four token characters that identify the token database entry. Create this dword from the four characters with the macro TOKEN_CHARS.

manufacturerID - The manufacturer ID number of the manufacturer responsible for the token database entry.

lmemBlock - The MemHandle of the local memory block in which the new chunk will be allocated. If the block is locked, you must manually dereference this handle after the routine call.

chunksize - A pointer to a word in which the size of the newly-allocated chunk will be returned.

chunkHandle - A pointer to a chunk handle in which the handle of the newly-allocated chunk will be returned.

Warnings: This routine can move chunks in the passed block, thereby invalidating pointers to any chunk in the block.

Include: token.h


TokenLockTokenMoniker()

void	* TokenLockTokenMoniker(
		TokenMonikerInfo	tokenMonikerInfo);	/* The DB group and item numbers
							 * as returned by TokenLookupMoniker() */ This routine locks a token's moniker so it may be drawn; it returns a pointer  to the locked chunk containing the moniker information. Pass it the  structure returned by **TokenLookupMoniker()**.

Be Sure To: Unlock the moniker with TokenUnlockMoniker() after you have finished drawing it.

Include: token.h


TokenLookupMoniker()

Boolean	TokenLookupMoniker(
		dword					tokenChars,			/* four characters of token */
		ManufacturerID			manufacturerID,		/* manufacturer ID of token */
		DisplayType				displayType,		/* display type of token */
		VisMonikerSearchFlags	searchFlags,		/* flags for finding token */
		TokenMonikerInfo *		tokenMonikerInfo);	/* DB group and item of token */ This routine finds and retrieves a pointer to the specific moniker for the  specified token, given also the token's display type and other attributes. Pass  the following:

tokenChars - The four token characters that identify this moniker or moniker list in the token database. Create this dword value from the four characters with the macro TOKEN_CHARS.

manufacturerID - The manufacturer ID number of the manufacturer responsible for the token database entry.

displayType - A value of DisplayType indicating the size of the display (used to indicate small-screen devices, primarily).

searchFlags - A record of VisMonikerSearchFlags indicating what type of moniker is being requested.

tokenDBItem A pointer to an empty TokenMonikerInfo structure, in which the token’s group and item numbers will be returned.

The return value is an error flag: it will be true if the item could not be found in the token database, false otherwise.

Include: token.h


TokenCloseLocalTokenDB()

void	TokenCloseLocalTokenDB() This routine closes the local token database.

TokenListTokens()

dword TokenListTokens(
		TokenRangeFlags		tokenRangeFlags,
		word				headerSize,
		ManufacturerID		manufacturerID) This routine locates all the tokens that meet specified criteria, allocates a  block, and copies the tokens to that block. The upper word of the return value  is the number of matching tokens found; the lower word is the handle of the  block which was allocated.

TokenOpenLocalTokenDB()

word	TokenOpenLocalTokenDB() This routine opens the local token database. It returns zero on success, and  a **VMStatus** error code on failure.

Include: token.h


TokenRemoveToken

Boolean	TokenRemoveToken(
		dword			tokenChars,			/* four characters of token */
		ManufacturerID	manufacturerID,		/* manufacturer ID of token */ This routine removes the specified token and its moniker list from the token  database. It returns an error flag: if the token could not be found, the  returned flag is *true*; otherwise it is *false*. Pass the following:

tokenChars - The four token characters that identify this moniker or moniker list in the token database. Create this dword value from the four characters with the macro TOKEN_CHARS.

manufacturerID - The manufacturer ID number of the manufacturer responsible for the token database entry.

Include: token.h


TokenUnlockTokenMoniker()

void	TokenUnlockTokenMoniker(
		void * moniker); This routine unlocks a moniker that had been locked with  **TokenLockMoniker()**. Pass a pointer to the locked moniker, as returned by  the locking routine.

Include: token.h


TypeFromFormatID()

word	TypeFromFormatID(id);
		ClipboardItemFormatID	id; This macro extracts the word-sized format ID (of type  **ClipboardItemFormat**) from a **ClipboardFormatID** argument.

Routines M-P <– Table of Contents    –> Routines U-Z