Techniques for Successful Calling

It is important to make your Word API code robust because a problem in your Word API code can cause problems in Word. Any possible error conditions should be accounted for, and proper allocation and deallocation of memory should be verified, especially when passing strings.

Handling Errors

The wdCommandDispatch function returns an error code that should always be checked. Error constants are defined in WDERROR.H, and errors specific to the Word API are listed in "Word API Errors" later in this appendix. Any nonzero returned value indicates a problem, and your code should accommodate all cases.

In Windows, you should also be careful with function calls into other Windows DLLs, and take appropriate action for any unexpected conditions. A good working knowledge of Windows programming techniques will help make your Word API programming successful.

Allocating Memory

It is the responsibility of the WLL to allocate and deallocate required memory. This means you must declare or allocate appropriate memory space for all string buffers, arrays, and so on. For dynamically allocated variables you must also remember to deallocate the memory later on.

There are two general approaches to allocating enough space for strings returned by Word API commands:

Fixed size

In general, 256 bytes is sufficient for virtually all returned strings,
so you can declare or allocate character buffers of this length for most purposes.

Double calling

Another useful technique is to first set BufferSize to 0 (zero), which guarantees that the command will fail. Upon return, however, BufferSize contains the number of bytes required to successfully return the string. You can then allocate a buffer of the exact size required and repeat the call.

Deallocating Memory

It is important to correctly deallocate all memory dynamically allocated by your WLL. Sometimes you can deallocate immediately after a function call. In other cases the returned data will need to be passed back to Word, or kept for future reference by your WLL. In these cases, you are responsible for keeping track of and eventually deallocating these blocks of memory. For example, you might set
a flag that can be checked in wdAutoRemove to indicate that a specific buffer is
to be deallocated.

Working with Strings

When a string is passed from WordBasic to a WLL function, it is automatically lengthened to a minimum of 256 bytes (including the null character) by Word. The WLL can always safely write up to 256 bytes into a passed string. If you need to pass back a longer string, you must take special steps to prevent overwriting the wrong parts of memory. For example, you might add another parameter to your function and insist that WordBasic passes the actual string length. The following WordBasic instructions demonstrate how this might work:


strsize = 500
x$ = String$( strsize, "x" )
rtn = MyNewCAPIFunction( strsize, x$ )

It is the ultimate responsibility of your WLL code to make sure the string is long enough before overwriting its contents.