Fidonet Mail Access

[This is preliminary documentation and subject to change.]

Updated: February 17, 2000

To PeteS,
the friend and
partner

Overview

Fidonet Mail Access is yet another toolkit to access Fidonet message bases. Despite the fact that Internet supersedes Fidonet, the latter still serves an important role in my home country, thus I decided to collect a bunch of the old source code written over the past years of my Fidonet involvement and release it in form of a toolkit that will hopefully allow others to come up with more up to date products which will make Fidonet life a bit more contemporary.

This document assumes that the reader is familiar with FTN technology and thus does not describe basics. Also, it does not go into details of native message base structure since this information is available in original specification published by message base authors.

Although many of the Fidonet Mail Access toolkit structures and calls are discussed in this document, the best reference is the actual source code.

Mission statement

Provide the ultimate solution for Fidonet message base access. In order to complete this mission, Fidonet Mail Access should meet the following requirements:

1. Support all popular message bases to the moment: Fts (aka FTS-001 or *.msg), Pkt, Squish, JAM and be easily extensible to support new message base formats.

2. Provide an application level abstraction of both message base storage and message format independent of the underlying message base as well as access to low level message base functionality. Such an abstraction should also be easily extensible to accommodate new message and base formats.

3. Should be portable across platforms (16 and 32 bits) and various compilers, plus allow both build time (.lib) static and late run-time (.dll) binding in a tread safe manner.

4. Exported objects and declarations should allow convenient encapsulation using C++, COM and Corba programming models.

5. Should be published with full source code under GPL-like license.

Since current version of Fidonet Mail Access toolkit implements support of JAM and Squish message base formats, their original specifications and toolkits greatly affected the way this toolkit has been designed. One can see that FMA message attributes are almost exactly the same as the JAM message attributes, FMA message properties are somewhat similar to JAM message subfields, and basic structure of the API calls is derived from Squish message base API.

Programming model

Fidonet Mail Access API allows you to access message bases at three different levels:

Abstraction level
At this level all the message base format specifics are hidden and the api exposes abstracted representation of the Fidonet mail message. This is the layer to use if you want your app to be message base independent.

Native level
At this level api exposes some of the message base specifics and native message format. This is the layer to use if your app supports only one or a few very similar message base formats.

Low level
At this level you have access to all the message base internals. Normally you don’t need to get that dirty unless you’re developing message base repair utilities.

Fidonet mail message abstraction

At the abstraction level Fidonet mail message is represented by FMM structure that contains little more than message attributes and a list of message properties:

typedef struct _FMM { /* emi */

UINT cb; // Size of this structure

UINT type; // Msg native type (FMMT_)

ULONG umsg; // Unique message id or number

ULONG attr; // Msg attributes (FMMA_)

PFMP pfmp; // Msg property list

#ifdef FMM_EXTENSION

FMM_EXTENSION // Extension declarations

#endif

} FMM, FAR * PFMM;

The type and umsg members of FMM structure contain the type of message base and unique message id or number of the message in the message base the message has been loaded from respectively.

The cb member of FMM structure and FMM_EXTENSION allows expansion of the core FMM structure when FMA toolkit is compiled along with the host application source code.

Following table lists all the message attributes in fmm.attr:

Attribute	Description
MA_LOCAL	Message was created locally
MA_INTRANSIT	Message is in-transit
MA_PRIVATE	Private message
MA_READ	Message was read by addressee
MA_SENT	Message was sent to remote system
MA_KILLSENT	Message will be deleted when sent
MA_ARCHIVESENT	Message will be archived when sent
MA_HOLD	Message is on hold for pick-up by addressee
MA_CRASH	Message is crash
MA_IMMEDIATE	Send message now, ignore restrictions
MA_DIRECT	Send directly to destination
MA_GATE	Send via gateway
MA_FILEREQUEST	Message contains file request
MA_FILEATTACH	Message contains attached file(s)
MA_TRUNCFILE	Attached files are to be truncated when sent
MA_KILLFILE	Attached files are to be deleted when sent
MA_RECEIPTREQ	Return receipt requested
MA_CONFIRMREQ	Confirmation receipt requested
MA_ORPHAN	Message destination is unknown
MA_ENCRYPT	Message text is encrypted
MA_COMPRESS	Message text is compressed
MA_ESCAPED	Message text is seven bit ASCII
MA_FORCEPICKUP	Force pickup
MA_TYPELOCAL	Message is for local use only (not for export)
MA_TYPEECHO	Message is for conference distribution
MA_TYPENET	Message is direct network mail
MA_SCANNED	Message is scanned (squish)
MA_FILEUPDATEREQ	Message contains file update request
MA_AUDITREQUEST	Audit request
MA_NODISPLAY	Message may not be displayed to user
MA_LOCKED	Message is locked, no editing possible
MA_DELETED	Message is deleted

Following is the Fidonet mail message property structure:

typedef struct _FMP { /* fmp */

struct _FMP * pfmpPrev; // Pointer to prev property

struct _FMP * pfmpNext; // Pointer to next property

ULONG id; // Property id (FMP_)

ULONG cb; // Property data size

//BYTE ab[cb]; // Property data

} FMP, FAR * PFMP;

Each message property is identified by 32-bit integer that contains hard coded unique property tag, property type flags and property position.

Following table lists all the message property type flags:

Flag	Description
FMP_ASZ	Property is zero terminated ASCII string stored immediately following FMP header. Note that if fmp.cb may be larger than the actual string length.
FMP_PSZ	Property is one or more pointers to zero terminated ASCII string stored immediately following FMP header. Note that fmp.cb / sizeof(PSZ) gives exact number of pointers.
FMP_U32	Property is one or more unsigned 32-bit values stored immediately following FMP header. Note that fmp.cb / sizeof(ULONG) gives number of values stored.
FMP_BIN	Property is an array of fmp.cb bytes stored immediately following FMP header.
FMP_DTM	Property is 32-bit date/time info in DTTM format stored immediately following FMP header.
FMP_EOM	Property represents end-of-message kludge. This flag is always OR’ed with one of the property type specification flags.
FMP_ONE	Specifies single instance property. This flag is always OR’ed with one of the property type specification flags.
FMP_KLU	Property is of FMP_ASZ type and represents FTN kludge.

Following table lists all the message property ids:

