Project: Webinterface II - Fidonet Messagebase Structure: SQUISH SDK
Squish Developers Kit
Version 2.00
Created May 23rd, 1994
Documentation produced by Scott Dudley
Copyright 1991-1994 by SCI Communications. All rights reserved.
Maximus and Squish are trademarks of SCI Communications.
TABLE OF CONTENTS
INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . 1
COPYRIGHT AND DISTRIBUTION RESTRICTIONS . . . . . . . . . . . 2
Distribution Policy . . . . . . . . . . . . . . . . . . 2
No Warranty . . . . . . . . . . . . . . . . . . . . . . 2
Author Contact Information . . . . . . . . . . . . . . . 3
MSGAPI FUNCTION REFERENCE . . . . . . . . . . . . . . . . . . 4
Initialization/Termination Functions . . . . . . . . . . 4
MsgOpenApi . . . . . . . . . . . . . . . . . . . . 4
MsgCloseApi . . . . . . . . . . . . . . . . . . . . 6
Area-Oriented Functions . . . . . . . . . . . . . . . . 6
MsgOpenArea . . . . . . . . . . . . . . . . . . . . 6
MsgCloseArea . . . . . . . . . . . . . . . . . . . 7
MsgValidate . . . . . . . . . . . . . . . . . . . . 8
MsgGetHighWater . . . . . . . . . . . . . . . . . . 8
MsgSetHighWater . . . . . . . . . . . . . . . . . . 9
MsgGetCurMsg . . . . . . . . . . . . . . . . . . . 9
MsgGetNumMsg . . . . . . . . . . . . . . . . . . . 9
MsgGetHighMsg . . . . . . . . . . . . . . . . . . . 9
MsgLock . . . . . . . . . . . . . . . . . . . . . . 10
MsgUnlock . . . . . . . . . . . . . . . . . . . . . 10
MsgInvalidHarea . . . . . . . . . . . . . . . . . . 10
Message-Oriented Functions . . . . . . . . . . . . . . . 11
MsgOpenMsg . . . . . . . . . . . . . . . . . . . . 11
MsgCloseMsg . . . . . . . . . . . . . . . . . . . . 12
MsgReadMsg . . . . . . . . . . . . . . . . . . . . 12
MsgWriteMsg . . . . . . . . . . . . . . . . . . . . 15
MsgKillMsg . . . . . . . . . . . . . . . . . . . . 17
MsgGetCurPos . . . . . . . . . . . . . . . . . . . 18
MsgSetCurPos . . . . . . . . . . . . . . . . . . . 18
MsgGetTextLen . . . . . . . . . . . . . . . . . . . 18
MsgGetCtrlLen . . . . . . . . . . . . . . . . . . . 19
MsgInvalidHmsg . . . . . . . . . . . . . . . . . . 19
UMSGID Translation Functions . . . . . . . . . . . . . . 19
MsgMsgnToUid . . . . . . . . . . . . . . . . . . . 19
MsgUidToMsgn . . . . . . . . . . . . . . . . . . . 20
CtrlInfo Manipulation Functions . . . . . . . . . . . . 20
MsgGetCtrlToken . . . . . . . . . . . . . . . . . . 20
MsgFreeCtrlToken . . . . . . . . . . . . . . . . . 21
MsgRemoveToken . . . . . . . . . . . . . . . . . . 21
MsgGetNumKludges . . . . . . . . . . . . . . . . . 21
MsgCvt4D . . . . . . . . . . . . . . . . . . . . . 22
MsgCreateCtrlBuf . . . . . . . . . . . . . . . . . 23
MsgCvtCtrlToKludge . . . . . . . . . . . . . . . . 24
MsgFreeCtrlBuf . . . . . . . . . . . . . . . . . . 24
Squish-Specific Functions . . . . . . . . . . . . . . . 24
SquishHash . . . . . . . . . . . . . . . . . . . . 24
SquishSetMaxMsg . . . . . . . . . . . . . . . . . . 25
API Changes from MsgAPI Version 0 . . . . . . . . . . . 25
BUILDING MSGAPI APPLICATIONS . . . . . . . . . . . . . . . . 26
Source File Requirements . . . . . . . . . . . . . . . . 26
Compiling Source Files . . . . . . . . . . . . . . . . . 26
Linking Your Application . . . . . . . . . . . . . . . . 27
Building the Sample Applications . . . . . . . . . . . . 28
BUILDING THE MSGAPI SOURCE . . . . . . . . . . . . . . . . . 29
OS/2 DLL DEVELOPMENT . . . . . . . . . . . . . . . . . . . . 30
Sample Feature DLLs . . . . . . . . . . . . . . . . . . 30
KILLRCAT.DLL . . . . . . . . . . . . . . . . . . . 30
MSGTRACK.DLL . . . . . . . . . . . . . . . . . . . 31
Feature DLL Programming Interface . . . . . . . . . . . 31
Building Feature DLLs . . . . . . . . . . . . . . . . . 37
SQUISH FILE FORMAT SPECIFICATION . . . . . . . . . . . . . . 38
Squish Philosophy . . . . . . . . . . . . . . . . . . . 38
Squish Data Types . . . . . . . . . . . . . . . . . . . 39
Data File Format . . . . . . . . . . . . . . . . . . . . 41
Index File Format . . . . . . . . . . . . . . . . . . . 48
Message Links . . . . . . . . . . . . . . . . . . . . . 50
Reading Messages . . . . . . . . . . . . . . . . . . . . 51
Writing Messages . . . . . . . . . . . . . . . . . . . . 52
Deleting Messages . . . . . . . . . . . . . . . . . . . 53
Concurrency Considerations . . . . . . . . . . . . . . . 53
INTRODUCTION
This document serves as a reference guide for version 2.0 of the
Squish Developers Kit. The primary purpose of this document is
to describe the C Application Programming Interface (API) for
Squish bases, also known as MsgAPI.
Information is included on rebuilding the MsgAPI source,
compiling applications that use MsgAPI, and a description of each
function within the MsgAPI. The standard MsgAPI distribution
supports Turbo C, Borland C, WATCOM C, and Microsoft C.
This document does not provide a tutorial on using the MsgAPI,
but those with a reasonable amount of programming experience
should have little trouble in using MsgAPI.
In addition, this document includes information on the "feature
DLL" interface that is supported by the OS/2 version of the
Squish tosser/scanner program. These hooks allow third-party
developers to manipulate messages when they are being processed
by Squish. These hooks are called when Squish is tossing and
packing messages.
Finally, this document also describes the physical layout of the
Squish file format. Although use of the MsgAPI is recommended,
this information should allow third-party developers to access
the Squish base directly, without going through a set of API
calls.
WARNING! THE SQUISH DEVELOPER'S KIT IS NOT A SUPPORTED PRODUCT.
We would be interested in hearing of any problems that you have
with this product, but we cannot provide technical support for
MsgAPI users.
While we have tried to ensure that the material provided in this
kit is correct, we also cannot guarantee that the code and
documentation will function correctly on all systems.
Please read the following section for information on distribution
terms and the product warranty.
Squish Developers Kit Version 2.0 - Page 1
COPYRIGHT AND DISTRIBUTION RESTRICTIONS
All of the source code, header files and documentation within the
Squish Developers Kit is copyright 1991-1994 by SCI
Communications. All rights reserved.
Distribution Policy
Although the MsgAPI code is copyrighted, you are granted a
limited license to modify or usr MsgAPI in your own applications.
1) You may use the MsgAPI code as part of any type of
application, including freeware, shareware, or commercial
programs. No royalties or licensing fees are required.
2) This code must not be sold on its own. While it is
permissible to sell an application that uses or contains the
MsgAPI code, you may not charge any extra fee (above the
base cost of the product) for just providing the user with a
copy of the Squish Developers kit.
Also, you may not charge any extra fee (above the base cost
of the product) for providing Squish base support within
your program.
3) If you use this code in your application, you must give
credit for the MsgAPI code and indicate that "Squish" is a
trademark of SCI Communications.
4) If you wish to identify your application as being compatible
with the Squish message format, you must ensure that the
original MsgAPI code is capable of reading and writing to
the message bases that are created by your program. If the
original MsgAPI code is unable to read the files created by
your program, you may not label your program as Squish-
compatible.
AS LONG AS THE ABOVE FOUR CONDITIONS ARE FOLLOWED, MSGAPI MAY BE
INCORPORATED INTO ANY TYPE OF APPLICATION WITHOUT CHARGE,
REGARDLESS OF THE NATURE OF THE APPLICATION (COMMERCIAL,
SHAREWARE, OR FREEWARE).
No Warranty
BECAUSE THE SQUISH DEVELOPERS KIT (SDK) IS LICENSED FREE OF
CHARGE, WE PROVIDE ABSOLUTELY NO WARRANTY. EXCEPT WHEN OTHERWISE
STATED IN WRITING, SCI COMMUNICATIONS AND/OR OTHER PARTIES
PROVIDE THE SDK "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
SQUISH, AND THE ACCURACY OF ITS ASSOCIATED DOCUMENTATION, IS WITH
Squish Developers Kit Version 2.0 - Page 2
YOU. SHOULD THE SDK OR ITS ASSOCIATED DOCUMENTATION PROVE
DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR
OR CORRECTION.
IN NO EVENT WILL SCI COMMUNICATIONS BE RESPONSIBLE IN ANY WAY FOR
THE BEHAVIOUR OF MODIFIED VERSIONS OF THE SDK. IN NO EVENT WILL
SCI COMMUNICATIONS AND/OR ANY OTHER PARTY WHO MAY MODIFY AND
REDISTRIBUTE SDK AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
OTHER PROGRAMS) THE SDK, EVEN IF SCI COMMUNICATIONS HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY
ANY OTHER PARTY.
Author Contact Information
If you make any modifications to this code, and if you feel that
the author would be interested in the changes, please forward the
source code to the author.
You can contact the author at any of the addresses listed below:
FidoNet: 1:249/106
Internet: sjd@f106.n249.z1.fidonet.org
CompuServe: >INTERNET:sjd@f106.n249.z1.fidonet.org
BBS: (613) 634-3058 (V.32bis)
Surface mail:
777 Downing St.
Kingston, Ont.
Canada K7M 5N3
The author can also be reached through the FidoNet EchoMail
conferences called MUFFIN (Maximus support) and TUB (Squish
support).
Sending correspondence via electronic mail is strongly preferred,
and the use of surface mail is discouraged. However, if you
really have to send paper mail (and expect to receive a reply),
please enclose a self-addressed, stamped envelope. (Users
outside of Canada should include an international postal reply
coupon instead of a stamp.)
DO NOT ATTEMPT TO CONTACT THE AUTHOR BY TELEPHONE! VOICE SUPPORT
WILL NOT BE PROVIDED FOR THIS PRODUCT!
Squish Developers Kit Version 2.0 - Page 3
MSGAPI FUNCTION REFERENCE
This section describes all of the functions in the MsgAPI that
can be used by application programs.
Initialization/Termination Functions
MsgOpenApi
sword MsgOpenApi(struct _minf *minf);
The MsgOpenApi function is used to initialize the MsgAPI.
This function must be called before any of the other API
functions are called, or else the results are undefined.
This function serves to initialize any needed structures,
and to prepare the message bases for use.
This function accepts one argument: a pointer to a
structure containing information about the application.
This structure contains the following information:
struct _minf
{
/* The following fields are required for all
* MsgAPI clients:
*/
word req_version;
word def_zone;
word haveshare;
/* The following fields are required when
* req_version >= 1:
*/
void OS2FAR * (MAPIENTRY *palloc)(size_t size);
void (MAPIENTRY *pfree)(void OS2FAR *ptr);
void OS2FAR * (MAPIENTRY *repalloc)(void OS2FAR *ptr,
size_t size);
void far * (MAPIENTRY *farpalloc)(size_t size);
void (MAPIENTRY *farpfree)(void far *ptr);
void far * (MAPIENTRY *farrepalloc)(void far *ptr,
size_t size);
};
'req_version' indicates the MsgAPI revision level that the
application is requesting. The compile-time revision level
can always be accessed using the constant 'MSGAPI_VERSION'.
'def_zone' should contain a default FidoNet zone number.
Squish Developers Kit Version 2.0 - Page 4
Certain message systems, such as the FTSC-0001 *.MSG format,
do not store zone information with each message. When the
API encounters such a message and no zone is present, the
specified zone will be used instead. A 'def_zone' of 0
indicates that nothing is to be inferred about the zone
number of a message, and in that case, the API functions
will return 0 as the zone number for any message with an
unknown zone.
'haveshare' is automatically filled in by the internal API
routines, and this flag indicates whether or not the DOS
"SHARE.EXE" program is currently loaded. Note that SHARE
must always be loaded to access Squish-format bases in a
multitasking or network environment. This field is not used
in the OS/2 version of the MsgAPI.
If 'req_version' is more than or equal to 1, the final six
fields in the _minf structure must be provided. These
fields are memory allocation hooks that MsgAPI will call
whenever it needs to allocate memory. (If req_version is 0,
or if one of the function pointers in this structure is
NULL, then MsgAPI will use its own memory allocation
routines.)
'palloc' is called to allocate a block of near memory. This
function should behave in the same manner as the ANSI
malloc() function. If this field is NULL, the MsgAPI will
use its own malloc() function.
'pfree' is called to free a block of near memory. This
function should behave in the same manner as the ANSI free()
function. If this field is NULL, the MsgAPI will use its
own free() function.
'repalloc' is called to reallocate a block of near memory.
This function should behave in the same manner as the ANSI
realloc() function. If this field is NULL, the MsgAPI will
use its own realloc() function.
'farpalloc' is called to allocate a block of far memory.
This function should behave in the same manner as the ANSI
malloc() function, except that a far pointer should be
returned. If this field is NULL, MsgAPI will use its own
malloc() function.
'farpfree' is called to free a block of far memory. This
function should behave in the same manner as the ANSI free()
function, except that a far pointer should be accepted. If
this field is NULL, MsgAPI will use its own free() function.
'farrepalloc' is called to reallocate a block of far memory.
This function should behave in the same manner as the ANSI
Squish Developers Kit Version 2.0 - Page 5
realloc() function, except that a far pointer should be
accepted and returned. If this field is NULL, MsgAPI will
use its own realloc() function.
MsgOpenApi() returns a value of 0 if the initialization was
performed successfully, and -1 if a problem was encountered.
MsgCloseApi
sword MsgCloseApi(void);
This function is used to deinitialize the MsgAPI. This
function performs any clean-up actions which may be
necessary, including the closing of files and releasing
allocated memory. This function should be called before the
application terminates.
MsgCloseApi returns a value of 0 if the API was successfully
deinitialized, and -1 otherwise.
Area-Oriented Functions
MsgOpenArea
HAREA MsgOpenArea(byte *name, word mode, word type);
This function is used to open or create a message area.
This function accepts three parameters:
'name' is the name of the message area to open. The
contents of this string are implementation-defined. (See
'type' for more information.)
'mode' is the mode with which the area should be opened.
Values for 'mode' are as follows:
MSGAREA_NORMAL Open the message area in a normal access
mode. If the area does not exist, this
function fails.
MSGAREA_CRIFNEC Open the message area in a normal access
mode. If the area does not exist, the
MsgAPI attempts to create the area. If
the area cannot be created, this
function fails.
MSGAREA_CREATE Create the message area. If the area
already exists, it is truncated or
started anew with no messages. If the
area cannot be created, this function
Squish Developers Kit Version 2.0 - Page 6
fails.
'type' specifies the type of message area to open. 'type'
can have any of the following values:
MSGTYPE_SDM Star Dot MSG (SDM). This specifies a
FTSC-0001 compatible access mode, and it
instructs the MsgAPI to create and read
Fido-compatible messages for this area. If
MSGTYPE_SDM is specified, 'name' should
contain the path to the *.MSG directory.
MSGTYPE_SQUISH Squish (*.SQ?) format. This specifies that
the proprietary Squish message format is to
be used for this area. 'name' should give
the path and root name (eight characters) for
the message area.
In addition, if the mask 'MSGTYPE_ECHO' is bitwise 'OR'ed
with the 'MSGTYPE_SDM' value, the area in question will be
treated as a FidoNet-style echomail area. This instructs
the MsgAPI to keep high-water mark information in the 1.MSG
file, and to stop the normal MsgAPI functions from writing
to the first message in each area. Other message formats
have a cleaner way of storing the high-water mark, so this
mask is only required for *.MSG areas.
Other values for 'type' are currently reserved.
If this function succeeds in opening the message area, an
HAREA handle is returned. This handle does not contain any
information which can be used directly by the caller; all
interaction should be performed through the MsgAPI functions
only.
If this function fails, NULL is returned, and the global
'msgapierr' variable is set to one of the following values:
MERR_NOMEM Not enough memory for requested task
MERR_NOENT The area did not exist or could not be
created.
MERR_BADF The message area is structurally damaged.
MsgCloseArea
sword MsgCloseArea(HAREA ha);
This function serves to "close" a message area. This
function performs all clean-up actions necessary, such as
Squish Developers Kit Version 2.0 - Page 7
closing files, changing directories, and so on.
The function accepts one argument, which must be an HAREA
handle returned by the MsgOpenArea function. The
MsgCloseArea function should be called for each area opened
by MsgOpenArea.
If the area was successfully closed, MsgCloseArea returns 0.
Otherwise, a value of -1 is returned and msgapierr is set to
one of the following:
MERR_BADH An invalid handle was passed to the function.
MERR_EOPEN Messages are still "open" in this area, so
the area could not be closed.
MsgValidate
sword MsgValidate(word type, byte *name);
The MsgValidate function validates a particular message
area, determining whether or not the area exists and if it
is valid.
'type' is the type of the message area, using the same
constants as specified for MsgOpenARea.
'name' is the name of the message area, using the same
format as specified for MsgOpenArea.
MsgValidate returns the value 1 if the area exists and is
valid. Otherwise. MsgValidate returns 0.
MsgGetHighWater
dword MsgGetHighWater(HAREA ha);
The MsgGetHighWater function returns the 'high water marker'
for the current area. This number represents the highest
message number that was processed by a message export or
import utility.
'ha' is a message area handle, as returned by MsgOpenArea.
The high water marker is automatically adjusted when
messages are killed.
The MsgGetHighWater function returns the high water mark
number on success, or 0 on error and sets msgapierr to:
Squish Developers Kit Version 2.0 - Page 8
MERR_BADH
MsgSetHighWater
sword MsgSetHighWater(HAREA mh, dword hwm);
The MsgSetHighWater function sets the 'high water marker'
for the current area.
'ha' is a message area handle, as returned by MsgOpenArea.
'hwm' is the new high water marker to use for the specified
area.
The MsgGetHighWater function returns 0 on success, or -1 on
error and sets msgapierr to:
MERR_BADH
MsgGetCurMsg
dword MsgGetCurMsg(HAREA ha);
The MsgGetCurMsg function returns the number of the last
message accessed with MsgOpenMsg.
'ha' is a message area handle, as returned by MsgOpenArea.
MsgGetCurMsg returns the current message number on success,
or 0 if there is no current message.
MsgGetNumMsg
dword MsgGetNumMsg(HAREA ha);
The MsgGetNumMsg function returns the number of messages in
the current message area. On error, MsgGetNumMsg returns
(dword)-1 and sets msgapierr to:
MERR_BADH
MsgGetHighMsg
dword MsgGetHighMsg(HAREA mh);
The MsgGetHighMsg function returns the number of the highest
message in the specified area. On error, MsgGetHighMsg
returns (dword)-1 and sets msgapierr to:
Squish Developers Kit Version 2.0 - Page 9
MERR_BADH
MsgLock
sword MsgLock(HAREA ha);
The MsgLock function 'locks' a message area for exclusive
access. This function may enable buffering or otherwise
improve performance, so it is advised that MsgLock be called
if speed is a concern when accessing the area.
All of the MsgAPI functions automatically perform file
locking and sharing internally, so this function is only
required when high performance is necessary.
'ha' is a message area handle, as returned by the
MsgOpenArea function.
MsgLock returns 0 on success. On error, MsgLock returns -1
and sets msgapierr to one of the following:
MERR_BADH
MsgUnlock
sword MsgUnlock(HAREA ha);
The MsgUnlock function unlocks a previously-locked message
area.
'ha' is a message area handle, as returned by MsgOpenMsg.
MsgUnlock returns 0 on success, or it returns -1 on error
and sets msgapierr to:
MERR_BADH
MsgInvalidHarea
sword MsgInvalidHarea(HAREA ha);
The MsgInvalidHarea function tests the given message area
handle for validity. If the message area handle is invalid,
this function returns TRUE and sets msgapierr to MERR_BADH.
Otherwise, a value of FALSE will be returned. returned.
Squish Developers Kit Version 2.0 - Page 10
Message-Oriented Functions
MsgOpenMsg
HMSG MsgOpenMsg(HAREA mh, word mode, dword msgn);
This function "opens" a message for access, and it must be
used to read from or write to a given message.
The function accepts three arguments:
'mh' is a message area handle, as returned by the
MsgOpenArea function.
'mode' is an access flag, containing one of the following
manifest constants:
MOPEN_CREATE Create a new message. This mode should only
be used for creating new messages.
MOPEN_READ Open an existing message for reading ONLY.
MOPEN_WRITE Open an existing message for writing ONLY.
MOPEN_RW Open an existing message for reading AND
writing.
'msgn' is the specified message number to open. If mode is
either MOPEN_READ, MOPEN_WRITE or MOPEN_RW, the message
number must currently exist in the specified area. If mode
is set to MOPEN_CREATE, a value of 0 for 'msgn' indicates
that a new message should be created, and assigned a number
one higher than the current highest message. If 'msgn' is
non-zero, but MOPEN_CREATE is set to the number of a
currently-existing message, the specified message will be
truncated and the new message will take its place.
For MOPEN_READ or MOPEN_RW, the following constants can also
be passed in place of 'msgn':
MSGNUM_CUR Open the last message which was accessed by
MsgOpenMsg.
MSGNUM_PREV Open the message prior to the last message
accessed by MsgOpenMsg.
MSGNUM_NEXT Open the message after the last message
accessed by MsgOpenMsg.
The MsgAPI maintains the number of the last message opened
by MsgOpenMsg, which is used when processing these
constants. (See also MsgGetCurMsg.)
Squish Developers Kit Version 2.0 - Page 11
If the message was successfully opened, the MsgOpenMsg
function will return a HMSG handle. Otherwise, a value of
NULL is returned, and msgapierr will be set to one of the
following:
MERR_NOENT
MERR_NOMEM
MERR_BADF
MERR_BADA
MERR_BADH
MsgCloseMsg
sword MsgCloseMsg(HMSG hmsg);
The MsgCloseMsg function serves to "close" a message which
has been previously opened by MsgOpenMsg. All messages
should be closed after use, or else data loss may result.
This function accepts a single argument, which is the
message handle that was returned by MsgOpenMsg.
If the message was successfully closed, this function
returns 0. Otherwise, a value of -1 is returned, and
msgapierr is set to:
MERR_BADH
MsgReadMsg
dword MsgReadMsg(HMSG hmsg, dword ofs, dword bytes,
byte *text, dword cbyt, byte *ctxt);
The MsgReadMsg function is used to read a message from disk.
This function can be used to read all parts of a message,
including the message header, message body, and control
information.
'hmsg' is a message handle, as returned by the MsgOpenMsg
function. The message in question must have been opened
with a mode of either MOPEN_READ or MOPEN_RW.
'msg' is a pointer to an XMSG (extended message) structure.
The format of this structure is detailed in the "Squish File
Format Specification" section, but it contains all of the
message information that is found in the message header,
including the to/from/subject fields, origination and
arrival dates, 4D origination and destination addresses, and
so forth. (See the appendices for specific information on
the XMSG structure itself.) If the application wishes to
Squish Developers Kit Version 2.0 - Page 12
read the header of a given message, this argument should
point to an XMSG structure. Otherwise, this argument should
be NULL, which informs the API that the message header does
not need to be read.
'ofs' is used for reading message text in a multiple-pass
environment. This defines the offset in the message body
from which the API should start reading. To start reading
from the beginning of the message, a value of 0L should be
given. Otherwise, the offset into the message (in bytes)
should be given for this argument. If the application does
not wish to read the message body, this argument should be
set to 0L.
'bytes' represents the maximum number of bytes to read from
the message. Fewer bytes may be read, but the API will read
no more than 'bytes' during this call. (See 'text', and
also this function's return value.) If the application does
not wish to read the message body, this argument should be
set to 0L.
'text' is a pointer to a block of memory, into which the API
will place the message body. The message body will be read
from the position specified by 'ofs', up to a maximum of
'bytes' bytes. If the application does not wish to read the
message body, this argument should be set to NULL.
'cbyt' represents the maximum number of bytes of control
information to read from the message.
'ctxt' is a pointer to a block of memory, into which the API
will place the message control information. No more than
'cbyt' bytes of control information will be placed into the
buffer. NOTE: unlike the message text functions, control
information can only be read in one pass.
The text read by this function is free-form. The message
body may or may not contain control characters, NULs, or any
other sequence of characters. Messages are simply treated
as a block of bytes, with no interpretation whatsoever.
In FidoNet areas, the message body consists of one or more
paragraphs of text. Each paragraph is delimited by a hard
carriage return, '\r', or ASCII 13. Each paragraph can be
of any length, so the text should be wordwrapped onto
logical lines before being displayed. If created by older
applications, paragraphs may also contain linefeeds ('\n')
and soft returns ('\x8d') at the end of each line, but these
are optional and should always be ignored.
As an example, assume that the following stream of text was
returned by MsgReadMsg():
Squish Developers Kit Version 2.0 - Page 13
"Hi!\r\rHow's it going? I got the new MsgAPI kit
today!\r\rAnyhow, gotta run!"
The "\r" marks are carriage returns, so they indicate the
end of a paragraph. Notice that the second paragraph is
fairly long, so it might have to be wordwrapped, depending
on the screen width. Your application might wordwrap the
text to make it look like this, if using a window 40
characters wide:
旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴�
� Hi! �
� �
� How's it going? I got the new MsgAPI �
� kit today! �
� �
� Anyhow, gotta run! �
읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴�
Paragraphs should always be wordwrapped by the application,
regardless of the screen/window size. When parsing the
message text, linefeeds and soft carriage returns should be
simply skipped.
The 'message control information' has a somewhat more
restricted format. The control information is passed to the
application in the form of an ASCIIZ string. The control
information is a variable-length string of text which
contains information not found in the (fixed-size) message
header.
The format of control information is given by the following
regular expression:
(group)+<NUL>
A 'group' consists of a <SOH> and a control item.
<SOH> is the Start Of Header character, or ASCII 01. All
control information strings must begin with an SOH, whether
or not control items are present.
Following the <SOH> is a control item. A control item
consists of a string which describes the type of control
item, or it may consist of nothing.
At least one group must be present in each message. If a
message has no extra control information, this field should
consists of a <SOH> followed by a single <NUL>.
Although the control items are free-form, the following
format is suggested:
Squish Developers Kit Version 2.0 - Page 14
<SOH>tag: value
where 'tag' is a descriptive identifier, describing the type
of field that the item represents. 'value' is simply
free-form text, which continues up until the next SOH or
<NUL>.
The character set for the tag and value consists of those
characters in the range 2-255, inclusive.
As an example, a message might have the following control
information:
<SOH>CHARSET: LATIN1<SOH>REALNAME: Mark Twain<NUL>
The trailing <NUL> byte must be included in the read count
given by 'cbyt'.
The return value for this function is the number of bytes
read from the message body. If no characters were
requested, this function returns 0.
On error, the function returns -1 and sets msgapierr to one
of the following:
MERR_BADH
MERR_BADF
MERR_NOMEM
MsgWriteMsg
sword MsgWriteMsg(HMSG hmsg, word fAppend, PXMSG msg,
byte *text, dword textlen, dword totlen,
dword clen, byte *ctxt);
The MsgWriteMsg function is used to write the message
header, body, and control information to a message.
'hmsg' is a message handle, as returned by the MsgOpenMsg
function. The message must have been opened with a mode of
MOPEN_CREATE, MOPEN_WRITE or MOPEN_RW.
'fAppend' is a boolean flag, indicating the state of the
message body. If 'append' is zero, then the API will write
the message body starting at offset zero. Otherwise, if
'append' is non-zero, the API will continue writing from the
offset used by the last MsgWriteMsg call. This flag applies
to the message body only; if no text is to be written to the
body, this argument should be set to 0.
'msg' is a pointer to an XMSG structure. If this pointer is
Squish Developers Kit Version 2.0 - Page 15
non-NULL, then MsgWriteMsg will place the XMSG structure
information into the message's physical header. To leave
the header unmodified, NULL should be passed for 'msg'.
THIS 'msg' PARAMETER MUST BE PASSED THE **FIRST** TIME THAT
MSGWRITEMSG() IS USED WITH A JUST-OPENED MESSAGE HANDLE!
'text' points to an array of bytes to be written to the
message body. If no text is to be written, this argument
should be NULL.
'textlen' indicates the number of bytes to be written to the
message body in this pass of the MsgWriteMsg function. The
text is free-format, and it can consist of any characters,
including NULs and control characters. If the application
does not wish to update the message body, a value of 0L
should be passed for this argument.
'totlen' indicates the total length of the message to be
written. This differs from 'textlen' in that the message
may be written a piece at a time (using small 'textlen'
values), but the total length of the message will not exceed
'totlen'. This parameter can be somewhat restrictive for
the application; however, this value is required for optimal
use of some message base types. The 'totlen' value does not
have to be the exact length of the message to write;
however, space may be wasted if this value is not reasonably
close to the actual length of the message. The rationale
behind this argument is that it gives the API writer the
most flexibility, in terms of supporting future message base
formats. If the application can provide this information to
the API, then almost any message base format can be
supported by simply dropping in a new API module or DLL.
To write text by making multiple passes, the FIRST pass
should call MsgWriteMsg with 'append' set to 0, with the
total length of the message in 'totlen', and the length of
'text' in textlen. Second and subsequent passes should set
'append' to 1, with the length of 'text' in textlen.
If the application does not wish to update the message body
of an existing message, a value of 0L should be passed for
this argument.
This argument MUST be specified during the first call to the
MsgWriteMsg when using a mode of MOPEN_CREATE, even if the
first call is not requesting any text to be written.
However, this value will be stored internally, and ignored
on the second and later calls.
When operating on a preexisting message (opened with
MOPEN_WRITE or MOPEN_RW), it is an error to specify a length
Squish Developers Kit Version 2.0 - Page 16
in 'totlen' which is greater than the original length of the
message.
'clen' specifies the total length of the control
information, including the trailing NUL byte. To write no
control information, a value of 0L should be passed for this
argument.
'ctxt' is a pointer to the control information string. To
write no control information, a value of 0L should be passed
for this argument.
N.B. Several restrictions apply to writing control
information:
First and foremost, control information can only be written
once. If the control information is to be changed, the
message must be read and copied to another message.
Secondly, control information MUST be written during or
before MsgWriteMsg is called with information about the
message body.
MsgWriteMsg returns a value of 0 on success, or -1 on error.
If an error occurred, msgapierr will be set to one of the
following values:
MERR_BADH
MERR_BADF
MERR_NOMEM
MERR_NODS
MsgKillMsg
sword MsgKillMsg(HAREA ha, dword msgnum);
The MsgKillMsg function is used to delete a message from the
specified message area.
'ha' is a message area handle, as returned by MsgOpenArea.
'msgnum' specifies the message number to kill.
It is an error to kill a message which is currently open.
MsgKillMsg returns a value of 0 if the message was
successfully killed, or it returns -1 on error and sets
msgapierr to one of the following:
MERR_BADH
MERR_NOENT
Squish Developers Kit Version 2.0 - Page 17
MERR_BADF
MERR_NOMEM
MsgGetCurPos
dword MsgGetCurPos(HMSG hmsg);
The MsgGetCurPos function retrieves the 'current position'
of a message handle. This position is where the MsgReadMsg
would read text from the message body next.
'hmsg' is a message handle, as returned by MsgOpenMsg.
MsgGetCurPos returns the offset into the message on success,
or (dword)-1 on error and sets msgapierr to:
MERR_BADH
MsgSetCurPos
sword MsgSetCurPos(HMSG hmsg, dword pos);
The MsgSetCurPos function sets the 'current position' in a
message handle. This position is used by MsgReadMsg to read
text from the message body.
'hmsg' is a message handle, as returned by MsgOpenMsg.
'pos' is the number of bytes into the message from which
MsgReadMsg should start reading.
MsgSetCurPos returns 0 on success, or -1 on error and sets
msgapierr to:
MERR_BADH
MsgGetTextLen
dword MsgGetTextLen(HMSG hmsg);
The MsgGetTextLen function retrieves the length of the
message body for the specified message.
'hmsg' is a message handle, as returned by MsgOpenMsg.
MsgGetTextLen returns the length of the body on success. On
error, it returns (dword)-1 and sets msgapierr to:
MERR_BADH
Squish Developers Kit Version 2.0 - Page 18
MsgGetCtrlLen
dword MsgGetCtrlLen(HMSG hmsg);
The MsgGetCtrlLen function retrieves the length of the
control information for the specified message.
'hmsg' is a message handle, as returned by MsgOpenMsg.
MsgGetCtrlLen returns the length of the control information
on success. On error, it returns (dword)-1 and sets
msgapierr to:
MERR_BADH
MsgInvalidHmsg
sword MsgInvalidHmsg(HMSG hmsg);
The MsgInvalidHmsg function tests the given message handle
for validity. If the message area handle is invalid, this
function returns TRUE and sets msgapierr to MERR_BADH.
Otherwise, a value of FALSE will be returned. returned.
UMSGID Translation Functions
MsgMsgnToUid
UMSGID MsgMsgnToUid(HAREA ha, dword msgnum);
The MsgMsgnToUid function converts a message number to a
'unique message ID', or UMSGID. This function can be used
to maintain pointers to an 'absolute' message number,
regardless of whether or not the area is renumbered or
packed. The MsgMsgnToUid function converts a message number
to a UMSGID, and the MsgUidToMsgn function converts that
UMSGID back to a message number.
'mh' is the message area handle, as returned by MsgOpenArea.
'msgnum' is the message number to convert.
MsgMsgnToUid returns a UMSGID on success; otherwise, it
returns 0 and sets msgapierr to:
MERR_BADH
MERR_BADF
MERR_NOENT
Squish Developers Kit Version 2.0 - Page 19
MsgUidToMsgn
dword MsgUidToMsgn(HAREA ha, UMSGID umsgid, word type);
The MsgUidToMsgn function converts a UMSGID to a message
number.
'ha' is the message area handle, as returned by MsgOpenArea.
'umsgid' is the UMSGID, as returned by a prior call to
MsgMsgnToUid.
'type' is the type of conversion to perform. 'type' can be
any of the following values:
UID_EXACT Return the message number represented by the
UMSGID, or 0 if the message no longer exists.
UID_PREV Return the message number represented by the
UMSGID. If the message no longer exists, the
number of the preceding message will be
returned.
UID_NEXT Return the message number represented by the
UMSGID. If the message no longer exists, the
number of the following message will be
returned.
If no valid message could be found, MsgUidToMsgn returns 0
and sets msgapierr to one of the following:
MERR_BADH
MERR_NOENT
CtrlInfo Manipulation Functions
MsgGetCtrlToken
byte *MsgGetCtrlToken(char *szCtrlInfo, char *szTag);
The MsgGetCtrlToken function finds a specified control
information tag in a message's control information buffer.
'szCtrlInfo' is the control information buffer for a
message, using the format described for MsgReadMsg.
'szTag' is the name of the tag to be extracted from the
control information buffer. (For example, tags such as
"FMPT ", "MSGID:" or "REPLY:" can be specified.)
Squish Developers Kit Version 2.0 - Page 20
If the tag is found in szCtrlInfo, the function allocates a
new block of memory and copies the tag to that new block.
The address of the new block is returned to the caller.
(The returned address should be freed later with a call to
MsgFreeCtrlToken.)
If the tag is not found in szCtrlInfo, this function returns
NULL.
For example, given a szCtrlInfo buffer that initially
contains the following text:
<SOH>REALNAME: John Doe<SOH>FMPT 24<SOH>TOPT 6<SOH>
A call to MsgGetCtrlToken(szBuf, "FMPT ") would return the
string "FMPT 24". After the call, szCtrlInfo would contain:
<SOH>REALNAME: John Doe<SOH>TOPT 6<SOH>
MsgFreeCtrlToken
void MsgFreeCtrlToken(byte *szCtrlToken);
The MsgFreeCtrlToken function frees a control token that was
returned by a call to MsgGetCtrlToken. This function must
be called to release memory that is allocated by the
MsgGetCtrlToken function.
'szCtrlToken' is the return value of a prior call to
MsgGetCtrlToken.
MsgRemoveToken
void MsgRemoveToken(byte *szCtrlInfo, byte *szTag);
The MsgRemoveToken function removes a specified control
token from a control information buffer. The existing text
in the buffer is shifted over such that no gaps are left in
the buffer.
'szCtrlInfo' is a control information buffer, using the
format specified in the description for MsgReadMsg.
MsgGetNumKludges
word MsgGetNumKludges(byte *szCtrlInfo);
The MsgGetNumKludges function returns the number of tags
contained in the control information buffer.
Squish Developers Kit Version 2.0 - Page 21
'szCtrlInfo' is a control information buffer, using the
format specified in the description for MsgReadMsg.
For example, given a control information buffer of the
following format:
<SOH>TAG1: ABC<SOH>TAG2: DEF<SOH>TAG3: GHI<SOH>
MsgGetNumKludges would return a value of 3, since three
separate tags exist within the control information buffer.
MsgCvt4D
void MsgCvt4D(byte *szCtrlInfo, NETADDR *orig,
NETADDR *dest);
The MsgCvt4D function converts FidoNet-style control
information (namely, the FMPT, TOPT and INTL tags) into a
proper 4D address. Messages are also un-gaterouted, if
necessary. After each tag is converted, it is removed from
the control information.
Most normal applications will not need to use this function.
MsgCvt4D is usually only used by tosser/scanner programs.
(The MsgAPI automatically handles 4D address conversions
when writing to *.MSG areas.)
'szCtrlInfo' specifies the buffer containing the original
control information for the message.
'orig' points to a NETADDR structure containing the two-
dimensional origination address of the message. (This
information is normally extracted from the 2D header of a
FTS-0001 packet.)
'dest' points to a NETADDR structure containing the two-
dimensional destination address of the message. (This
information is normally extracted from the 2D header of a
FTS-0001 packet.)
On output, the 'orig' and 'dest' parameters are updated with
zone and point information from the control information, if
necessary.
For example, if the following parameters were given as
input:
orig = {0, 249, 106, 0} /* zone and point fields are 0 */
dest = {0, 254, 1, 0} /* zone and point fields are 0 */
szCtrlInfo = <SOH>FMPT 4<SOH>TOPT 6<SOH>INTL: 2:254/1
Squish Developers Kit Version 2.0 - Page 22
1:249/106<SOH>REALNAME: John Doe<SOH>
A call to MsgCvt4D would result in the parameters being
updated as follows:
orig = {1, 249, 106, 4}
dest = {2, 254, 1, 6}
szCtrlInfo = <SOH>REALNAME: John Doe<SOH>
MsgCreateCtrlBuf
char *MsgCreateCtrlBuf(char *szKludgeText,
char **pszEndText,
unsigned *puiLength);
The MsgCreateCtrlBuf function is used to convert an array of
FidoNet-style "kludge lines" (as per FTS-0001) into a
control information buffer. Most application programs will
not need to use this function.
MsgCreateCtrlBuf is normally used by tosser/scanner programs
that need to directly manipulate FTS-0001 *.PKT files. Most
applications will not need to use this function.
'szKludgeText' points to the buffer containing the beginning
of an FTS-0001 style message body. MsgCreateCtrlBuf will
extract all of the control information from this buffer, up
until the first non-blank and non-kludge line is
encountered.
'pszEndText' should be a pointer to a 'char *' variable.
When MsgCreateCtrlBuf returns, the given variable will point
to the first byte of the text following the kludge
information. (In most cases, this will be the beginning of
the FTS-0001 style message body.)
'puiLength' is a pointer to a variable that contains the
length of the message buffer pointed to by 'szKludgeText'.
On return, this variable will be updated to reflect the real
length of the message body, not counting the kludge lines at
the beginning of the text.
This function returns a pointer to the newly-created control
information buffer. This buffer should be freed with a call
to MsgFreeCtrlBuf.
Squish Developers Kit Version 2.0 - Page 23
MsgCvtCtrlToKludge
char *MsgCvtCtrlToKludge(char *szCtrlInfo);
The MsgCvtCtrlToKludge function converts a body of control
information lines to an equivalent set of FTS-0001 kludge
lines.
MsgCvtCtrlToKludge is normally used by tosser/scanner
programs that need to directly manipulate FTS-0001 *.PKT
files. Most applications will not need to use this
function.
'szCtrlInfo' is a buffer of control information, using the
format given in the MsgReadMsg description.
This function returns a pointer to a new block of memory
containing the FTS-0001 style kludge lines. This buffer
should be freed with a call to MsgFreeCtrlBuf.
MsgFreeCtrlBuf
void MsgFreeCtrlBuf(byte *szCtrlBuf);
The MsgFreeCtrlBuf function is used to free the control
buffers which are allocated by the MsgCvtCtrlToKludge and
MsgCreateCtrlBuf functions.
'szCtrlBuf' is the return value of a prior call to
MsgCvtCtrlToKludge or MsgCreateCtrlBuf.
Squish-Specific Functions
SquishHash
dword SquishHash(byte *szTxt);
The SquishHash function is used to calculate a hash for a
"To:" field in a message.
'szTxt' is a pointer to the To: field of a message.
The algorithm used to calculate this hash is described in
the "Index File Format" subsection of the Squish File Format
Specification (contained later in this document).
Squish Developers Kit Version 2.0 - Page 24
SquishSetMaxMsg
dword SquishSetMaxMsg(HAREA ha, dword dwMaxMsg,
dword dwSkipMsg, dword dwMaxDays);
The SquishSetMaxMsg function is used to set the "maximum
messages", "skip messages" and "maximum age" parameters in a
Squish-format base.
'ha' is a Squish area handle, as returned by MsgOpenMsg.
'ha' must be a handle for a Squish-format message area.
'dwMaxMsg' is the maximum number of messages to allow in
this area.
'dwSkipMsg' is the number of messages to skip (at the
beginning of the base) before automatically deleting
messages.
'dwMaxDays' is the maximum age (in days) of messages to be
kept in the message base.
API Changes from MsgAPI Version 0
1) Renamed the msg.ftsc_date field to msg.__ftsc_date. Most of
the developers whoa re currently using this field should
actually be using the binary dates. See the comments for
the __ftsc_date field in MSGAPI.H for more information.
2) For compatibility with Windows, the MSG and MSGH names have
been changed. The old-style ones will still be there for
compatibility, but the API defaults to using HAREA instead
of MSG*, and HMSG instead of MSGH*. If you wish to turn off
the old definitions because they conflict with your source
files or the Windows headers, define MSGAPI_NO_OLD_TYPES
before including msgapi.h.
3) Renamed the InvalidMsgh and InvalidMsg functions to
MsgInvalidHarea and MsgInvalidHmsg, making them more
consistent with the other API names. Also fixed the
documented return codes for these functions.
4) A few slight changes were made to the XMSG structure.
Notably, now only 9 reply links are supported, and the field
that used to hold the tenth reply link is now used for
storing a message's UMSGID.
Squish Developers Kit Version 2.0 - Page 25
BUILDING MSGAPI APPLICATIONS
Source File Requirements
Any code which uses the MsgAPI must include the following line at
the top of each source file:
#include "msgapi.h"
If the MsgAPI source is not installed in the current directory,
you should add the MsgAPI directory to your compiler's "include
path" before trying to compile an application.
Programmers who are using MsgAPI with Windows should make sure to
define the "MSGAPI_NO_OLD_TYPES" constant before including the
msgapi.h header. Older versions of the MsgAPI used typedefs
which were incompatible with Windows, and this macro must be
defined to stop MsgAPI from using the old typedef names.
For information on using the MsgAPI function calls, please see
the section entitled "MsgAPI Function Reference". This section
contains a complete list of function calls in the API, including
formal parameters, notes on operation, and return codes.
If you are using TC++ or BC++, make sure that your application is
compiled in "C mode". MsgAPI was not designed for use with C++.
(In the TC++ IDE, set Options/Compiler/C++ to "CPP extension
only". For the command-line compiler, make sure that you are NOT
using the "-P" switch.)
Also, the distribution TC++/BC++ and WC libraries have been
compiled without overlay support. If you wish to use the WATCOM
or Borland overlay managers, you will have to recompile the
MsgAPI source with overlay support.
Compiling Source Files
No special requirements are necessary for compiling source files
for the DOS version of MsgAPI. However, make sure to select the
LARGE memory model when compiling your application. If you wish
to create an application using a different memory model, you will
have to recompile the MsgAPI code.
For compiling OS/2 applications that use MsgAPI, make sure that
the "OS_2" macro is defined on the compiler command-line. The
MsgAPI uses a different set of calling conventions under OS/2, so
all of your code must be compiled with the OS_2 macro defined.
Squish Developers Kit Version 2.0 - Page 26
Linking Your Application
This package already includes pre-made libraries for a number of
compilers, all built using the large memory model.
Under DOS, the MsgAPI library is statically linked with each
application. To link with the MsgAPI routines, simply specify
the required library file when linking. For example:
TLINK (Borland C, DOS):
tlink \bc\lib\c0l myapp,myapp,nul,bc_dos_l \bc\lib\cl
TLINK (Turbo C, DOS):
tlink \tc\lib\c0l myapp,myapp,nul,tc_dos_l \tc\lib\cl
WLINK (16-bit DOS):
wlink file myapp lib wc_dos_l name myapp
WLINK (32-bit DOS):
wlink file myapp lib wc_dos_f name myapp
LINK (DOS):
link myapp,myapp,nul,mc_dos_l;
If using the TC++ or BC++ IDE, simply declare the required
library as part of your project file. If you are using TC++ or
BC++ from the command line, you can specify the name of the
library after your source module, like this:
tcc -ml myapp.c tc_dos_l.lib
Under OS/2, the MsgAPI code is distributed as a DLL (dynamic link
library). To use this code in your application, simply link with
the DLL16.LIB import library (for 16-bit code) or the DLL32.LIB
import library (for 32-bit code). 16-bit OS/2 applications
should also be compiled in the large memory model.
After ensuring that MSGAPI.DLL and/or MSGAPI32.DLL are on your
LIBPATH, your application should be ready to run.
If you wish to use the default libraries and memory models, you
do not need any of the *.c files in the source directory.
However, you must still retain all *.h header files, since they
are required when compiling your application.
Squish Developers Kit Version 2.0 - Page 27
Building the Sample Applications
The SAMPLES subdirectory contains a number of sample programs
that use the MsgAPI. The commands given below can be used to
make the samples using the supported compilers:
Compiler OS Command
WATCOM C/16 DOS wmake -u -f makefile.wcd
WATCOM C/16 OS/2 wmake -u -f makefile.wco
WATCOM C/32 DOS wmake -u -f makefile.w3d
WATCOM C/32 OS/2 wmake -u -f makefile.w3o
Microsoft C DOS nmake -f makefile.mcd
Microsoft C OS/2 nmake -f makefile.mco
Turbo C DOS make -fmakefile.tcd
Borland C DOS make -fmakefile.bcd
Squish Developers Kit Version 2.0 - Page 28
BUILDING THE MSGAPI SOURCE
The MsgAPI sources have been tested with the following compilers:
WATCOM C/16 9.5 (DOS and OS/2)
WATCOM C/32 9.5 (DOS and OS/2)
Microsoft C 6.0 (DOS and OS/2)
Turbo C 2.0 (DOS only)
Borland C++ 3.1 (DOS only)
In addition, either the Microsoft Macro Assembler or the Borland
Turbo Assembler is required to build the MsgAPI source.
Other versions of these compilers (or compilers made by different
vendors) may also work, but only the compilers above have been
tested. The code works with both 16-bit and 32-bit compilers.
(However, if you add support for a compiler from a different
vendor, you will probably have to modify h\compiler.h.)
To recompile the MsgAPI source, simply edit the MAKEFILE within
the SRC directory. Sample definitions have been provided for all
of the supported compilers.
The makefile included in this package should work with almost any
make utility. This makefile has been successfully used under
Borland's MAKE, Microsoft's NMAKE, WATCOM's WMAKE, and Vadura's
DMAKE.
Warning! WMAKE users must use the "-u" command-line option when
running WMAKE.EXE. By default, WMAKE uses a non-standard line
continuation character, so the makefile will not be processed
correctly unless the "-u" option is used.
By default, the makefile is set up to compile for WATCOM C/16
9.5. To select another compiler, comment out all of the WC/16
definitions and uncomment those that pertain to your compiler.
Having made the appropriate modifications, simply type "make" to
rebuild the appropriate msgapi*.lib or msgapi*.dll file.
Under DOS, the "MODEL=" directive at the beginning of the
makefile can also be used to instruct the compiler to build a
MsgAPI library for one of the following memory models. MODEL
should be set to one of the following values:
s Small
m Medium
c Compact
l Large
Squish Developers Kit Version 2.0 - Page 29
OS/2 DLL DEVELOPMENT
The files in the FEATURES subdirectory contains everything that
is required to write third-party extensions for Squish.
This developers kit includes the source for two sample feature
DLLs. These DLLs are not part of the standard Squish
distribution, nor are they supported in any manner. They are
simply included to provide examples and to give a demonstration
of feature DLL programming.
Sample Feature DLLs
KILLRCAT.DLL
The first sample DLL is "KillrCat", a message filtering program
that selectively deletes messages based on a set of search
criteria. The following can be added to the top of your
SQUISH.CFG for a demonstration of KillrCat's capabilities:
; The Feature and/or Feature32 keywords tell Squish to load
; KILLRCAT and/or KILLRC32.
Feature KillrCat
Feature32 KillrC32
; Keyword:
;
; KillrCat <where> <echo_tag> <text>
;
; <where>: t = to
; f = from
; s = subject
; b = body
;
; Any combination of the above flags are permitted.
;
; <echo_tag> is the tag of the echo area.
;
; <text> is the text to find.
KillrCat b sysop249 Node Diff announcement
KillrCat s sysop249 Nodediff announcement
KillrCat sb users249 Latest Versions'n Stuff
KillrCat sb users249 Fidonews!
KillrCat b netmail File request generated by AMAX
When KillrCat find a message that matches the specified criteria,
it diverts the message from its usual area and places it in
BAD_MSGS. If you don't want to see these messages at all, fix
KILLRCAT.C and use the "delete message" bitmask in the return
code.
Squish Developers Kit Version 2.0 - Page 30
MSGTRACK.DLL
The other sample DLL is a message bouncer. This bouncer requires
a version 7 nodelist to work properly. Try adding the following
to your SQUISH.CFG for a demonstration:
Feature Msgtrack
Feature32 Msgtra32
; Path and name of nodelist
Msgtrack Nodelist <filename>
; Delete bounced messages
;Msgtrack Kill
When packing netmail, this bouncer will automatically return
messages to the originating node if the destination is not listed
in the nodelist.
<filename> should be the name of the NODEX.DAT file from your
version 7 nodelist.
The optional "Msgtrack Kill" line instructs the message bouncer
to delete messages after they have been bounced. (By default,
Squish just marks a bounced message as "Sent" and "Orphan", but
the message is left in the netmail area.)
Feature DLL Programming Interface
FEATURES.LZH includes a sample TEMPLATE.C file that can be used
as a template for writing feature DLLs.
A feature DLL must start with the following lines:
#define INCL_DOS
#include <os2.h>
#include "sqfeat.h"
os2.h is the standard OS/2 include file, as distributed in the
OS/2 toolkit. (For 16-bit feature DLLs, the OS/2 1.x toolkit is
required. For 32-bit feature DLLs, an OS/2 2.x toolkit is
required.)
sqfeat.h is the feature DLL include file. This contains
definitions and typedefs necessary to write a Squish feature DLL.
Each feature DLL must contain a number of functions. These
functions are used as hooks when Squish is performing certain
actions.
Squish Developers Kit Version 2.0 - Page 31
All of the hook functions must be exported by name, and they all
must use the pascal calling convention. The "FEATENTRY" keyword
automatically defines all of these attributes.)
The following functions must be present in every feature DLL:
FeatureInit
This function is responsible for performing feature-specific
initializations. FeatureInit() is called as soon as the
Feature or Feature32 keyword is encountered in SQUISH.CFG.
This function is passed a pointer to a _feat_init structure.
The structure contains the following fields:
struct_len The length of the _feat_init structure
szConfigName The name of the DLL. This should be filled
in by the FeatureInit() function. This name
is be used for adding feature-specific
configuration options to SQUISH.CFG.
When Squish encounters an unknown
configuration line, it first checks to see if
the first word matches any of the feature
DLLs, as given in the szConfigName field. If
a match is found, the configuration line is
passed to the DLL's FeatConfig function.
pfnLogMsg A pointer to the Squish logging routine.
This field is filled in by Squish itself. If
the feature DLL needs to add lines to the
Squish log, this function pointer can be used
to access the system log function.
The FeatInit() function should save a copy of
the pfnLogMsg field in a global variable,
such that the other Feat...() functions can
create log entries when necessary.
ulFlag This flag contains a bitmask that Squish uses
to optimize calls made to the feature DLL.
FeatInit() should initialize this field
before returning to the caller.
Any or all of the following flags can be
combined using the bitwise OR operator ("|"):
FFLAG_NETSENT Only call FeatNetMsg when
packing a message that
does not have the SENT
bit set.
Squish Developers Kit Version 2.0 - Page 32
FFLAG_NETTOUS Only call FeatNetMsg when
packing a message which
is addressed to one of
our addresses, as given
in SQUISH.CFG.
FFLAG_NETRECD Only call FeatNetMsg when
packing a message that
does not have the
RECEIVED bit set.
FFLAG_NETNOTTOUS Only call FeatNetMsg when
packing a message that is
NOT addressed to one of
our addresses, as given
in SQUISH.CFG.
If this field is given a value of 0, the
FeatNetMsg function will be called before
packing every netmail message.
FeatureConfig
This function is called whenever a feature-specific
configuration line is encountered. Feature DLLs can use
this function to process application-specific configuration
information from SQUISH.CFG.
This function is passed a pointer to a _feat_config
structure. The structure contains the following fields:
struct_len This field contains the length of the
_feat_config structure.
szConfigLine This field contains the line just read from
SQUISH.CFG. The first word on this line
matches the szConfigName value that was
placed in the _feat_init structure by
FeatInit.
ppszArgs This field contains a standard argv-style
variable, pointing to a tokenized version of
szConfigLine. The first word on szConfigLine
can be accessed as ppszArgs[0]; the second
word can be accessed as ppszArgs[1]; and so
on. If there are 'n' arguments, ppszArgs[0]
through ppszArgs[n-1] will contain pointers
to each word on the line, and ppszArgs[n]
will be NULL.
The FeatureConfig function should extract any relevant
Squish Developers Kit Version 2.0 - Page 33
information and store it in a global variable that can be
accessed by other functions in the DLL.
FeatureNetMsg
This function is called whenever a NetMail message is about
to be packed. This function is only used on non-
ArcmailAttach systems.
This function is passed a pointer to the _feat_netmsg
structure. The structure contains the following fields:
struct_len This field contains the length of the
_feat_netmsg structure.
ulAction This field controls the action taken by
Squish when FeatureNetMsg returns. The
contents of this field should be filled out
by the feature DLL.
This field can be set to a combination of any
of the following values, using the bitwise OR
operator ("|"):
FACT_NONE No action is taken
FACT_KILL The message is deleted upon
returning to Squish, before
the message is packed.
FACT_SKIP The message is left alone and
is not packed.
FACT_HIDE Do not pass this message to
other installed features. (By
default, all installed
features are called with a
pointer to the current
message. However, if the
FACT_HIDE flag is set, other
DLLs will not be called with
this message during the
current run.)
FACT_RWMSG Rewrite the current message.
This flag should be used if
the DLL modifies the message
header in pMsg.
pszAreaTag This field contains the name of the current
Squish Developers Kit Version 2.0 - Page 34
netmail area.
ha This is a MsgAPI HAREA handle for the current
netmail area.
hmsg This is a MsgAPI HMSG handle for the current
message.
ulMsgNum This contains the message number of the
current message.
pMsg Pointer to the message header of the current
message.
pszCtrl Pointer to the control information for the
current message.
pszMsgTxt Pointer to the message text for the current
message.
us A NETADDR-type structure giving Squish's
primary address.
FeatureTossMsg
This function is called whenever an EchoMail message is
about to be tossed.
This function is passed a pointer to the _feat_toss
structure. The structure contains the following fields:
struct_len Length of the _feat_toss structure.
ulTossAction This field specifies the action to be taken
when Squish returns from FeatureTossMsg.
This field can contain any of the following
options, combined using the bitwise OR
operator ("|"):
FTACT_NONE No action is taken.
FTACT_KILL Delete the message without
attempting to toss it.
FTACT_AREA Toss to the new area tag
specified in szArea.
FTACT_HIDE Do not pass this message to
any other installed features.
(See the comments for
Squish Developers Kit Version 2.0 - Page 35
FACT_HIDE in FeatureNetMsg for
more information.)
FTACT_NSCN Do not scan this message to
anyone else (if performing a
one-pass toss/scan).
szArea Area tag for this message. This field can be
changed to cause the message to be redirected
to another area, but to ensure that Squish
recognizes the change, the FTACT_AREA flag
should be set (above).
szPktName Name of the packet file that contains the
current message.
pMsg Pointer to the message header for the current
message.
pszCtrl Control information for the current message.
pszMsgTxt Message text of the current message.
FeatureScanMsg
This function is currently not supported by Squish.
However, it must be present for Squish to load the DLL.
FeatureTerm
This function is called when Squish is about to finish
execution. This function should perform feature-specific
clean-up operations.
Feature16Bit
This function is never actually called by Squish, but it
must be present in all 16-bit feature DLLs.
Feature32Bit
This function is never actually called by Squish, but it
must be present in all 32-bit feature DLLs.
Squish Developers Kit Version 2.0 - Page 36
Building Feature DLLs
The following commands can be used to build a sample 16-bit DLL
using WATCOM C/16 9.5 or above, where "template" is the name of
the source file for the feature:
[C:\] wcc /bd /dOS_2 /ml /zu template.c
[C:\] wlink sys os2 dll initi debug all name template.dll
file template.obj lib os2 opt manyauto, protmode, verb,
modname=template
The following commands can be used to build a sample 32-bit DLL
using WATCOM C/32 9.5 or above:
[C:\] wcc386 /bd /dOS_2 /fo=templa32 template.c
[C:\] wlink sys os2v2 dll initi debug all name templa32.dll
file templa32.obj lib os2386 opt verb, manyauto,
modname=templa32
Squish Developers Kit Version 2.0 - Page 37
SQUISH FILE FORMAT SPECIFICATION
This section describes the physical file layout of a Squish
message base. This is intended as a reference for developers who
are writing their own Squish-compatible programs. For an
overview of the Squish message base, see the section of
SQUISH.PRN entitled "Using Squish-Format Message Areas".
While the Squish MsgAPI library provides a standardized interface
to Squish and *.MSG bases for C programmers, authors who use
other languages may need to access Squish bases directly. This
section describes the implementation details of the Squish file
format.
Squish Philosophy
A standard Squish base consists of two files: a message data
file and a message index file. Both files have the same prefix,
but the data file has an extension of ".sqd", while the index
file has an extension of ".sqi".
From an overall point of view, the Squish data file consists of
messages stored in a doubly-linked list. The Squish data file
includes a header that contains pointers to the first and last
frames in the area, in addition to other area-specific
information.
In the data file, a "frame" is used to hold an individual
message. A frame consists of a frame header (which contains
links to the prior and next messages), followed by the optional
message header, control information and message body fields.
This "linked list of frames" approach is ideal for a BBS message
base. Almost all message base access is sequential, starting
from a particular offset, and reading or writing until the end of
the message base is reached. Since each frame header contains
the offset of the prior and next messages, no disk accesses are
required to find the preceding or following messages.
The index file is a flat array of Squish Index (SQIDX) records.
The index file is used primarily for performing random access
look-ups by message number.
Unlike other message base formats, the Squish base is only
loosely based on the concept of "message numbers". While all
messages have a message number, these numbers can change at any
time. By definition, the message numbers in a Squish base always
range from 1 to the highest message in the area. Consequently,
there are no "gaps" in message numbers, so a Squish message area
never needs to be renumbered.
Squish Developers Kit Version 2.0 - Page 38
While this makes it easy to scan through all of the messages in
an area, this also makes it difficult to find one specific
message. Consequently, the concept of a "unique message
identifier" or (UMSGID) is introduced.
When a message is created, it is assigned a 32-bit UMSGID. These
identifiers are unique and NEVER CHANGE. Unique message numbers
are never "renumbered", so once a UMSGID of a message is
obtained, it can always be used to find the current message
number of the given message, no matter how many messages have
been added or deleted in the interim.
Squish Data Types
The following integral types are used in the Squish file format
definitions:
Type Size Description
char 1 byte A one-byte unsigned character.
word 2 bytes A two-byte unsigned integer.
sword 2 bytes A two-byte signed integer.
dword 4 bytes A four-byte unsigned integer.
FOFS 4 bytes A four-byte unsigned integer. This type is
used to store offsets of frames within the
Squish data file.
UMSGID 4 bytes A four-byte unsigned integer. This type is
used to store unique message identifiers for
Squish messages.
The types above are stored in the standard Intel "backwords"
format, with the least significant byte being stored first, and
the most significant byte being stored last.
A two-byte integer containing 0x1234 would be stored as follows:
Offset Value
0 0x34
1 0x12
A four-byte integer containing 0x12345678 would be stored as
follows:
Offset Value
0 0x78
1 0x56
2 0x34
Squish Developers Kit Version 2.0 - Page 39
3 0x12
The Squish file format also uses a number of abstract data types:
The SCOMBO type is used for describing a message date/time stamp.
This structure has the following format:
Name Type Ofs Description
date word 0 DOS bitmapped date value. This field is
used to store a message date.
The first five bits represent the day of
the month. (A value of 1 represents the
first of the month.)
The next four bits indicate the month of
the year. (1=January; 12=December.)
The remaining seven bits indicate the
year (relative to 1980).
time word 2 DOS bitmapped time value. This field
used to store a message time.
The first five bits indicate the seconds
value, divided by two. This implies
that all message dates and times get
rounded to a multiple of two seconds.
(0 seconds = 0; 16 seconds = 8; 58
seconds = 29.)
The next six bits represent the minutes
value.
The remaining five bits represent the
hour value, using a 24-hour clock.
Total: 4 bytes
Squish Developers Kit Version 2.0 - Page 40
The NETADDR type is used for describing a FidoNet network
address. This structure has the following format:
Name Type Offset Description
zone word 0 FidoNet zone number.
net word 2 FidoNet net number.
node word 4 FidoNet node number.
point word 6 FidoNet point number. If the
system is not a point, this field
should be assigned a value of zero.
Total: 8 bytes
In addition, to describe an array of a given type, the "type[n]"
notation is used. For example, "char[6]" represents an array of
six contiguous characters. Likewise, "UMSGID[12]" represents an
array of twelve UMSGID types.
Data File Format
The Squish data file consists of two major sections:
1) A fixed-length area header, stored at the beginning of the
file.
2) A variable-length heap that comprises the rest of the file.
This part of the file is used for storing message text.
The area header stores pointers to the head and tail of two major
"chains" of messages; the message chain and the free chain. The
message chain is used to find all active messages in an area.
The free chain is used for storing the locations of deleted
messages, such that space can be reused at a later point in time.
The Squish data file always contains a copy of the following
_sqbase structure at file offset 0:
Name Type Offset Description
len word 0 Length of the _sqbase
structure.
reserved word 2 Reserved for future use.
num_msg dword 4 Number of messages in
this Squish base. This
should always be equal to
the value of the high_msg
field.
Squish Developers Kit Version 2.0 - Page 41
high_msg dword 8 Highest message number in
this Squish base. This
should always be equal to
the value of the num_msg
field.
skip_msg dword 12 When automatically
deleting messages, this
field indicates that the
first skip_msg messages
in the area should not be
deleted. (If max_msg=50
and skip_msg=2, this
means that the writing
program should start
deleting from the third
message whenever the
total message count
exceeds 50 messages.)
high_water dword 16 The high water marker for
this area, stored as a
UMSGID. This field is
used in EchoMail areas
only. This contains the
UMSGID of the highest
message that was scanned
by EchoMail processing
software.
uid dword 20 This field contains the
UMSGID to be assigned to
the next message created
in this area.
base char[80] 24 Name and path of the
Squish base, as an ASCIIZ
string, not including the
extension. This field is
optional and will not
necessarily be filled out
by all applications. (If
this field is not
supported, it should be
initialized to ASCII 0.)
begin_frame FOFS 104 Offset of the first frame
in the message chain.
last_frame FOFS 108 Offset of the last frame
in the message chain.
Squish Developers Kit Version 2.0 - Page 42
free_frame FOFS 112 Offset of the first frame
in the free chain.
last_free_frame FOFS 116 Offset of the last
message in the free
chain.
end_frame FOFS 120 Offset of end-of-file.
Applications will append
messages to the Squish
file from this point.
max_msg dword 124 Maximum number of
messages to store in this
area. When writing
messages, applications
should dynamically delete
messages to make sure
that no more than
max_msgs exist in this
area.
keep_days word 128 Maximum age (in days) of
messages in this area.
This field is not
normally used by
applications. However,
it is used by SQPACK when
performing a message area
pack.
sz_sqhdr word 130 Size of the SQHDR
structure. For
compatibility with future
versions of the Squish
file format, applications
should use this value as
the size of the SQHDR
structure, instead of
using a hardcoded
"sizeof(SQHDR)" value.
reserved char[124] 132 Reserved for future use.
Total: 256 bytes
To examine the messages in a Squish base, the application needs
to follow the message chain. To do this, start with the
begin_frame and/or end_frame fields. These fields contain the
offsets of the first and last frames (respectively) in the
message base.
Squish Developers Kit Version 2.0 - Page 43
A frame in the message chain consists of a Squish Frame Header
structure (SQHDR), followed by the XMSG message header, message
control information, and message body.
A frame in the free chain consists of a SQHDR structure only. A
free frame does not necessarily contain a message.
A SQHDR structure always has the following format:
Name Type Ofs Description
id dword 0 The frame identifier signature.
This field must always be set to a
value of 0xAFAE4453.
next_frame FOFS 4 Frame offset of the next frame, or
0 if this is the last frame.
prev_frame FOFS 8 Frame offset of the prior frame, or
0 if this is the first frame.
frame_length dword 12 Amount of space ALLOCATED for the
frame, not including the space used
by the SQHDR itself.
msg_length dword 16 Amount of space USED in this frame,
including the size of the XMSG
header, the control information,
and the message text. This field
does NOT include the size of the
SQHDR itself.
clen dword 20 Length of the control information
field in this frame.
frame_type word 24 This field can contain one of the
following frame type values:
0 Normal frame. This frame
contains an XMSG header,
followed by the message
control information and
the message body. Normal
frames should only be
encountered when
processing the normal
message chain.
1 Free frame. This frame
has been deleted, but it
can be reused. The
amount of available space
in the frame is given by
Squish Developers Kit Version 2.0 - Page 44
the frame_length field.
Free frames should only
be encountered when
processing the free
chain.
2 LZSS frame. This frame
type is reserved for
future use.
3 Frame update. The frame
is being updated by
another task. This is
only a transient frame
type; it indicates that
the frame should not be
manipulated by another
task.
All other frame types are
reserved for future use.
reserved word 26 Reserved for future use.
Total: 28 bytes
For a normal frame type, the XMSG header immediately follows the
Squish frame header. The XMSG structure has the following
format:
Name Type Ofs Description
attr dword 0 Message attributes. This is a
combination of any of the MSG*
attributes. (See below.)
from char[36] 4 Name of the user who originated
this message.
to char[36] 40 Name of the user to whom this
message is addressed.
subject char[72] 76 Message subject.
orig NETADDR 148 Originating network address of this
message.
dest NETADDR 156 Destination network address of this
message. (Used for netmail areas
only.)
Squish Developers Kit Version 2.0 - Page 45
date_written SCOMBO 164 Date that the message was written.
date_arrived SCOMBO 168 Date that the message was placed in
this Squish area.
utc_ofs sword 172 The message writer's offset from
UTC, in minutes. Currently, this
field is not used.
replyto UMSGID 174 If this message is a reply, this
field gives the UMSGID of the
original message. Otherwise, this
field is given a value of 0.
replies UMSGID[9] 178 If any replies for this message are
present, this array lists the
UMSGIDs of up to nine reply
messages.
umsgid UMSGID 214 The UMSGID of this message. THIS
FIELD IS ONLY VALID IF THE MSGUID
BIT IS SET IN THE "ATTR" FIELD.
Older Squish programs do not always
set this field, so its contents can
only be trusted if the MSGUID bit
is set.
__ftsc_date char[20] 218 FTS-0001 compatible date. Squish
applications should not access this
field directly. This field is used
exclusively by tossers and scanners
for preserving the original ASCII
message date. Squish applications
should use the binary dates in
date_written and date_arrived to
retrieve the message date.
Total: 238 bytes
Any of the following bitmasks can be used in the XMSG "attr"
field:
Attribute Value Description
MSGPRIVATE 0x00000001 The message is private.
MSGCRASH 0x00000002 The message is given a "crash"
flavour when packed. When both
MSGCRASH and MSGHOLD are both
enabled, the message is given a
"direct" flavour.
MSGREAD 0x00000004 The message has been read by the
addressee.
Squish Developers Kit Version 2.0 - Page 46
MSGSENT 0x00000008 The message has been packed and
prepared for transmission to a
remote system.
MSGFILE 0x00000010 The message has a file attached.
The filename is given in the "subj"
field.
MSGFWD 0x00000020 The message is in-transit; it is
not addressed to one of our primary
addresses.
MSGORPHAN 0x00000040 The message is orphaned. The
message destination address could
not be found in the nodelist.
MSGKILL 0x00000080 The message should be deleted from
the local message base when it is
packed.
MSGLOCAL 0x00000100 The message originated on this
system. This flag must be present
on all locally-generated netmail
for Squish to function properly.
MSGHOLD 0x00000200 The message should be given a
"hold" flavour when packed. When
combined with the MSGCRASH flag,
the message is given a "direct"
flavour.
MSGXX2 0x00000400 Reserved for future use.
MSGFRQ 0x00000800 The message is a file request. The
filename is given in the "subj"
field.
MSGRRQ 0x00001000 A receipt is requested. (Not
supported by Squish.)
MSGCPT 0x00002000 This message is a receipt for an
earlier MSGRRQ request.
MSGARQ 0x00004000 An audit trail is requested. (Not
supported by Squish.)
MSGURQ 0x00008000 This message is an update request.
The filename is given in the "subj"
field.
MSGSCANNED 0x00010000 This echomail message has been
scanned out to other systems.
Squish Developers Kit Version 2.0 - Page 47
MSGUID 0x00020000 The "uid" field contains a valid
UMSGID for this message.
Index File Format
The index file provides random access capability for a Squish
base. Given a message number, the index file can be used to
quickly find the frame offset for that message.
Similarly, given a UMSGID, the index file can also be used to
find the message number and/or the frame offset for the message.
The Squish index file is an array of Squish Index (SQIDX)
structures. Each SQIDX structure corresponds to an active
message. For a base containing 'n' messages, there are at least
'n' SQIDX structures. (There may also be extra SQIDX frames at
the end of the index file, but these will be initialized with
invalid values, as described below.)
The SQIDX for the first message is stored at offset 0.
The SQIDX for the second message is stored at offset 12.
The SQIDX for the third message is stored at offset 24.
(and so on)
The Squish Index structure (SQIDX) has the following format:
Name Type Ofs Description
ofs FOFS 0 Offset of the frame for this message. A
value of 0 is used to indicate an
invalid message.
umsgid UMSGID 4 Unique message ID for this message. A
value of 0xffffffff is used to indicate
an invalid message.
The umsgid field must always be greater
than the umsgid field of the preceding
SQIDX structure. UMSGIDs are assigned
serially, so this will normally be the
case. (A binary search is performed on
the index file to translate UMSGIDs, so
the umsgid field of the SQIDX headers
must always be stored in ascending
order.)
hash dword 8 The low 31 bits of this field contain a
hash the "To:" field for this message.
(See below for the hash function.) The
high bit is set to 1 if the MSGREAD flag
is enabled in the corresponding XMSG
Squish Developers Kit Version 2.0 - Page 48
header.
Total: 12 bytes
The following hash function is used to calculate the "hash" field
of the SQIDX structure. All variables are 32-bit unless
otherwise noted:
Set "hash" to a value of 0
For each 8-bit character "ch" in the To: field, repeat:
- Shift "hash" left by four bytes.
- Convert "ch" to lowercase
- Increment the hash by the ASCII value of "ch"
- Set "g" to the value of "hash"
- Perform a bitwise AND on "g", using a mask of
0xf0000000.
- If "g" is non-zero:
- Perform a bitwise OR on "hash" with the value
of "g".
- Shift "g" right by 24 bits.
- Perform a bitwise OR on "hash" with the value
of "g".
Perform a bitwise AND on "hash" with a value of 0x7fffffff.
The following C function can be used to calculate such a hash:
#include <ctype.h>
unsigned long SquishHash(unsigned char *f)
{
unsigned long hash=0;
unsigned long g;
char *p;
for (p=f; *p; p++)
{
hash=(hash << 4) + (unsigned long)tolower(*p);
if ((g=(hash & 0xf0000000L)) != 0L)
{
hash |= g >> 24;
hash |= g;
}
}
Squish Developers Kit Version 2.0 - Page 49
/* Strip off high bit */
return (hash & 0x7fffffffLu);
}
The SquishHash function is derived from the hashpjw() function by
P.J. Weinberger.
The following procedure can be used to find the frame offset or
UMSGID of a particular message number:
- Read the Squish data header and ensure that the message
number is less than or equal to the value given by
"high_msg".
- Subtract one from the message number.
- Multiply the result by 12 (the size of the SQIDX structure).
- The product is the required offset in the SQIDX file. Seek
to that offset and read the SQIDX header.
- The "fofs" field of the SQIDX structure indicates the offset
of the message frame. The "umsgid" field indicates the
UMSGID for the message in question.
To find a message number and/or frame offset of a particular
UMSGID, a simple binary search can be performed on the index
file. Since the SQIDX structures are (by definition) stored in
ascending order by the "umsgid" field. Conventional binary
search techniques can be used to find the SQIDX structure for a
particular UMSGID value.
Having found the SQIDX structure, the offset of the message can
be obtained from the SQIDX "fofs" field. In addition, the
message number can be determined from the location of the SQIDX
within the index file. (The SQIDX at offset 0 is for message 1;
the SQIDX at offset 12 is for message 2; and so on.)
Message Links
Like with any doubly-linked list, inserting a message into a
Squish message chain requires more work than just writing a
single header.
First of all, when writing the SQHDR for the new message, the
"prev_frame" and the "next_frame" fields must be set to the frame
offsets of the previous and next messages in the chain.
In addition, the "next_frame" field of the PREVIOUS message must
be set to the offset of the message being inserted. Likewise,
Squish Developers Kit Version 2.0 - Page 50
the "prev_frame" field of the NEXT message must be set to the
offset of the message being inserted.
Similar arguments apply to deleting a message. The prior and
next messages must be linked together to remove the current
message from the chain.
Beyond that, if the message is being inserted or deleted is at
the beginning or end of the chain, the begin_frame/last_frame or
free_frame/last_free_frame pointers must be updated (for the
message and free chains, respectively).
Reading Messages
Once the offset of a message frame is known, the application can
follow these steps to read the message:
- Seek to the specified frame offset.
- Read the SQHDR for the frame, making sure to read "sz_sqhdr"
bytes (as given in the _sqdata base header).
- Validate the "id" field. If the contents of this field are
not equal to the predefined constant (see "id", above), the
Squish base is damaged.
- Validate the "frame_type" field. If the type is equal to
"normal frame", proceed. If the type is equal to "frame
update", another application is processing the base, so the
message should be skipped. Any other value is an error.
- Read the XMSG header.
- Use the "clen" field of the SQHDR to determine the length of
the control information. Read this many bytes into an
array.
- Use the "msg_length" field of the SQHDR to determine the
total length of the frame. Subtract the size of the XMSG
header and the "clen" value, and use this result as the
length of the message text. Read this many bytes into an
array.
To read the next or prior message in a chain, simply use the
"next_frame" or "prev_frame" fields (respectively) to obtain the
frame offset (FOFS) of the indicated frame. A FOFS of zero
indicates that the end of the chain has been reached.
Squish Developers Kit Version 2.0 - Page 51
Writing Messages
To write a new message to a Squish base, an application should
follow this procedure:
- Obtain exclusive access to the Squish base. (See the
section entitled "Concurrency" for more information.)
- Re-read a copy of the Squish base header.
- Scan the messages in the "free_frame" chain to see if any
frame is large enough to accommodate the new message.
Ensure that the message header has a type of "free frame".
If so, unlink the message from the free chain, adjusting the
free_frame and last_free_frame pointers if necessary. (See
"Message Links", above.)
- If no free frame was found, allocate a frame at the end of
the file, using the "end_frame" offset from the base header.
Increment the "end_frame" value by the amount of space
allocated.
- Link the new SQHDR frame into the end of the message chain,
adjusting the begin_frame and last_frame pointers in the
base header (if necessary).
- Set the "frame_type" field of the new SQHDR to "frame
update" and write at the appropriate offset.
- Copy the "uid" field from the base header into the XMSG
header of the message to be written. Also set the MSGUID
flag in the "attr" field of the XMSG header. Then increment
the "uid" field in the base header.
- Increment the num_msg and high_msg values in the base
header.
- Rewrite the Squish base header.
- Relinquish exclusive access to the Squish base.
- Take the offset of the new SQHDR, and add the "sz_sqhdr"
value from the base header. Seek to that offset and write
the XMSG header.
- Write the message's control information.
- Write the message body.
- Set the frame type of the new message to "normal".
- Seek to the appropriate offset in the Squish index file, and
Squish Developers Kit Version 2.0 - Page 52
write a SQIDX header for the new message. Make sure
- Check the "high_msg" count of the message area to ensure
that it is less than or equal to max_msg. If not, delete
messages (while skipping the first skip_msg messages) until
the total message count is less than high_msg.
Deleting Messages
An application should follow this procedure to delete an existing
message:
- Obtain the frame offset of the message to be deleted. (If
given a message number, the frame offset for a message can
be found in the n'th record of the index file.)
- Read the frame header into memory.
- Obtain exclusive access to the message base.
- Update the header pointed to by the next_frame link to skip
over the message being deleted.
- Update the header pointed to by the next_frame link to skip
over the message being deleted.
- Shift the index file to remove the just-deleted message from
the message area. The global pointers in the Squish header
(num_msg, high_msg, and so on) should also be updated.
- Append the just-deleted header to the chain of "free"
messages. The frame should be inserted at the end of the
free list. The procedure used for inserting a free frame is
similar to that used in "Writing a message", except that the
free list is manipulated (instead of the message list).
- Relinquish exclusive access to the message base.
Concurrency Considerations
For Squish applications to operate properly in a multitasking or
networked environment, certain precautions must be taken when
manipulating a Squish base. While there are few restrictions on
reading message information, a certain set of conventions must be
followed when writing to a Squish base.
The procedure for obtaining exclusive access to the message base
(as used in the descriptions above) is as follows:
- Attempt to lock the first byte of the Squish data file. If
the lock fails, wait for one second and try again. If all
Squish Developers Kit Version 2.0 - Page 53
ten locks fail, the base is locked by another process and
cannot be modified.
- Re-read the Squish base header. Old copies of the header
may no longer be current, so this step must always be
performed when obtaining exclusive access to the Squish
base.
An application should not write to the Squish base until
performing the steps above.
Once exclusive access has been obtained, the application can
perform any necessary modifications. When the application no
longer needs to write to the message base, the following steps
can be performed to relinquish exclusive access:
- Write the updated Squish base header. This revised header
should include any modifications which were made while
exclusive access was in effect.
- Unlock the first byte of the Squish data file.
As long as all Squish applications follow these conventions for
accessing the Squish base, concurrency should not be a problem.
###
Squish Developers Kit Version 2.0 - Page 54