Applications and Geodes: 2.2 Creating Icons: Managing the Token Database File

GEOS SDK TechDocs

2.1 The Token Database

3 Saving User Options

TokenDefineToken(), TokenGetTokenInfo(), TokenLookupMoniker(), TokenLoadMonikerBlock(), TokenLoadMonikerChunk(), TokenLoadMonikerBuffer(), TokenRemoveToken(), TokenLoadTokenBlock(), TokenLoadTokenChunk(), TokenLoadTokenBuffer(), TokenLockTokenMoniker(), TokenUnlockTokenMoniker(), TokenGetTokenStats(), TokenListTokens()

In nearly all cases, you will create your application's icon with the icon tool and not worry about it again. However, the following routines allow you to add, change, access, and remove entries from the token database.

TokenLoadTokenBlock() , TokenLoadTokenChunk() , and TokenLoadTokenBuffer() load a TokenEntry structure into memory (a newly allocated block, a newly allocated chunk, or a locked buffer). The TokenEntry structure contains information about the token, the geode's release number, and the geode's protocol number. This structure does not actually contain the monikers used for the icon.

TokenLookupMoniker() gets the specific moniker of a token entry given the display type (CGA, EGA, VGA, etc.), the entry's GeodeToken structure, and search flags. If the moniker is found, the entry identifier (database group and ID numbers) of the moniker are returned. You can use these return values to lock the moniker into memory (see below).

TokenLockTokenMoniker() locks a moniker into memory given its entry identifier. This routine returns a pointer to a locked block and the chunk handle of the chunk containing the locked moniker. A moniker should always be locked before it is drawn; this keeps it from moving in memory while it is being accessed. The routine TokenUnlockTokenMoniker() unlocks a previously locked moniker when given the moniker's segment address. This unlocks the entire block, not just the individual moniker.

TokenLoadMonikerBlock() , TokenLoadMonikerChunk() , and TokenLoadMonikerBuffer() load a specific moniker into memory from the token database file (into a newly allocated block, a newly allocated chunk, or a locked buffer). It takes the same parameters as TokenLookupMoniker() but returns the handle and chunk handle of the loaded moniker. If using this routine, simply lock the memory block rather than using TokenLockTokenMoniker() .

TokenGetTokenInfo() finds a token when passed its tokenchars and tokenid and returns the token's flags. If no token exists with the passed characteristics, it will return an error flag.

TokenDefineToken() adds a new token and its moniker list to the token database. If the given token already exists, the new one will replace the old one. The token identifier ( tokenchars , tokenid ), handle and chunk handle of the moniker list, and flags of the new token must be passed.

TokenRemoveToken() removes a given token and its moniker list from the token database file. It returns only a flag indicating whether the token was successfully removed or not.

TokenListTokens() returns a list of the tokens in the token database. It is passed three arguments:

• A set of TokenRangeFlags , which specifies which tokens should be returned. The following flags are available:

TRF_ONLY_GSTRING

Return only those tokens which are defined with a GString.

TRF_ONLY_PASSED_MANUFID

Return only those tokens which match the passed manufacturer's ID.

• A number of bytes to reserve for a header.
• A manufacturer ID. This field is ignored if TRF_ONLY_PASSED_MANUFID was not passed.

TokenListTokens() allocates a global memory block and copies all the specified tokens into that block. It leaves a blank space at the beginning of the block; this space is the size specified by the second argument. The rest of the block is an array of GeodeToken structures. TokenListTokens() returns a dword. The lower word of the return value is the handle of the global memory block; the upper word is the number of GeodeToken structures in that block.

GEOS SDK TechDocs

2.1 The Token Database

3 Saving User Options