Property id	Type	Description
FMP_MESSAGETEXT	FMP_PSZ FMP_ONE	Message text
FMP_SENDERNAME	FMP_ASZ FMP_ONE	Author's name
FMP_RECEVRNAME	FMP_ASZ FMP_ONE	Recipient's name
FMP_ORIGADDR	FMP_ASZ FMP_ONE	Originating address
FMP_DESTADDR	FMP_ASZ FMP_ONE	Destination address
FMP_GATEADDR	FMP_ASZ FMP_ONE	Gate address
FMP_SUBJECT	FMP_ASZ FMP_ONE	Message subject
FMP_FILEATTACH	FMP_ASZ	File attachment
FMP_FILEREQUEST	FMP_ASZ	File request
FMP_FILEUPDATEREQ	FMP_ASZ	File update request
FMP_DTTMWRITTEN	FMP_DTM FMP_ONE	Date and time when message was written
FMP_DTTMRECEIVED	FMP_DTM FMP_ONE	Date and time when message was received
FMP_DTTMPROCESSED	FMP_DTM FMP_ONE	Date and time when message was processed
FMP_MSGREPLYTO	FMP_U32 FMP_ONE	Message which this message replies to
FMP_MSGREPLIES	FMP_U32 FMP_ONE	Messages which reply to this message
FMP_MSGREPLYNEXT	FMP_U32 FMP_ONE	Next message in reply chain if any
FMP_TIMESREAD	FMP_U32 FMP_ONE	Number of times this message was read
FMP_PASSWORDCRC	FMP_U32 FMP_ONE	CRC-32 of password to access message
FMP_MESSAGECOST	FMP_U32 FMP_ONE	Cost of message transfer
FMP_AREA	FMP_KLU FMP_ONE	FTN ^aAREA kludge info
FMP_MSGID	FMP_KLU FMP_ONE	FTN ^aMSGID kludge info
FMP_REPLYID	FMP_KLU FMP_ONE	FTN ^aREPLYID kludge info
FMP_PID	FMP_KLU FMP_ONE	FTN ^aPID kludge info
FMP_TID	FMP_KLU FMP_ONE	FTN ^aTID kludge info
FMP_TZUTC	FMP_KLU FMP_ONE	FTN ^aTZUTC kludge info [+\|-]NNNN
FMP_FLAGS	FMP_KLU FMP_ONE	FTN ^aFLAGS kludge info
FMP_CHARSET	FMP_KLU FMP_ONE	FTN ^aCHRS kludge info
FMP_REALNAME	FMP_KLU FMP_ONE	FTN ^aREALNAME kludge info
FMP_REPLYADDR	FMP_KLU FMP_ONE	FTN ^aREPLYADDR kludge info
FMP_REPLYTO	FMP_KLU FMP_ONE	FTN ^aREPLYTO kludge info
FMP_FTSKLUDGE	FMP_KLU	Unknown kludge line
FMP_SEENBY2D	FMP_KLU FMP_EOM	2D net/node SEEN-BY information
FMP_PATH2D	FMP_KLU FMP_EOM	2D net/node PATH information
FMP_EOMKLUDGE	FMP_KLU FMP_EOM	Unknown kludge line at end of message

Property position is an integer from 0 to 255 hard coded in the property id that determines order in which properties appear in Fidonet mail message property list. The API maintains this order automatically so that properties with lower position value go before properties with higher one. Properties with equal position value are sorted in the order they are added to the property list. This technique allows reasonable property ordering which directly affects the sequence in which the message kludges are written in the native message when it gets stored in the message base.

Unique message id’s and message numbers

Fidonet Message Access toolkit follows the unique message id paradigm introduced with Squish message bases.

Function reference

Fma functions

This section describes only the most important Fma functions. There are many other functions that can be useful for the application, for example memory allocation, date and time conversion, CRC32 and hash generation, file access, debug logging, etc. Check the Fidonet Message Access toolkit headers to see for these functions.

FmaCreateMsg

This function creates new Fidonet Mail Message object.

FMAAPI_(PFMM) FmaCreateMsg(UINT cbExtra);

Parameters

cbExtra

Specifies number of extra bytes to allocate at the end of the FMM structure.

Return values

If the function succeeds, the return value is pointer to the created Fidonet Mail Message object.

If the function fails, the return value is NULL. To get error code, call FmaGetLastError.

Remarks

The Fidonet Mail Message object returned by this function contains no attributes and no properties.

When you no longer need the Fidonet Mail Message object, call FmaDestroyMsg function to destroy it.

FmaDestroyMsg

This function destroys Fidonet Mail Message object,

FMAAPI_(BOOL) FmaDestroyMsg(PFMM pfmm);

Parameters

pfmm

Pointer to Fidonet Mail Message object.

Return values

This function always returns TRUE.

Remarks

The pfmm parameter can be NULL.

FmaDumpMsg

This function dumps the Fidonet Mail Message object.

FMAAPI_(BOOL) FmaDumpMsg(PFMM pfmm);

Parameters

pfmm

Pointer to Fidonet Mail Message object.

Return values

This function always returns TRUE.

Remarks

This function is only available when Fidonet Message Access toolkit is compiled with FMA_LOG defined.

FmaGetFmp

This function returns pointer to specified Fidonet Mail Message property.

FMAAPI_(PFMP) FmaGetFmp(PFMM pfmm, ULONG id, UINT ifmp);

Parameters

pfmm

Pointer to Fidonet Mail Message object.

Fidonet Mail Message property id.

ifmp

Index of the Fidonet Mail Message property to return if the message contains more than one property with the specified id.

Return values

If the function succeeds, the return value is pointer to the Fidonet Mail Message property with the specified id.

If the function fails, the return value is NULL. To get error code, call FmaGetLastError.

Remarks

To retrieve first or the only property with the specified id call this function with ifmp parameter set to zero.

To retrieve all the properties with the specified id call this function incrementing ifmp parameter until it returns NULL.

FmaDelFmp

This function deletes the specified Fidonet Mail Message property.

FMAAPI_(BOOL) FmaDelFmp(PFMM pfmm, ULONG id, UINT ifmp);

Parameters

pfmm

Pointer to Fidonet Mail Message object.

Fidonet Mail Message property id.

ifmp

Index of the Fidonet Mail Message property to delete if the message contains more than one property with the specified id.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

To delete first or the only property with the specified id call this function with ifmp parameter set to zero.

To delete all the properties with the specified id call this function with ifmp parameter set to zero until it returns FALSE.

FmaAddFmp

This function adds the specified Fidonet Mail Message property.

FMAAPI_(PFMP) FmaAddFmp(PFMM pfmm, ULONG id, PVOID pbData, ULONG cbData);

Parameters

pfmm

Pointer to Fidonet Mail Message object.

Fidonet Mail Message property id.

pbData

Pointer to the Fidonet Mail Message property data. If this parameter is NULL, the property data is initialized to zeros.

cbData

Size of Fidonet Mail Message property data. When adding properties with FMP_ASZ type cbData can be –1 in which case the size of the string will be calculated automatically.

Return values

If the function succeeds, the return value is pointer to the added Fidonet Mail Message property.

If the function fails, the return value is NULL. To get error code, call FmaGetLastError.

Remarks

When adding a property with FMP_ONE flag existing property with the same id is automatically deleted.

New properties are inserted before the existing property with the higher position value and after the existing property with equal or lesser position value.

FmaAddFmpFormat

This function adds the specified Fidonet Mail Message property with formatting.

FMAAPIV_(PFMP) FmaAddFmpFormat(PFMM pfmm, ULONG id, PSZ pszFormat, ...);

Parameters

pfmm

Pointer to Fidonet Mail Message object.

Fidonet Mail Message property id with the FMP_ASZ type.

pszFormat

printf-style formatting string.

…

Variable parameter list for printf-style formatting.

Return values

If the function succeeds, the return value is pointer to the added Fidonet Mail Message property.

If the function fails, the return value is NULL. To get error code, call FmaGetLastError.

Remarks

When adding a property with FMP_ONE flag existing property with the same id is automatically deleted.

