From 3d83ba0f319b641e9392c2bc4668278b276f7291 Mon Sep 17 00:00:00 2001 From: RainerB Date: Fri, 24 May 2024 14:54:20 +0200 Subject: [PATCH] TokenLoadToken routines updated. Documentation fixed. --- CInclude/token.h | 12 +- Library/User/Token/tokenC.asm | 8 + TechDocs/Markdown/Routines/rroutq_t.md | 10 +- TechDocs/ascii/Routines/rroutq-t.txt | 20 +- TechDocs/html/CRef/Routines/R_9c.htm | 11 +- TechDocs/html/CRef/Routines/R_9d.htm | 480 ++++++++++++------------- 6 files changed, 274 insertions(+), 267 deletions(-) diff --git a/CInclude/token.h b/CInclude/token.h index c50903e6b..8259ddded 100644 --- a/CInclude/token.h +++ b/CInclude/token.h @@ -85,7 +85,7 @@ extern Boolean /*XXX*/ VisMonikerSearchFlags searchFlags, TokenMonikerInfo *tokenMonikerInfo); -extern Boolean /*XXX*/ +extern Boolean _pascal TokenLoadMonikerBlock(dword tokenChars, ManufacturerID manufacturerID, DisplayType displayType, @@ -93,7 +93,7 @@ extern Boolean /*XXX*/ word *blockSize, MemHandle *blockHandle); -extern Boolean /*XXX*/ +extern Boolean _pascal TokenLoadMonikerChunk(dword tokenChars, ManufacturerID manufacturerID, DisplayType displayType, @@ -102,7 +102,7 @@ extern Boolean /*XXX*/ word *chunkSize, ChunkHandle *chunkHandle); -extern Boolean /*XXX*/ +extern Boolean _pascal TokenLoadMonikerBuffer(dword tokenChars, ManufacturerID manufacturerID, DisplayType displayType, @@ -117,20 +117,20 @@ extern Boolean /*XXX*/ extern void /*XXX*/ _pascal TokenGetTokenStats(dword tokenChars, ManufacturerID manufacturerID); -extern Boolean /*XXX*/ +extern Boolean _pascal TokenLoadTokenBlock(dword tokenChars, ManufacturerID manufacturerID, word *blockSize, MemHandle *blockHandle); -extern Boolean /*XXX*/ +extern Boolean _pascal TokenLoadTokenChunk(dword tokenChars, ManufacturerID manufacturerID, MemHandle lmemBlock, word *chunkSize, ChunkHandle *chunkHandle); -extern Boolean /*XXX*/ +extern Boolean _pascal TokenLoadTokenBuffer(dword tokenChars, ManufacturerID manufacturerID, TokenEntry *buffer); diff --git a/Library/User/Token/tokenC.asm b/Library/User/Token/tokenC.asm index 8e2273a46..35b3e8544 100644 --- a/Library/User/Token/tokenC.asm +++ b/Library/User/Token/tokenC.asm @@ -413,6 +413,10 @@ TOKENLOADTOKENBLOCK proc far tokenChars:dword, clr cx ; allocate global heap block call TokenLoadToken ; cx = #bytes, di = block ; carry clear if found + jnc foundit + mov cx, 0 ; return zero block and #bytes + mov di, 0 ; preserve carry +foundit: les si, blockSize mov es:[si], cx ; return #bytes les si, blockHandle @@ -457,6 +461,10 @@ TOKENLOADTOKENCHUNK proc far tokenChars:dword, clr di ; cx = lmemBlock call TokenLoadToken ; cx = #bytes, di = lmem chunk ; carry clear if found + jnc foundit + mov cx, 0 ; return zero chunk handle and #bytes + mov di, 0 ; preserve carry +foundit: les si, chunkSize mov es:[si], cx ; return #bytes les si, chunkHandle diff --git a/TechDocs/Markdown/Routines/rroutq_t.md b/TechDocs/Markdown/Routines/rroutq_t.md index 4cf5ca372..61f7c4572 100644 --- a/TechDocs/Markdown/Routines/rroutq_t.md +++ b/TechDocs/Markdown/Routines/rroutq_t.md @@ -2401,8 +2401,8 @@ pointers to any chunk in the block. 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. If the token is not found, the returned -error flag will be *true*; otherwise, it will be *false*. +newly-allocated global memory block. The returned Boolean will be *true* if the +token was found, *false* otherwise. Pass this routine the following: @@ -2428,7 +2428,7 @@ newly-allocated block will be returned. 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 error flag will be *true* if the token was not found, *false* +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 @@ -2452,8 +2452,8 @@ will be copied. 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 error flag will be *true* if the token could -not be found, *false* otherwise. +newly-allocated chunk. The returned Boolean will be *true* if the token was found, +*false* otherwise. Pass this routine the following: diff --git a/TechDocs/ascii/Routines/rroutq-t.txt b/TechDocs/ascii/Routines/rroutq-t.txt index 8a507e224..998d55e2e 100644 --- a/TechDocs/ascii/Routines/rroutq-t.txt +++ b/TechDocs/ascii/Routines/rroutq-t.txt @@ -2963,8 +2963,8 @@ Boolean TokenLoadMonikerBlock( 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 false if the -moniker was found, true otherwise. Information about the moniker is +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. @@ -3015,7 +3015,7 @@ Boolean TokenLoadMonikerBuffer( word * bytesReturned); /* number of bytes returned */ This routine loads a specified token's moniker into a provided buffer. The -return value will be false if the moniker was found, true otherwise. The size +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. @@ -3067,8 +3067,8 @@ Boolean TokenLoadMonikerChunk( 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 error flag will be true if the -moniker was not found, false otherwise. +local memory block for the moniker. The returned Boolean will be true if the +moniker was found, false otherwise. Pass this routine the following: @@ -3117,8 +3117,8 @@ Boolean TokenLoadTokenBlock( MemHandle * blockHandle); /* returned handle of block */ This routine loads the specified token's TokenEntry structure into a -newly-allocated global memory block. If the token is not found, the returned -error flag will be true; otherwise, it will be false. +newly-allocated global memory block. The returned Boolean will be true if the +token was found, false otherwise. Pass this routine the following: @@ -3150,7 +3150,7 @@ Boolean TokenLoadTokenBuffer( TokenEntry * buffer); /* buffer for returned token */ This routine loads the specified token's TokenEntry structure into a passed -buffer. The returned error flag will be true if the token was not found, false +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 @@ -3181,8 +3181,8 @@ Boolean TokenLoadTokenChunk( ChunkHandle * chunkHandle); /* returned chunk handle */ This routine loads the specified token's TokenEntry structure into a -newly-allocated chunk. The returned error flag will be true if the token could -not be found, false otherwise. +newly-allocated chunk. The returned Boolean will be true if the +token was found, false otherwise. Pass this routine the following: diff --git a/TechDocs/html/CRef/Routines/R_9c.htm b/TechDocs/html/CRef/Routines/R_9c.htm index 5343b4c7e..ec76a31c6 100644 --- a/TechDocs/html/CRef/Routines/R_9c.htm +++ b/TechDocs/html/CRef/Routines/R_9c.htm @@ -166,9 +166,9 @@

This routine loads the specified token's TokenEntry - structure into a newly-allocated global memory block. If the token is not found, the returned error flag will be + structure into a newly-allocated global memory block. The returned Boolean will be true -; otherwise, it will be +if the token was found; otherwise, it will be false .

@@ -210,11 +210,10 @@

This routine loads the specified token's TokenEntry - structure into a passed buffer. The returned error flag will be + structure into a passed buffer. The returned Boolean will be true - if the token was not found, -false - otherwise. Pass this routine the following:

+if the token was found; otherwise, it will be +false. Pass this routine the following:

diff --git a/TechDocs/html/CRef/Routines/R_9d.htm b/TechDocs/html/CRef/Routines/R_9d.htm index f5b6a477e..98bb1a2be 100644 --- a/TechDocs/html/CRef/Routines/R_9d.htm +++ b/TechDocs/html/CRef/Routines/R_9d.htm @@ -1,240 +1,240 @@ - - - - - - - - - - - -GEOS C Routines: TokenLoadTokenChunk() ... - - -
- - -

-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 error flag will be -true - if the token could not be 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 -TokenUnlockTokenMoniker() - 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 -

-
-
- - -

-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 -TokenLockTokenMoniker() -. 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.

-
-
- -| Up: GEOS SDK TechDocs -| Up - - | Prev: TokenLoadMonikerBuffer() ... - | Next: UserAllocObjBlock ... -
- - - + + + + + + + + + + + +GEOS C Routines: TokenLoadTokenChunk() ... + + +
+ + +

+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; otherwise, it will be +false +.

+

+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 +TokenUnlockTokenMoniker() + 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 +

+
+
+ + +

+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 +TokenLockTokenMoniker() +. 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.

+
+
+ +| Up: GEOS SDK TechDocs +| Up + + | Prev: TokenLoadMonikerBuffer() ... + | Next: UserAllocObjBlock ... +
+ + +