|
|
Sentry Spelling Checker Engine - Support |
|
Home |
You are here: Home > Support > Sentry Spelling Checker Engine
Product: Sentry Spelling Checker Engine Windows SDK, Sentry Spelling Checker Engine Source SDK
SSCE_OpenBlock and SSCE_CheckBlockDlg take parameters which indicate the size and length of a text block. This article explains the meanings of these parameters and offers advice on avoiding common problems.
A text block is a chunk of contiguous memory containing text. A text block is similar to a string. However, a text block differs from a string in one important respect: A text block contains extra room at the end to allow the text to grow. The text might grow if, during spell-checking, a short, misspelled word is replaced with a longer word. If extra space was not available for growth, an attempt to make the text grow might overwrite memory past the end of the text, with unpredictable results (including crashing).
The total capacity the text block is called the block size. The block size is like the capacity of a container, such as a bucket. The block size is measured in characters.
The number of text characters currently in the text block is called the block length. The block length is like the amount of some substance currently in a container, such as the amount of water in a bucket. The block length is measured in characters.
Following is an representation of a text block.
0123456789012345678901234567890123456789
The quick brown fox
The first line ("0123...") represents the block size. In this example, the block size is 40 characters. The second line ("The quick brown fox") represents the text in the block. The text occupies 19 characters, so the block length is 19. The length of the text can be increased by up to 21 characters (40 - 19) because that is the amount of extra space available at the end of the block.
When your application calls SSCE_OpenBlock, it passes as parameters the block size and the block length. Another parameter, the copyBlock parameter, indicates which party is responsible for maintaining the block's memory while it is open: your application or the Sentry spelling checker engine.
If the copyBlock parameter is false (i.e., has a value of 0), then your application takes responsibility for maintaining the block's memory. This means your application must allocate memory for the block, and keep that memory allocated and in the same location while the block is open. How memory is allocated for the text block depends on the programming language you use. The amount of memory you allocate for the block is the block size, and this is the value you must pass as the blockSz parameter to SSCE_OpenBlock. Stated another way, the value you pass as the blockSz parameter must be the total capacity of the text block you have allocated. For example, in C you could allocate a text block as a character array on the stack like this:
char block[100];
The block size in this example is 100. You must pass 100 as the blockSz parameter. The blockSz parameter tells SSCE_OpenBlock how much space your application has allocated for the text block. A common error is to do something like this:
char *block = "The quick brown fox";
and pass a large value, such as 1000, as the blockSz parameter, perhaps with the expectation that SSCE_OpenBlock will allocate space for the block. If the copyBlock parameter is false, then your application takes responsibility for allocating and maintaining the memory for the block while the block is open. When the copyBlock parameter is false, SSCE_OpenBlock simply records the location, size, and length of the text block, and trusts that your application has provided this information correctly and won't change anything while the block is open. If your application passes an inaccurate value for the blockSz parameter, then the Sentry engine will believe it has more space available than is actually available, and will allow the block's text to grow up to the specified block size. This may overwrite memory, resulting in a crash.
If the copyBlock parameter passed to SSCE_OpenBlock is true (i.e., non-zero), then the Sentry engine takes responsibility for maintaining the text block's memory while the block is open. When copyBlock is true, SSCE_OpenBlock allocates the amount of memory specified in the blockSz parameter and copies the number of characters specified in the blockLen parameter to the allocated memory. The memory allocated for the block is freed when the block is closed. When copyBlock is true, your application can specify any value it likes as the blockSz parameter (however, the value must be greater than or equal to the blockLen parameter, and it must be reasonable or SSCE_OpenBlock won't be able to allocate memory).
You may be wondering at this point why anyone would specify a false value for copyBlock when calling SSCE_OpenBlock, since specifying a true value causes SSCE_OpenBlock to take care of memory allocation details, simplifying the life of the application developer. However, setting copyBlock to true has the following disadvantages:
Memory must be allocated to hold the block. Memory is allocated on the heap, and this sometimes incurs a delay. If the text is already in a block-like buffer or array, allocating memory for another copy of it wastes space.
The text in the block must be copied to the allocated memory, consuming time if the text is large.
The block's contents must be retrieved via the SSCE_GetBlock function, resulting in another copy. Memory to hold the block's text must be allocated in the application, and the text must be copied, both of which consume time.
In environments where allocated memory may be moved (as can happen in languages that support garbage collection such as Visual Basic), the copyBlock parameter must be set to true. If copyBlock is false, SSCE_OpenBlock records the address, size, and length of the block. If the actual address changes, the Sentry engine has no way of knowing this, and may modify memory which is now used for some other purpose, possibly resulting in a crash.
When your application calls SSCE_CheckBlockDlg, it passes as parameters the block size and the block length. Your application is responsible for allocating memory for the text block. How memory is allocated for the text block depends on the programming language you use. The amount of memory you allocate for the block is the block size, and this is the value you must pass as the blockSz parameter to SSCE_CheckBlockDlg. Stated another way, the value you pass as the blockSz parameter must be the total capacity of the text block you have allocated. For example, in C you could allocate a text block as a character array on the stack like this:
char block[100];
The block size in this example is 100. You must pass 100 as the blockSz parameter. The blockSz parameter tells SSCE_CheckBlockDlg how much space your application has allocated for the text block. A common error is to do something like this:
char *block = "The quick brown fox";
and pass a large value, such as 1000, as the blockSz parameter, perhaps with the mistaken expectation that SSCE_CheckBlockDlg will allocate space for the block. SSCE_CheckBlockDlg trusts that the blockSz parameter accurately reflects the actual amount of space your application has allocated for the text block. If your application passes an inaccurate value for the blockSz parameter, then the Sentry engine will believe it has more space available than is actually available, and will allow the block's text to grow up to the specified block size. This may overwrite memory, resulting in a crash.
Visual Basic adjusts the amount of memory allocated to a string as the string is assigned. The best way to ensure that a text block represented as a VB string has enough space is to pad the string with extra characters like this:
Dim block As String
Dim blockLen As Long
Dim blockSz As Long
block = "The quick brown fox"
blockLen = Len(block)
block = block + Space$(200)
blockSz = Len(block)
In this example, room for growth is allocated via the Space$ function.
Copyright © 2015 Wintertree Software Inc.