New properties are inserted before the existing property with the higher position value and after the existing property with equal or lesser position value.

FmaDumpFmp

This function dumps the specified Fidonet Mail Message property.

FMAAPI_(BOOL) FmaDumpFmp(PFMP pfmp);

Parameters

pfmp

Pointer to Fidonet Mail Message property.

Return values

The return value is always TRUE

Remarks

This function is only available when Fidonet Message Access toolkit is compiled with FMA_LOG defined.

FmaOpenArea

This function opens the specified area.

FMAAPI_(HAREA) FmaOpenArea(PSZ pszPath, UINT type, UINT fOpenMode, ULONG fl,

NETADDR * pnetAddr);

Parameters

pszPath

Pointer to a null-terminated string that specifies the path to the message base.

type

Specifies the type of the message base to open. This parameter can be one of the types previously registered with the call to FmaRegisterApi function. Following message base types area supported by the current version of Fidonet Message Access toolkit:

MBTYPE_FTS	FTS-001 message base, also known as *.MSG base
MBTYPE_SQU	Squish message base
MBTYPE_JAM	JAM message base

fOpenMode

Specifies the open mode. This parameter can be one of the following:

OPENAREA_EXISTING	Open existing area, fail if it does not exist
OPENAREA_ALWAYS	Open existing area or create it if does not exist
OPENAREA_CREATE_NEW	Create new area, fail if it already exists
OPENAREA_CREATE_ALWAYS	Create new area, clear it if it exists

Specifies the open flags. This parameter can be a combination of the following flags:

FOA_LOCKAREA	Automatically lock area upon opening and unlock it when closing. This is the same as calling FmaLockArea function.
FOA_READONLY	Open area in read-only mode. This allows opening areas on CD-ROM’s and other read-only storage.
FOA_DENYALL	Open area in exclusive mode. Denies all other access to the area while it is opened. Use only for message base maintenance.
FOA_NETMAIL	Area is a net mail area.
FOA_ECHOMAIL	Area is an echo mail area.
FOA_HIGHREAD	Maintain highest read message for Fts and Squish areas. Highest read message is always maintained for JAM areas.
FOA_KEEPUMSG	Keep unique message id in smh.umsg. Applies to Squish only. For compatibility with SQDEV200, Fidonet Message Access zeroes smh.umsg when passing Squish message header to caller. Specifying this flag if you want to receive this umsg,
FOA_DELAYTRIMMING	Delay maximum message count trimming until close area time. Applies to Squish only. Normally, if creating a new message in Squish message base will exceed message count limit, the necessary amount of old messages is deleted to keep resulting message count within limits. This imposes performance penalty that can be avoided by specifying this flag. However, keep in mind that this may cause temporary growth of the message base size. This flag is intended to be used primarily by mail tossers.
FOA_CREATEATEOF	Create new messages at end of message base. Applies to Squish only. Normally, when creating a new message in Squish message base, the free frame chain is searched to find a free frame large enough to hold the new message. This imposes performance penalty that can be avoided by specifying this flag. Keep in mind that message base size will grow faster since free frames are not reused. This flag is intended to be used primarily by mail tossers.

pnetAddr

Specifies the default network address for the area that is used if message network address is incomplete.

Return values

If the function succeeds, the return value is handle to the open area.

If the function fails, the return value is NULL. To get error code, call FmaGetLastError.

Remarks

This function searches the registered message base API table (see FmaRegisterApi function) and thunks down to the native message base open function.

FmaCloseArea

This function closes an open area.

FMAAPI_(BOOL) FmaCloseArea(HAREA harea);

Parameters

harea

Handle to the area to be closed.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

The handle can’t be used after the area has been closed.

Any open messages for the area being closed are closed and area is unlocked if it’s locked.

This function thunks down to the appropriate native message base function.

FmaLockArea

This function locks or unlocks the area.

FMAAPI_(BOOL) FmaLockArea(HAREA harea, BOOL bLock);

Parameters

harea

Handle to an open area.

bLock

Specifies whether the internal area lock counter is to be incremented or decremented. If bLock is TRUE, the area lock count is incremented by one. If bLock is FALSE, the area lock count is decremented by one.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

This function sets an area lock counter that determines whether the area is locked. The area is locked if the area lock count is greater than 0. This allows nested calls to this function.

When the area is locked, no other process can change the contents of the area. In addition, the message base index is cached for faster access.

If the first attempt to lock the area fails, this function tries to lock it up to 5 times with a 1 second multitasking friendly interval between attempts.

Area can be locked upon opening and unlocked when closing by specifying the FOA_LOCKAREA flag when calling the FmaOpenArea function.

This function thunks down to the appropriate native message base function.

FmaValidateMsg

This function validates the specified message number.

FMAAPI_(BOOL) FmaValidateMsg(HAREA harea, MSGN msgn, PULONG pimsg);

Parameters

harea

Handle to an open area.

msgn

Specifies the message number to validate.

pimsg

Points to the ULONG variable that receives message index. This parameter can be NULL.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

This function verifies that the message with the specified number actually exists by checking area internal data structures, which is a lot faster than trying to open message with the specified message number.

This function thunks down to the appropriate native message base function.

FmaCreateMsgMap

This function creates an area message map.

FMAAPI_(BOOL) FmaCreateMsgMap(HAREA harea, UMSG * paumsg[], PULONG pcumsg);

Parameters

harea

Handle to an open area.

paumsg

Points to a variable, which receives the pointer to the created message map.

pcumsg

Points to a variable, which receives the number of entries in the created message map.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

Message map is an array of unique message ids that can be used for quickly scanning message base contents.

Memory allocated for the message map has to be freed with a call to FmaMemFree.

This function thunks down to the appropriate native message base function.

FmaEnumMsgs

This function enumerates area messages.

FMAAPI_(BOOL) FmaEnumMsgs(HAREA harea, PFNENUMMSGS pfnCallback,

PVOID pvCallbackData, ULONG fl);

Parameters

harea

Handle to an open area.

pfnCallback

Pointer to the callback function with the following prototype:

FMACALLBACK BOOL EnumMsgs(PENUMMSGINFO pemi, PVOID pvCallbackData);

Following is the message enumeration info structure:

typedef struct _ENUMMSGINFO { /* emi */

MSGN msgn; // Message number

UMSG umsg; // Message uid

ULONG imsg; // Message index

ULONG offs; // Message offset (sqi.lfm or jdx.lmh)

ULONG hash; // Message hash (sqi.hash or jdx.crc)

HAREA harea; // Message area handle

} ENUMMSGINFO, FAR * PENUMMSGINFO;

pvCallbackData

Custom pointer passed to the callback function.

Specifies flags that control enumeration process. This parameter can be any combination of the following flags:

FENUMMSGS_REVERSE	Enumerate in reverse order
FENUMMSGS_SAFEENUM	Allows messages to be deleted while enumerating.

Return values

If the function succeeds, the return value is equal to the last value returned by the call back function.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError, which can be FMAERROR_NONE if the callback function returned FALSE to cancel the enumeration process.

Remarks

This function thunks down to the appropriate native message base function.

FmaDeleteMsg

This function deletes message.

FMAAPI_(BOOL) FmaDeleteMsg(HAREA harea, MSGN msgn);

Parameters

harea

Handle to an open area.

msgn

Specifies number of the message to delete.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

This function will fail if the message to be deleted is open.

This function thunks down to the appropriate native message base function.

FmaSetCurMsg

This function sets the current message for the area.

FMAAPI_(BOOL) FmaSetCurMsg(HAREA harea, MSGN msgn);

Parameters

harea

Handle to an open area.

msgn

Specifies number of the new current message.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

This function will fail if the message with specified number does not exist,

This function thunks down to the appropriate native message base function.

FmaGetCurMsg

This function returns the current message number for the area.

FMAAPI_(MSGN) FmaGetCurMsg(HAREA harea);

Parameters

harea

Handle to an open area.

Return values

If the function succeeds, the return value is number of the current message.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

The current message is automatically updated when opening messages in the area.

This function thunks down to the appropriate native message base function.

FmaGetFirstMsg

This function returns number of the first message in the area.

FMAAPI_(MSGN) FmaGetFirstMsg(HAREA harea);

Parameters

harea

Handle to an open area.

Return values

If the function succeeds, the return value is number of the first message in the area.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

If area contains no messages, this function returns zero.

This function thunks down to the appropriate native message base function.

FmaGetHighMsg

This function returns number of the first message in the area.

FMAAPI_(MSGN) FmaGetHighMsg(HAREA harea);

Parameters

harea

Handle to an open area.

Return values

If the function succeeds, the return value is number of the high message in the area.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

If area contains no messages, this function returns zero.

This function thunks down to the appropriate native message base function.

FmaGetMsgCount

This function returns number of messages in the area.

FMAAPI_(LONG) FmaGetMsgCount(HAREA harea);

Parameters

harea

Handle to an open area.

Return values

If the function succeeds, the return value is number of messages in the area.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

If area contains no messages, this function returns zero.

This function thunks down to the appropriate native message base function.

FmaMsgnToUid

This function converts message number to unique message id.

FMAAPI_(UMSG) FmaMsgnToUid(HAREA harea, MSGN msgn);

Parameters

harea

Handle to an open area.

msgn

Number of the message to get the unique id for.

Return values

If the function succeeds, the return value is unique message id.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

This function thunks down to the appropriate native message base function.

FmaUidToMsgn

This function converts unique message id to the message number.

FMAAPI_(MSGN) FmaUidToMsgn(HAREA harea, UMSG umsg, UINT fMode);

Parameters

harea

Handle to an open area.

umsg

Unique message id to get the message number for.

fMode

Specifies the conversion mode. This parameter can be any combination of the following flags:

UMSG_EXACT	Return exact message number provided the message with the given unique id exists.
UMSG_NEXT	Return next message number provided it exists, and exact message does not exist or UMSG_EXACT is not specified.
UMSG_PREV	Return previous message number provided it exists, and exact message does not exist or UMSG_EXACT is not specified, and next message does not exist or UMSG_NEXT is not specified.

Return values

If the function succeeds, the return value is message number.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

This function thunks down to the appropriate native message base function.

FmaOpenMsg

This function opens a message.

FMAAPI_(HMSG) FmaOpenMsg(HAREA harea, UINT mode, MSGN msgn, ULONG fl);

Parameters

harea

Handle to an open area.

mode

Specifies the open message mode. This parameter can be one of the following:

OPENMSG_CREATE	Create new message or truncate existing message and open it for reading and writing.
OPENMSG_READ	Open existing message for reading
OPENMSG_WRITE	Open existing message for writing
OPENMSG_READWRITE	Open existing message for reading and writing

msgn

Specifies number of the message to open. This parameter can be null if creating a new message in which case the message number assigned to the new message will be one more than the current highest message number in the area. It can also be one of the special message number values:

MSGN_CUR	Open current message, fail if it does not exist
MSGN_PREV	Open previous message, fail if it does not exist
MSGN_NEXT	Open next message, fail if it does not exist
MSGN_CURORPREV	Open current or previous if current message does not exist
MSGN_CURORNEXT	Open current or next if current message does not exist

Specifies open message flags. This parameter can be any combination of the following:

FOM_KEEPUMSG

Keep unique message id in Squish message header. Applies to Squish only. For compatibility with SQDEV200, Fidonet Message Access zeroes smh.umsg when passing Squish message header to caller. Specifying this flag if you want to receive this umsg,

Return values

If the function succeeds, the return value is handle of the open message.

If the function fails, the return value is NULL. To get error code, call FmaGetLastError.

Remarks

This function update current message number for the area.

The opened message has to be closed with a call to FmaCloseMsg when no longer needed.

This function thunks down to the appropriate native message base function.

FmaLoadMsg

This function loads a message.

FMAAPI_(BOOL) FmaLoadMsg(HMSG hmsg, PFMM * ppfmm, ULONG fl);

Parameters

hmsg

Handle to an open message.

ppfmm

Pointer to PFMM variable that receives the loaded Fidonet Mail Message object pointer.

Specifies the load message flags. This parameter can be any combination of the following flags:

FLM_NOTEXT

Don’t load message text. Note that if this flag is specified, the end of message kludges will not be loaded.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

The loaded Fidonet Mail Message object has to be destroyed with a call to FmaDestroyFmm when no longer needed.

The message must be opened in OPENMSG_CREATE, OPENMSG_READ or OPENMSG_READWRITE mode for this call to succeed.

This function thunks down to the appropriate native message base function.

FmaSaveMsg

This function saves a message.

FMAAPI_(BOOL) FmaSaveMsg(HMSG hmsg, PFMM pfmm, ULONG fl, ULONG cchTextTotal);

Parameters

hmsg

Handle to an open message.

pfmm

Pointer to the Fidonet Mail Message object to be saved.

Specifies the save message flags. This parameter can be any combination of the following flags:

FSM_NOTEXT	Don't save message text. Note that if this flag is specified, the end of message kludges will not be saved.
FSM_FORCEINTL	Always add ^aINTL kludge. If this flags is not specified, the ^aINTL kludge will be added only if the originating or destination zones are different.
FSM_AUTODOMAIN	Add ^aDOMAIN if domains are specified in both message origination and destination addresses.
FSM_AUTOMSGID	Add automatic ^aMSGID kludge
FSM_AUTOPID	Add automatic ^aPID kludge

cchTextTotal

Specifies total message text length. This parameter can be –1 in which case it will be calculated automatically.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

The message must be opened in OPENMSG_CREATE, OPENMSG_WRITE or OPENMSG_READWRITE mode for this call to succeed.

This function thunks down to the appropriate native message base function.

FmaReadMsg

This function reads the message.

FMAAPI_(BOOL) FmaReadMsg(HMSG hmsg, PVOID pmsgh,

PVOID * ppchCtrl, ULONG * pcchCtrl,

PCH * ppchText, ULONG * pcchText, ULONG * poffText);

Parameters

hmsg

Handle to an open message.

pmsgh

Pointer to the buffer that receives message header. Size and format of this buffer is specific to the message base. This parameter could be NULL in which case the message header is not read.

ppchCtrl

Points to a variable that specifies pointer to the message control info. If this parameter is NULL, the message control info is not read.

pcchCtrl

Points to a variable that specifies length of the message control info. If ppchCtrl is NULL, this parameter can also be NULL.

ppchText

Points to a variable that specifies pointer to the message text buffer. If this parameter is NULL, the message text is not read.

pcchText

Points to a variable that specifies length of the message text buffer. If ppchText is NULL, this parameter can also be NULL.

poffText

Points to a variable that specifies the offset of the message text to read. When the function returns, this variable holds the offset just past the returned message text. The offset is specified relative to beginning of the message text. If this parameter is NULL, the text is read from its very beginning.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

The message must be opened in OPENMSG_CREATE, OPENMSG_READ or OPENMSG_READWRITE mode for this call to succeed.

If *pcchCtrl is set to FRM_GETCTRLCOPY, this function allocates memory block to hold the message control info and sets its address into *ppchCtrl. The size of the message control info is set into *pcchCtrl. This buffer has to be freed by caller with a call to FamMemFree when no longer needed.

If *pcchCtrl is set to FRM_GETCTRLPTR, this function sets *ppchCtrl to the address of the private message control info buffer. Since this buffer is maintained internally, it’s not allowed to be modified, freed or reallocated. The size of the message control info is set into *pcchCtrl.

If *pcchCtrl is set to anything but FRM_GETCTRLPTR or FRM_GETCTRLCOPY, it is interpreted as pointer to the caller’s buffer of the size *pcchCtrl and up to *pcchCtrl bytes of message control info area copied into this buffer.

Format of the message control info depends on the message base type:

· For Fts and Pkt bases message control info is a null-terminated string of kludges each starting with 0x01 character and ending with \r.

· For Squish bases message control info is a null-terminated string of kludges each starting with 0x01 character.

· For JAM bases message control info is an array of variable length JAM sub-field structures.

If *ppchText is set to NULL, this function allocates message text buffer of the size specified by *pcchText and copies its address into *ppchText. The *pcchText specifies the size of the buffer to allocate. If *pcchText is set to FRM_GETALLTEXT, the allocated buffer is large enough to hold entire message text with trailing null and its size is copied into *pcchText upon function return. This buffer has to be freed by caller with a call to FamMemFree when no longer needed.

If *ppchText is not NULL, it is interpreted as the address of the caller’s buffer of the size *pcchText so this function copies as much of the message text as possible into this buffer and sets *pcchText to number of characters copied into the buffer.

This function thunks down to the appropriate native message base function.

FmaWriteMsg

This function writes the message.

FMAAPI_(BOOL) FmaWriteMsg(HMSG hmsg, PVOID pmsgh,

PVOID pchCtrl, ULONG cchCtrl,

PCH pchText, ULONG cchText, ULONG * poffText,

ULONG cchTextTotal);

Parameters

hmsg

Handle to an open message.

pmsgh

Pointer to the buffer containing the message header. Size and format of this buffer is specific to the message base. This parameter could be NULL in which case the message header is not written. This parameter must to be specified on the first call to this function when creating a new message.

pchCtrl

Points to the message control info to write. If this parameter is NULL, the message control info is not written. This parameter must to be specified on the first call to this function when creating a new message.

cchCtrl

Specifies message control info length.

pchText

Points to the message text. If this parameter is NULL, the message text is not written.

cchText

Specifies size message text to write.

poffText

Points to a variable that specifies the offset of the message text to write. When the function returns, this variable holds the offset just past the message text written. The offset is specified relative to beginning of the message text. If this parameter is NULL, the text is written from its very beginning.

cchTextTotal

Specifies total message text length. This parameter must to be specified on the first call to this function even if the message text is not written during this call. Any subsequent calls to this function may omit this parameter.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

The message must be opened in OPENMSG_CREATE, OPENMSG_WRITE or OPENMSG_READWRITE mode for this call to succeed.

Format of the message control info depends on the message base type:

· For Fts and Pkt bases message control info is a null-terminated string of kludges each starting with 0x01 character and ending with \r.

· For Squish bases message control info is a null-terminated string of kludges each starting with 0x01 character.

· For JAM bases message control info is an array of variable length JAM sub-field structures.

This function thunks down to the appropriate native message base function.

FmaGetMsgCtrlLen

This function returns size of the message control info.

FMAAPI_(BOOL) FmaGetMsgCtrlLen(HMSG hmsg, ULONG * pcchCtrl);

Parameters

hmsg

Handle to an open message.

pcchCtrl

Pointer to the variable that receives size of the message control info.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

The message must be opened in OPENMSG_CREATE, OPENMSG_READ or OPENMSG_READWRITE mode for this call to succeed.

This function thunks down to the appropriate native message base function.

FmaGetMsgTextLen

This function returns message text length

FMAAPI_(BOOL) FmaGetMsgTextLen(HMSG hmsg, ULONG * pcchText);

Parameters

hmsg

Handle to an open message.

pcchText

Pointer to the variable that receives size of the message text.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

The message must be opened in OPENMSG_CREATE, OPENMSG_READ or OPENMSG_READWRITE mode for this call to succeed.

For Fts and Squish message bases size of the end of message kludges is included in the returned value since they are physically part of the message text. For JAM messages end of message kludges are not part of the message text.

This function thunks down to the appropriate native message base function.

FmaGetLRInfo

This function gets last read information for the specified user.

FMAAPI_(BOOL) FmaGetLRInfo(HAREA harea, ULONG uid, PLRINFO plri);

Parameters

harea

Handle to an open area.

uid

User id to get the last read information for.

plri

Pointer to the structure that receives last read information. This parameter can be NULL in which case this function just checks for the existence of the last read information for this user id.

Format of the last read information structure is as following:

typedef struct _LRINFO { /* lri */

UMSG umsgLast; // Last read message uid

UMSG umsgHigh; // Highest read message uid

} LRINFO, FAR * PLRINFO;

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

The standard specifications of last read information for Fts and Squish message bases do not allow storing of the high read message number. Fidonet Message Access toolkit extends this specifications in a compatible manner by storing last and high read message numbers in the consecutive entries of the standard last read file format and using even user ids. This mode is enabled only if the area has been opened with FOA_HIGHREAD flag.

This function thunks down to the appropriate native message base function.

FmaSetLRInfo

This function sets last read information for the specified user..

FMAAPI_(BOOL) FmaSetLRInfo(HAREA harea, ULONG uid, PLRINFO plri,

PSZ pszUserName);

Parameters

harea

Handle to an open area.

uid

User id to set the last read information for.

plri

Pointer to the structure that receives last read information. This parameter can be NULL in which case this function just checks for the existence of the last read information for this user id.

Format of the last read information structure is as following:

typedef struct _LRINFO { /* lri */

UMSG umsgLast; // Last read message uid

UMSG umsgHigh; // Highest read message uid

} LRINFO, FAR * PLRINFO;

pszUserName

Points to a null-terminated string that specifies the user name. Required only for the JAM message bases.

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

This function thunks down to the appropriate native message base function.

FmaInitialize

This function initializes the Fidonet Message Access toolkit.

FMAAPI_(BOOL) FmaInitialize(PFMAINIT pfmaInit);

Parameters

pfmaInit

Pointer to the initialization structure or NULL. Following is initialization structure format:

typedef struct _FMAINIT { /* fmaInit */

PVOID (FMAAPI * pfnMemAlloc)(size_t cb, BOOL bZero);

PVOID (FMAAPI * pfnMemRealloc)(PVOID p, size_t cb);

VOID (FMAAPI * pfnMemFree)(PVOID p);

} FMAINIT, FAR * PFMAINIT;

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

Any application must call this function before calling any of the Fidonet Message Access toolkit functions.

By providing initialization structure application can specify custom memory allocation routines.

FmaTerminate

This function terminates Fidonet Message Access toolkit.

FMAAPI_(BOOL) FmaTerminate(VOID);

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

No Fidonet Message Access toolkit routines can be called after calling this function until ths toolkit is initialized again with a call to FmaInitialize.

FmaRegisterApi

This function registers the message base API.

FMAAPI_(BOOL) FmaRegisterApi(UINT type, PAPI (FMAAPI * pfnGetApi)(VOID));

Parameters

type

Specifies the type of the message base API to register. Following message base types area supported by the current version of Fidonet Message Access toolkit:

MBTYPE_FTS	FTS-001 message base, also known as *.MSG base
MBTYPE_SQU	Squish message base
MBTYPE_JAM	JAM message base

pfnGetApi

Pointer to the message base specific function that returns the API set with the following prototype:

FMAAPI_(PAPI) GetApi(VOID)

Return values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get error code, call FmaGetLastError.

Remarks

Registering message base API is required only if application uses abstraction level functions. The application typically registers all the necessary message base API’s during initialization with the code similar this:

if (!FmaRegisterApi(MBTYPE_FTS, FtsGetApi) ||

!FmaRegisterApi(MBTYPE_SQU, SquGetApi) ||

!FmaRegisterApi(MBTYPE_JAM, JamGetApi)) {

// Handle error

}

FmaGetVersion

This function returns the Fidonet Message Access toolkit version info.

FMAAPI_(BOOL) FmaGetVersion(PFMAVER pfmaVer);

Parameters

pfmaVer

Pointer to the Fidonet Message Access version info structure of the following format:

typedef struct _FMAVER { /* fmaVer */

UINT verMajor; // Major version number

UINT verMinor; // Minor version number

UINT verBuild; // Build number

CHAR achName[64]; // Build name

} FMAVER, FAR * PFMAVER;

Return values

The return value is always TRUE.

Remarks

Use this function to determine version and build numbers of the Fidonet Message Access toolkit at runtime.

FmaGetLastError

This function gets the last error code.

FMAAPI_(UINT) FmaGetLastError(VOID)

Return values

The return value is the last error code. Following is the list of error codes:

FMAERROR_NONE	No error
FMAERROR_INTERNAL_ERROR	Internal error occurred.
FMAERROR_NOT_SUPPORTED	Requested feature or item is not currently supported.
FMAERROR_INVALID_PARAM	Invalid parameter passed to the function.
FMAERROR_INVALID_DATA	Invalid data detected. This could be result of corrupted message base or invalid information passed by the caller.
FMAERROR_INVALID_SIZE	Invalid data size detected. This could be result of corrupted message base or invalid information passed by the caller.
FMAERROR_NOT_ENOUGH_MEMORY	There is not enough memory for the requested operation.
FMAERROR_NOT_FOUND	Request item not found. This could be message base, message with the specified number, etc.
FMAERROR_ALREADY_EXISTS	Request item already exists.
FMAERROR_STILL_OPEN	Messages or areas are still open when closing area or the entire API respectively.
FMAERROR_CANNOT_CREATE	Failed to create request item. This could be message base, message, etc.
FMAERROR_CANNOT_OPEN	Failed to open item. This could be message base, message, file.
FMAERROR_CANNOT_SEEK	Seek failed. This error usually relates to file operations and indicates severe file related problem.
FMAERROR_CANNOT_READ	Read failed. This error usually relates to file operations and indicates severe file related problem.
FMAERROR_CANNOT_WRITE	Write failed. This error usually relates to file operations and indicates severe file related problem.
FMAERROR_CANNOT_DELETE	Delete failed. This could be message, file, property, etc.
FMAERROR_CANNOT_LOCK	Lock failed. The file or message base may be in use by other process.
FMAERROR_CANNOT_UNLOCK	Unlock failed. This error usually relates to file operations and indicates severe file related problem.
FMAERROR_NO_DISK_SPACE	Disk full when writing message or file.
FMAERROR_NOT_LOCKED	Attempt to unlock message base or file which is not locked.
FMAERROR_NOT_EXCLUSIVE	Attempt to leave exclusive mode when it is not currently in effect.
FMAERROR_NOT_CACHING	Attempt to stop caching mode when it is not currently in effect.
FMAERROR_FRAME_IN_USE	Attempt to read frame that is currently updated by another process.
FMAERROR_INVALID_FRAME	Invalid message frame detected. This error is usually result of corrupted message base.
FMAERROR_INVALID_INDEX	Invalid index entry detected. This error is usually result of corrupted message base index file.
FMAERROR_ACCESS_DENIED	File or message base is in use by other process.
FMAERROR_MISSING_FILES	Missing some of the message base files.
FMAERROR_INVALID_ADDRESS	Detected incorrectly formatted network address.
FMAERROR_INVALID_KLUDGE	Detected incorrectly formatted message kludge.
FMAERROR_INVALID_USERID	Detected incorrectly specified user id. This error is a result of un-even user id specification when an area is opened in FOA_HIGHREAD flag.
FMAERROR_NOT_REGISTERED	Item is not registered. This could be message base api, etc.
FMAERROR_DATA_SIZE_LIMIT	Item is too large to process. This could be message contol info, message text, etc in 16-bit builds of the toolkit.

Remarks

The last error is set only if the function returned error condition and is not always reset if function call succeeds. This means that error codes set by the previous function calls may persist across successful function calls.

Last error code information is maintained on per tread basis in multithreaded builds of the Fidonet Message Access toolkit.

FmaSetLastError

This function sets the last error code.

FMAAPI_(UINT) FmaSetLastError(UINT code);

Parameters

code

Specifies the error code to set.

Return values

The return value is the error code set.

Remarks

Applications can set their own error codes provided these codes do not clash with the predefined error codes. Use FMAERROR_CUSTOM_ERRORS_BASE as the base of user error codes to ensure compatibility with the future versions.

Fts functions

Following table lists native Fts message base functions are similar to their Fma counterparts. In fact, those Fma counterparts thunk down to these functions to carry out the job. There are quite a few additional Fts functions specific to Fts message bases not described in the document, so please check FtsApiP.h header for more information.

FMAAPI_(HAREA) FtsOpenArea(PSZ pszPath, UINT fOpenMode, ULONG fl,

NETADDR * pnetAddr);

FMAAPI_(BOOL) FtsCloseArea(HAREA harea);

FMAAPI_(BOOL) FtsLockArea(HAREA harea, BOOL bLock);

FMAAPI_(BOOL) FtsValidateMsg(HAREA harea, MSGN msgn, PULONG pimsg);

FMAAPI_(BOOL) FtsCreateMsgMap(HAREA harea, UMSG * paumsg[], PULONG pcumsg);

FMAAPI_(BOOL) FtsEnumMsgs(HAREA harea, PFNENUMMSGS pfnCallback,

PVOID pvCallbackData, ULONG fl);

FMAAPI_(BOOL) FtsDeleteMsg(HAREA harea, MSGN msgn);

FMAAPI_(BOOL) FtsSetCurMsg(HAREA harea, MSGN msgn);

FMAAPI_(MSGN) FtsGetCurMsg(HAREA harea);

FMAAPI_(MSGN) FtsGetFirstMsg(HAREA harea);

FMAAPI_(MSGN) FtsGetHighMsg(HAREA harea);

FMAAPI_(LONG) FtsGetMsgCount(HAREA harea);

FMAAPI_(UMSG) FtsMsgnToUid(HAREA harea, MSGN msgn);

FMAAPI_(MSGN) FtsUidToMsgn(HAREA harea, UMSG umsg, UINT fMode);

FMAAPI_(HMSG) FtsOpenMsg(HAREA harea, UINT mode, MSGN msgn, ULONG fl);

FMAAPI_(BOOL) FtsCloseMsg(HMSG hmsg);

FMAAPI_(BOOL) FtsLoadMsg(HMSG hmsg, PFMM * ppfmm, ULONG fl);

FMAAPI_(BOOL) FtsSaveMsg(HMSG hmsg, PFMM pfmm, ULONG fl,

ULONG cchTextTotal);

FMAAPI_(BOOL) FtsReadMsg(HMSG hmsg, PFMH pfmh,

PCH * ppchCtrl, ULONG * pcchCtrl,

PCH * ppchText, ULONG * pcchText, ULONG * poffText);

FMAAPI_(BOOL) FtsWriteMsg(HMSG hmsg, PFMH pfmh, PCH pchCtrl, ULONG cchCtrl,

PCH pchText, ULONG cchText, ULONG * poffText,

ULONG cchTextTotal);

FMAAPI_(BOOL) FtsGetMsgCtrlLen(HMSG hmsg, ULONG * pcchCtrl);

FMAAPI_(BOOL) FtsGetMsgTextLen(HMSG hmsg, ULONG * pcchText);

FMAAPI_(BOOL) FtsGetLRInfo(HAREA harea, ULONG uid, PLRINFO plri);

FMAAPI_(BOOL) FtsSetLRInfo(HAREA harea, ULONG uid, PLRINFO plri,

PSZ pszUserName);

Pkt functions

Following table lists native Pkt message base functions are similar to their Fma counterparts. In fact, those Fma counterparts thunk down to these functions to carry out the job. There are quite a few additional Pkt functions specific to Pkt message bases not described in the document, so please check PktApiP.h header for more information.

FMAAPI_(HAREA) PktOpenArea(PSZ pszPath, UINT fOpenMode, ULONG fl,

NETADDR * pnetAddr);

FMAAPI_(BOOL) PktCloseArea(HAREA harea);

FMAAPI_(BOOL) PktLockArea(HAREA harea, BOOL bLock);

FMAAPI_(BOOL) PktValidateMsg(HAREA harea, MSGN msgn, PULONG pimsg);

FMAAPI_(BOOL) PktCreateMsgMap(HAREA harea, UMSG * paumsg[], PULONG pcumsg);

FMAAPI_(BOOL) PktEnumMsgs(HAREA harea, PFNENUMMSGS pfnCallback,

PVOID pvCallbackData, ULONG fl);

FMAAPI_(BOOL) PktDeleteMsg(HAREA harea, MSGN msgn);

FMAAPI_(BOOL) PktSetCurMsg(HAREA harea, MSGN msgn);

FMAAPI_(MSGN) PktGetCurMsg(HAREA harea);

FMAAPI_(MSGN) PktGetFirstMsg(HAREA harea);

FMAAPI_(MSGN) PktGetHighMsg(HAREA harea);

FMAAPI_(LONG) PktGetMsgCount(HAREA harea);

FMAAPI_(UMSG) PktMsgnToUid(HAREA harea, MSGN msgn);

FMAAPI_(MSGN) PktUidToMsgn(HAREA harea, UMSG umsg, UINT fMode);

FMAAPI_(HMSG) PktOpenMsg(HAREA harea, UINT mode, MSGN msgn, ULONG fl);

FMAAPI_(BOOL) PktCloseMsg(HMSG hmsg);

FMAAPI_(BOOL) PktLoadMsg(HMSG hmsg, PFMM * ppfmm, ULONG fl);

FMAAPI_(BOOL) PktSaveMsg(HMSG hmsg, PFMM pfmm, ULONG fl, ULONG cchTextTotal);

FMAAPI_(BOOL) PktReadMsg(HMSG hmsg, PFMH pfmh,

PCH * ppchCtrl, ULONG * pcchCtrl,

PCH * ppchText, ULONG * pcchText, ULONG * poffText);

FMAAPI_(BOOL) PktWriteMsg(HMSG hmsg, PFMH pfmh,

PCH pchCtrl, ULONG cchCtrl,

PCH pchText, ULONG cchText, ULONG * poffText,

ULONG cchTextTotal);

FMAAPI_(BOOL) PktGetMsgCtrlLen(HMSG hmsg, ULONG * pcchCtrl);

FMAAPI_(BOOL) PktGetMsgTextLen(HMSG hmsg, ULONG * pcchText);

FMAAPI_(BOOL) PktGetLRInfo(HAREA harea, ULONG uid, PLRINFO plri);

FMAAPI_(BOOL) PktSetLRInfo(HAREA harea, ULONG uid, PLRINFO plri,

PSZ pszUserName);

Squ functions

Following table lists native Squish message base functions are similar to their Fma counterparts. In fact, those Fma counterparts thunk down to these functions to carry out the job. There are quite a few additional Squ functions specific to Squishmessage bases not described in the document, so please check SquApiP.h header for more information.

FMAAPI_(HAREA) SquOpenArea(PSZ pszPath, UINT fOpenMode, ULONG fl,

NETADDR * pnetAddr);

FMAAPI_(BOOL) SquCloseArea(HAREA harea);

FMAAPI_(BOOL) SquLockArea(HAREA harea, BOOL bLock);

FMAAPI_(BOOL) SquValidateMsg(HAREA harea, MSGN msgn, PULONG pimsg);

FMAAPI_(BOOL) SquCreateMsgMap(HAREA harea, UMSG * paumsg[], PULONG pcumsg);

FMAAPI_(BOOL) SquEnumMsgs(HAREA harea, PFNENUMMSGS pfnCallback,

PVOID pvCallbackData, ULONG fl);

FMAAPI_(BOOL) SquDeleteMsg(HAREA harea, MSGN msgn);

FMAAPI_(BOOL) SquSetCurMsg(HAREA harea, MSGN msgn);

FMAAPI_(MSGN) SquGetCurMsg(HAREA harea);

FMAAPI_(MSGN) SquGetFirstMsg(HAREA harea);

FMAAPI_(MSGN) SquGetHighMsg(HAREA harea);

FMAAPI_(LONG) SquGetMsgCount(HAREA harea);

FMAAPI_(UMSG) SquMsgnToUid(HAREA harea, MSGN msgn);

FMAAPI_(MSGN) SquUidToMsgn(HAREA harea, UMSG umsg, UINT fMode);

FMAAPI_(HMSG) SquOpenMsg(HAREA harea, UINT mode, MSGN msgn, ULONG fl);

FMAAPI_(BOOL) SquCloseMsg(HMSG hmsg);

FMAAPI_(BOOL) SquLoadMsg(HMSG hmsg, PFMM * ppfmm, ULONG fl);

FMAAPI_(BOOL) SquSaveMsg(HMSG hmsg, PFMM pfmm, ULONG fl, ULONG cchTextTotal);

FMAAPI_(BOOL) SquReadMsg(HMSG hmsg, PSMH psmh,

PCH * ppchCtrl, ULONG * pcchCtrl,

PCH * ppchText, ULONG * pcchText, ULONG * poffText);

FMAAPI_(BOOL) SquWriteMsg(HMSG hmsg, PSMH psmh, PCH pchCtrl, ULONG cchCtrl,

PCH pchText, ULONG cchText, ULONG * poffText,

ULONG cchTextTotal);

FMAAPI_(BOOL) SquGetMsgCtrlLen(HMSG hmsg, ULONG * pcchCtrl);

FMAAPI_(BOOL) SquGetMsgTextLen(HMSG hmsg, ULONG * pcchText);

FMAAPI_(BOOL) SquGetLRInfo(HAREA harea, ULONG uid, PLRINFO plri);

FMAAPI_(BOOL) SquSetLRInfo(HAREA harea, ULONG uid, PLRINFO plri,

PSZ pszUserName);

Jam functions

Following table lists native JAM message base functions are similar to their Fma counterparts. In fact, those Fma counterparts thunk down to these functions to carry out the job. There are quite a few additional Jam functions specific to JAM message bases not described in the document, so please check JamApiP.h header for more information.

FMAAPI_(HAREA) JamOpenArea(PSZ pszPath, UINT fOpenMode, ULONG fl,

NETADDR * pnetAddr);

FMAAPI_(BOOL) JamCloseArea(HAREA harea);

FMAAPI_(BOOL) JamLockArea(HAREA harea, BOOL bLock);

FMAAPI_(BOOL) JamValidateMsg(HAREA harea, MSGN msgn, PULONG pimsg);

FMAAPI_(BOOL) JamCreateMsgMap(HAREA parea, UMSG * paumsg[], PULONG pcumsg);

FMAAPI_(BOOL) JamEnumMsgs(HAREA harea, PFNENUMMSGS pfnCallback,

PVOID pvCallbackData, ULONG fl);

FMAAPI_(BOOL) JamDeleteMsg(HAREA harea, MSGN msgn);

FMAAPI_(BOOL) JamSetCurMsg(HAREA harea, MSGN msgn);

FMAAPI_(MSGN) JamGetCurMsg(HAREA harea);

FMAAPI_(MSGN) JamGetFirstMsg(HAREA harea);

FMAAPI_(MSGN) JamGetHighMsg(HAREA harea);

FMAAPI_(LONG) JamGetMsgCount(HAREA harea);

FMAAPI_(UMSG) JamMsgnToUid(HAREA harea, MSGN msgn);

FMAAPI_(MSGN) JamUidToMsgn(HAREA harea, UMSG umsg, UINT fMode);

FMAAPI_(HMSG) JamOpenMsg(HAREA harea, UINT mode, MSGN msgn, ULONG fl);

FMAAPI_(BOOL) JamCloseMsg(HMSG hmsg);

FMAAPI_(BOOL) JamLoadMsg(HMSG hmsg, PFMM * ppfmm, ULONG fl);

FMAAPI_(BOOL) JamSaveMsg(HMSG hmsg, PFMM pfmm, ULONG fl, ULONG cchTextTotal);

FMAAPI_(BOOL) JamReadMsg(HMSG hmsg, PJMH pjmh, PJSF * ppjsf, ULONG * pcbjsf,

PCH * ppchText, ULONG * pcchText, ULONG * poffText);

FMAAPI_(BOOL) JamWriteMsg(HMSG hmsg, PJMH pjmh, PJSF pjsf, ULONG cbjsf,

PCH pchText, ULONG cchText, ULONG * poffText,

ULONG cchTextTotal);

FMAAPI_(BOOL) JamGetMsgCtrlLen(HMSG hmsg, ULONG * pcbjsf);

FMAAPI_(BOOL) JamGetMsgTextLen(HMSG hmsg, ULONG * pcchText);

FMAAPI_(BOOL) JamGetLRInfo(HAREA harea, ULONG uid, PLRINFO plri);

FMAAPI_(BOOL) JamSetLRInfo(HAREA harea, ULONG uid, PLRINFO plri,

PSZ pszUserName);

Programming considerations

This section contains information you may find useful while coding your applications.

Header files structure

The following table shows the Fidonet Mail Access header structure:

Header	Description	When to include
FmaApi.h	Main header file	In any app which uses FMA
FmaApiP.h	Private header for FMA code	When you need FMA private declarations
FmaDef.h	Definition header file	When you need FMA types declaration only
FmaSys.h	System dependant declarations	When you need FMA system functions
FmaUti.h	Miscellaneous utility declarations	When you need FMA utility functions
FmaCtrl.h	Message control info routines header	When parsing message control info on your own
FtsApi.h	Public Fts message base api	When accessing Fts base with native api level
FtsApiP.h	Private Fts message base api	When accessing Fts base at low level
PktApi.h	Public Pkt message base api	When accessing Pkt base with native api level
PktApiP.h	Private Pkt message base api	When accessing Pkt base at low level
SquApi.h	Public Squish message base api	When accessing Squish base with native api level
SquApiP.h	Private Squish message base api	When accessing Squish base at low level
JamApi.h	Public JAM message base api	When accessing JAM base with native api level
JamApiP.h	Private JAM message base api	When accessing JAM base at low level

Reading messages

TBD: provide info on typical applications and known caveats…

Talk about various ways to retrieve control info etc.

Creating messages

TBD: provide info on typical applications and known caveats…

Talk about msgn=0 and msgn!= regarding creating new message or creating exising message.

Updating messages

TBD: provide info on typical applications and known caveats…

Talk about message frame size issues.

Deleting messages

TBD: provide info on typical applications and known caveats…

Talk about the problem of enumerating messages using msgn's and deleting some of them. The correct way to do this is to call FmaCreateMsgMap, loop through it's entries converting calling FmaUmsgToMsgn, etc.

Message base sharing

TBD: discuss message base sharing issues…

Multithread applications

TBD: discuss multithreading applications issues…

Building FMA libraries

This section contains information you may find useful while building Fidonet Message Access libraries.

TBD:

License

This software is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

See file GNU_GPL.TXT for details.

Credits

Distribution

Latest FMA version is available at:

freq: FMA 2:5020/6@fidonet
http://www.kvitek.com/fido

If you have questions or comments, please contact:

mail: pete@kvitek.com
Fido: Pete Kvitek@2:5020/6