{: Pascal (Delphi/ Kylix) Interface unit for the smapi. Documentation comments are taken from sqdev.prn, which is part of Scott Dudley's SQDEV200.zip archive. } {: NOTE: Unfortunately it turned out that the structures that are passed between smapi and any calling programs are in no way align controlled, that is, how they are aligned is left to the compiler. That means that if you are not using the same compiler for your program that was used to compile the libraries, chances are that you will have an alignment problem resulting in fields of the structures being out of sync, e.g. you are reading something totally different from what the library put there. Because of this and because I don't want to chase a moving target like this, I will stop maintaining smapi.pas and fidoconf.pas. That probably means that husky has now become a project that can only be used by C programmers, unless somebody else wants to go through the trouble. One possible solution I can think of, would be having an interface layer that converts the randomly aligned structures to other structures that are fixed. I might do it, maybe, if I don't find anything else to waste my time on. But this is rather unlikely, because it has to be done in C and that is definitely not my favourite programming language. Please leave this comment in here, so nobody else will waste time trying to figure out why the data his programs reads is wrong. 2001-07-22 twm } unit smapi; interface type // this assumes that a word is 2 bytes and a longword is 4 bytes, true // for Delphi 5 and Kylix. sword = word; dword = longword; PPChar = ^PChar; PLongint = ^Longint; const MSGAREA_NORMAL = $00; // read/write MSGAREA_CREATE = $01; // create MSGAREA_CRIFNEC = $02; // create if necessary MSGTYPE_SDM = $01; // *.MSG MSGTYPE_SQUISH = $02; // squish MSGTYPE_JAM = $08; // jam MSGTYPE_ECHO = $80; MSGTYPE_NOTH = $0100; // ?? MSGNUM_CUR: longint = -1; MSGNUM_PREV: longint = -2; MSGNUM_NEXT: longint = -3; MSGNUM_current: longint = -1; MSGNUM_previous: longint = -2; MOPEN_CREATE = 0; MOPEN_READ = 1; MOPEN_WRITE = 2; MOPEN_RW = 3; MSGAPI_VERSION = 1; SMAPI_VERSION = '1.5.65.65.65.65.6'; MSGPRIVATE = $00001; MSGCRASH = $00002; MSGREAD = $00004; MSGSENT = $00008; MSGFILE = $00010; MSGFWD = $00020; // also called intransit flag MSGORPHAN = $00040; MSGKILL = $00080; MSGLOCAL = $00100; MSGHOLD = $00200; MSGXX2 = $00400; MSGFRQ = $00800; MSGRRQ = $01000; MSGCPT = $02000; MSGARQ = $04000; MSGURQ = $08000; MSGSCANNED = $10000; MSGLOCKED: dword = $40000000; // seems to be a feature of GoldEd XMSG_NAME_SIZE = 36; XMSG_FROM_SIZE = XMSG_NAME_SIZE; XMSG_TO_SIZE = XMSG_NAME_SIZE; XMSG_SUBJ_SIZE = 72; MAX_REPLY = 9; FTS0001_DATE_SIZE = 20; XMSG_SIZE = ((94 + XMSG_FROM_SIZE) + XMSG_TO_SIZE) + XMSG_SUBJ_SIZE; MSGAPI_ID: dword = $0201414D; MSGH_ID = $0302484D; UID_EXACT = $00; UID_NEXT = $01; UID_PREV = $02; // error constants MERR_NONE = 0; // No error MERR_BADH = 1; // Invalid handle passed to function MERR_BADF = 2; // Invalid or corrupted file MERR_NOMEM = 3; // Not enough memory for specified operation MERR_NODS = 4; // Maybe not enough disk space for operation MERR_NOENT = 5; // File/message does not exist MERR_BADA = 6; // Bad argument passed to msgapi function MERR_EOPEN = 7; // Couldn't close - messages still open BROWSE_ACUR = $0001; BROWSE_ATAG = $0002; BROWSE_AALL = $0004; BROWSE_ALL = $0008; BROWSE_NEW = $0010; BROWSE_SEARCH = $0020; BROWSE_FROM = $0040; BROWSE_READ = $0100; BROWSE_LIST = $0200; BROWSE_QWK = $0400; BROWSE_GETTXT = $0800; BROWSE_EXACT = $1000; BROWSE_HASH = $2000; BROWSE_AREA = (BROWSE_ACUR or BROWSE_ATAG) or BROWSE_AALL; BROWSE_TYPE = ((BROWSE_ALL or BROWSE_NEW) or BROWSE_SEARCH) or BROWSE_FROM; BROWSE_DISPLAY = (BROWSE_READ or BROWSE_LIST) or BROWSE_QWK; SF_HAS_ATTR = $01; SF_NOT_ATTR = $02; SF_OR = $04; SF_AND = $08; WHERE_TO = $01; WHERE_FROM = $02; WHERE_SUBJ = $04; WHERE_BODY = $08; WHERE_ALL = ((WHERE_TO or WHERE_FROM) or WHERE_SUBJ) or WHERE_BODY; SCAN_BLOCK_SDM = 48; SCAN_BLOCK_SQUISH = 512; type PAreaHandle = ^TAreaHandle; PMsgHandle = ^TMsgHandle; PXMSG = ^TXMSG; PNETADDR = ^TNETADDR; PSEARCH = ^TSEARCH; PBROWSE = ^TBROWSE; TUMsgId = dword; { Timestamp } TStamp = packed record // This was true for the original Squish MsgAPI, but smapi is double word aligned // case Boolean of // True: (Date, Time: sword); // False: (Value: dword); Date, Filler1, Time, Filler2: sword; // Date, Time: dword; end; PMINF = ^TMINF; TMINF = packed record req_version: sword; def_zone: sword; haveshare: sword; // necessary for Versions >= 1 always set to NIL palloc: pointer; pfree: pointer; repalloc: pointer; farpalloc: pointer; farpfree: pointer; farrepalloc: pointer; end; TNetAddr = packed record zone: sword; net: sword; node: sword; point: sword; end; TMsgName = packed array[0..XMSG_NAME_SIZE - 1] of char; TMsgSubj = packed array[0..XMSG_SUBJ_SIZE - 1] of Char; // TMsgSubjStr = string[XMSG_SUBJ_SIZE]; TXMSG = packed record attr: dword; from: TMsgName; _to: TMsgName; subj: TMsgSubj; orig: TNetAddr; dest: TNetAddr; date_written: TStamp; date_arrived: TStamp; utc_ofs: sword; filler1: sword; // dword align replyto: TUMsgId; Replies: array[0..MAX_REPLY - 1] of TUMsgId; filler2: sword; // dword align FtscData: array[0..FTS0001_DATE_SIZE - 1] of Char; end; TApiFuncs = packed record CloseArea: function(mh: PAreaHandle): sword; cdecl; OpenMsg: function(mh: PAreaHandle; mode: sword; n: dword): PMsgHandle; cdecl; CloseMsg: function(msgh: PMsgHandle): sword; cdecl; ReadMsg: function(msgh: PMsgHandle; msg: PXMSG; ofs: dword; bytes: dword; text: PChar; cbyt: dword; ctxt: PChar): dword; cdecl; WriteMsg: function(msgh: PMsgHandle; append: sword; msg: PXMSG; text: PChar; textlen: dword; totlen: dword; clen: dword; ctxt: PChar): sword; cdecl; KillMsg: function(mh: PAreaHandle; msgnum: dword): sword; cdecl; Lock: function(mh: PAreaHandle): sword; cdecl; UnLock: function(mh: PAreaHandle): sword; cdecl; SetCurPos: function(msgh: PMsgHandle; pos: dword): sword; cdecl; GetCurPos: function(msgh: PMsgHandle): dword; cdecl; MsgnToUid: function(mh: PAreaHandle; msgnum: dword): TUMsgId; cdecl; UidToMsgn: function(mh: PAreaHandle; UMsgId: TUMsgId; _type: sword): dword; cdecl; GetHighWater: function(mh: PAreaHandle): dword; cdecl; SetHighWater: function(mh: PAreaHandle; hwm: dword): sword; cdecl; GetTextLen: function(msgh: PMsgHandle): dword; cdecl; GetCtrlLen: function(msgh: PMsgHandle): dword; cdecl; end; PApiFuncs = ^TApiFuncs; TMSGAPI = packed record id: dword; len: sword; _type: sword; num_msg: dword; cur_msg: dword; high_msg: dword; high_water: dword; sz_xmsg: sword; locked: byte; isecho: byte; api: PApiFuncs; apidata: pointer; // Pointer to application-specific data. // API_SQ.C and API_SDM.C use this for // different things, so again, no applications // should muck with anything in here. end; TAreaHandle = TMSGAPI; TMsgHandle = packed record sq: PAreaHandle; id: dword; bytes_written: dword; cur_pos: dword; end; TSEARCH = packed record next: PSEARCH; attr: longint; flag: longint; txt: Pchar; where: char; end; TBROWSE = packed record path: Pchar; _type: sword; bflag: sword; bdata: dword; first: PSEARCH; nonstop: Pchar; msgn: dword; sq: PAreaHandle; m: PMsgHandle; msg: TXMSG; matched: sword; Begin_Ptr: function(b: pBROWSE): longint; cdecl; Status_Ptr: function(b: pBROWSE; aname: pchar; colour: longint): longint; Idle_Ptr: function(b: pBROWSE): longint; Display_Ptr: function(b: pBROWSE): longint; After_Ptr: function(b: pBROWSE): longint; End_Ptr: function(b: pBROWSE): longint; Match_Ptr: function(b: pBROWSE): longint; end; //Var // msgapierr: sword; cvar; external; // mi: minf; cvar; external; {: Helper function. Since Delphi/Kylix does not support external variables, this function has been introduced. It reads the smapi error variable msgapierr and returns its value } function MsgGetMsgApiErr: sword; cdecl; {: Closes a message area. This function performs all clean-up actions necessary, such as closing files, changing directories, and so on. The MsgCloseArea function should be called for each area opened by MsgOpenArea. @param AreaHandle is an HAREA handle returnded by MsgOpenArea. @returns 0 if the area was successfully closed, otherwise it returns -1 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. } function MsgCloseArea(_AreaHandle: PAreaHandle): sword; cdecl; {: Opens a message for access, and it must be used to read from or write to a given message. @param AreaHandle is a message area handle, as returned by the MsgOpenArea function. @param 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. @param MsgNum 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.) @returns a HMSG handle ff the message was successfully opened. 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 } function MsgOpenMsg(_AreaHandle: PAreaHandle; _Mode: sword; _MsgNum: dword): PMsgHandle; cdecl; {: Closes a message which has been previously opened by MsgOpenMsg. All messages should be closed after use, or else data loss may result. @params MsgHandle is the message handle that was returned by MsgOpenMsg. @returns 0, if the message was successfully closed, otherwise, -1 is returned, and msgapierr is set to: MERR_BADH } function MsgCloseMsg(_MsgHandle: PMsgHandle): sword; cdecl; {: Reads 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. @param MsgHandle 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. @param XMsg is a pointer to an TXMSG (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 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. @param Offset 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. @param BodyLen represents the maximum number of bytes to read from the message. Fewer bytes may be read, but the API will read no more than BodyLen during this call. (See BodyLen, 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. @param Body 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 Offset, up to a maximum of BodyLen bytes. If the application does not wish to read the message body, this argument should be set to NULL. @param ControlLen represents the maximum number of bytes of control information to read from the message. @param Control is a pointer to a block of memory, into which the API will place the message control information. No more than ControlLne 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(): "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)+ A 'group' consists of a and a control item. 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 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 followed by a single . Although the control items are free-form, the following format is suggested: 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 . 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: CHARSET: LATIN1REALNAME: Mark Twain The trailing byte must be included in the read count given by 'cbyt'. @returns 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 } function MsgReadMsg(_MsgHandle: PMsgHandle; _XMsg: PXMSG; _Offset: dword; _BodyLen: dword; _Body: PChar; _ControlLen: dword; _Control: PChar): integer; cdecl; {: Writes the message header, body, and control information to a message. @param MsgHandle 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. @param Append 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. @param XMsg is a pointer to an XMSG structure. If this pointer is 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 XMsg. THIS PARAMETER MUST BE PASSED THE **FIRST** TIME THAT MSGWRITEMSG() IS USED WITH A JUST-OPENED MESSAGE HANDLE! @param Body 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. @param Bodylen 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. @param Total indicates the total length of the message to be written. This differs from Bodylen in that the message may be written a piece at a time (using small Bodylen values), but the total length of the message will not exceed Total. This parameter can be somewhat restrictive for the application; however, this value is required for optimal use of some message base types. The Total 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 Total, and the length of Body in Bodylen. Second and subsequent passes should set Append to 1, with the length of Body in Bodylen. 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 in 'totlen' which is greater than the original length of the message. @param ControlLen 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. @param Control 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. @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 } function MsgWriteMsg(_MsgHandle: PMsgHandle; _Append: sword; _XMsg: PXMSG; _Body: PChar; _Bodylen: dword; _Total: dword; _ControlLen: dword; _Control: PChar): sword; cdecl; {: Deletes a message from the specified message area. @param AreaHandle is a message area handle, as returned by MsgOpenArea. @param MsgNum specifies the message number to kill. It is an error to kill a message which is currently open. @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 MERR_BADF MERR_NOMEM } function MsgKillMsg(_AreaHandle: PAreaHandle; _MsgNum: dword): sword; cdecl; function MsgLock(mh: PAreaHandle): sword; cdecl; function MsgUnLock(mh: PAreaHandle): sword; cdecl; {: Sets the 'current position' in a message handle. This position is used by MsgReadMsg to read text from the message body. @param MsgHandle is a message handle, as returned by MsgOpenMsg. @param Pos is the number of bytes into the message from which MsgReadMsg should start reading. @returns 0 on success, or -1 on error and sets msgapierr to: MERR_BADH } function MsgSetCurPos(_MsgHandle: PMsgHandle; _Pos: dword): sword; cdecl; {: Retrieves the 'current position' of a message handle. This position is where the MsgReadMsg would read text from the message body next. @param MsgHandle 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 } function MsgGetCurPos(_MsgHandle: PMsgHandle): dword; cdecl; {: 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. @param AreaHandle is the message area handle, as returned by MsgOpenArea. @param MsgNum is the message number to convert. @returns a UMSGID on success; otherwise, it returns 0 and sets msgapierr to: MERR_BADH MERR_BADF MERR_NOENT } function MsgMsgnToUid(_AreaHandle: PAreaHandle; _MsgNum: dword): TUMsgId; cdecl; {: Converts a UMSGID to a message number. @param AreaHandle is the message area handle, as returned by MsgOpenArea. @param UMsgId is the UMSGID, as returned by a prior call to MsgMsgnToUid. @param 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. @returns the requested UMSGID. If no valid message could be found, MsgUidToMsgn returns 0 and sets msgapierr to one of the following: MERR_BADH MERR_NOENT } function MsgUidToMsgn(_AreaHandle: PAreaHandle; _UMsgId: TUMsgId; _Type: sword): dword; cdecl; {: Returns the 'high water marker' for an area. This number represents the highest message number that was processed by a message export or import utility. The high water marker is automatically adjusted when messages are killed. @param AreaHandle is a message area handle, as returned by MsgOpenArea. @returns the high water mark on success, or 0 on error and sets msgapierr to: MERR_BADH } function MsgGetHighWater(_AreaHandle: PAreaHandle): dword; cdecl; {: Sets the 'high water marker' for the current area. @param AreaHandle is a message area handle, as returned by MsgOpenArea. @param HighWater is the new high water marker to use for the specified area. @returns 0 on success, or -1 on error and sets msgapierr to: MERR_BADH } function MsgSetHighWater(_AreaHandle: PAreaHandle; _HighWater: dword): sword; cdecl; {: Retrieves the length of the message body for the specified message. @param MsgHandle is a message handle, as returned by MsgOpenMsg. @returns the length of the body on success. On error, it returns (dword)-1 and sets msgapierr to: MERR_BADHT } function MsgGetTextLen(_MsgHandle: PMsgHandle): dword; cdecl; {: Retrieves the length of the control information for the specified message. @param MsgHandle is a message handle, as returned by MsgOpenMsg. @returns the length of the control information on success. On error, it returns (dword)-1 and sets msgapierr to: MERR_BADH } function MsgGetCtrlLen(_MsgHandle: PMsgHandle): dword; cdecl; {: Initializes 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. @param MInf is a structure contining the following fields: record TMInf // 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); end; '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. 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 realloc() function, except that a far pointer should be accepted and returned. If this field is NULL, MsgAPI will use its own realloc() function. @returns a value of 0 if the initialization was performed successfully, and -1 if a problem was encountered. } function MsgOpenApi(_MInf: PMINF): sword; cdecl; {: Deinitialize theMsgAPI. 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. @returns a value of 0 if the API was successfully deinitialized, and -1 otherwise. } function MsgCloseApi: sword; cdecl; {: Opens or creates a message area. @param Name is the name of the message area to open. The contents of this string are implementation-defined. (See Type for more information.) @param Mode is the mode with which the area should be opened. Values for Mmode 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 fails. @param 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 in DOS) 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. @returns a HAREA handle on success. 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. } function MsgOpenArea(_Name: PChar; _Mode: sword; _Type: sword): PAreaHandle; cdecl; {: The MsgValidate function validates a particular message area, determining whether or not the area exists and if it is valid. @param Type is the type of the message area, using the same constants as specified for MsgOpenArea. @param Name is the name of the message area, using the same format as specified for MsgOpenArea. @returns the value 1 if the area exists and is valid. 0 otherwise. } function MsgValidate(_Type: sword; _Name: PChar): sword; cdecl; {: This function is not part of the original MsgApi and therefore I don't have any clue what it does. } function MsgBrowseArea(b: PBROWSE): sword; cdecl; function MsgCurMsg(_AreaHandle: PAreaHandle): integer; function MsgNumMsg(_AreaHandle: PAreaHandle): integer; function MsgHighMsg(_AreaHandle: PAreaHandle): integer; function MsgGetCurMsg(_AreaHandle: PAreaHandle): integer; function MsgGetNumMsg(_AreaHandle: PAreaHandle): integer; function MsgGetHighMsg(_AreaHandle: PAreaHandle): integer; function InvalidMsgh(msgh: PMsgHandle): sword; cdecl; function InvalidMh(mh: PAreaHandle): sword; cdecl; procedure SquishSetMaxMsg(sq: PAreaHandle; max_msgs: dword; skip_msgs: dword; age: dword); cdecl; function SquishHash(f: PChar): dword; cdecl; function SdmOpenArea(name: PChar; mode: sword; _type: sword): PAreaHandle; cdecl; function SdmValidate(name: PChar): sword; cdecl; function SquishOpenArea(name: PChar; mode: sword; _type: sword): PAreaHandle; cdecl; function SquishValidate(name: PChar): sword; cdecl; function JamOpenArea(name: PChar; mode: sword; _type: sword): PAreaHandle; cdecl; function JamValidate(name: PChar): sword; cdecl; function CvtCtrlToKludge(ctrl: PChar): PChar; cdecl; function GetCtrlToken(where: PChar; what: PChar): PChar; cdecl; function CopyToControlBuf(txt: PChar; newtext: PPChar; length: PLongInt): PChar; cdecl; procedure ConvertControlInfo(ctrl: PChar; orig: PNETADDR; dest: PNETADDR); cdecl; function NumKludges(txt: PChar): sword; cdecl; procedure RemoveFromCtrl(ctrl: PChar; what: PChar); cdecl; function Address(a: PNETADDR): PChar; cdecl; function StripNasties(str: PChar): PChar; cdecl; implementation const LIBSMAPI_NAME = 'libsmapi.so'; function MsgCloseArea(_AreaHandle: PAreaHandle): sword; cdecl; begin MsgCloseArea := _AreaHandle^.api^.CloseArea(_AreaHandle); end; function MsgOpenMsg(_AreaHandle: PAreaHandle; _Mode: sword; _MsgNum: dword): PMsgHandle; cdecl; begin MsgOpenMsg := _AreaHandle^.api^.OpenMsg(_AreaHandle, _Mode, _MsgNum); end; function MsgCloseMsg(_MsgHandle: PMsgHandle): sword; cdecl; begin MsgCloseMsg := _MsgHandle^.sq^.api^.CloseMsg(_MsgHandle); end; function MsgReadMsg(_MsgHandle: PMsgHandle; _XMsg: PXMSG; _Offset: dword; _BodyLen: dword; _Body: PChar; _ControlLen: dword; _Control: PChar): integer; cdecl; begin MsgReadMsg := _MsgHandle^.sq^.api^.ReadMsg(_MsgHandle, _XMsg, _Offset, _BodyLen, _Body, _ControlLen, _Control); end; function MsgWriteMsg(_MsgHandle: PMsgHandle; _Append: sword; _Xmsg: PXMSG; _Body: PChar; _Bodylen: dword; _Total: dword; _ControlLen: dword; _Control: PChar): sword; cdecl; begin MsgWriteMsg := _MsgHandle^.sq^.api^.WriteMsg(_MsgHandle, _Append, _Xmsg, _Body, _Bodylen, _Total, _ControlLen, _Control); end; function MsgKillMsg(_AreaHandle: PAreaHandle; _MsgNum: dword): sword; cdecl; begin MsgKillMsg := _AreaHandle^.api^.KillMsg(_AreaHandle, _MsgNum); end; function MsgLock(mh: PAreaHandle): sword; cdecl; begin MsgLock := mh^.api^.Lock(mh); end; function MsgUnLock(mh: PAreaHandle): sword; cdecl; begin MsgUnLock := mh^.api^.UnLock(mh); end; function MsgSetCurPos(_MsgHandle: PMsgHandle; _Pos: dword): sword; cdecl; begin MsgSetCurPos := _MsgHandle^.sq^.api^.SetCurPos(_MsgHandle, _Pos); end; function MsgGetCurPos(_MsgHandle: PMsgHandle): dword; cdecl; begin MsgGetCurPos := _MsgHandle^.sq^.api^.GetCurPos(_MsgHandle); end; function MsgMsgnToUid(_AreaHandle: PAreaHandle; _MsgNum: dword): TUMsgId; cdecl; begin MsgMsgnToUid := _AreaHandle^.api^.MsgnToUid(_AreaHandle, _MsgNum); end; function MsgUidToMsgn(_AreaHandle: PAreaHandle; _UMsgId: TUMsgId; _Type: sword): dword; cdecl; begin MsgUidToMsgn := _AreaHandle^.api^.UidToMsgn(_AreaHandle, _UMsgId, _Type); end; function MsgGetHighWater(_AreaHandle: PAreaHandle): dword; cdecl; begin MsgGetHighWater := _AreaHandle^.api^.GetHighWater(_AreaHandle); end; function MsgSetHighWater(_AreaHandle: PAreaHandle; _HighWater: dword): sword; cdecl; begin MsgSetHighWater := _AreaHandle^.api^.SetHighWater(_AreaHandle, _HighWater); end; function MsgGetTextLen(_MsgHandle: PMsgHandle): dword; cdecl; begin MsgGetTextLen := _MsgHandle^.sq^.api^.GetTextLen(_MsgHandle); end; function MsgGetCtrlLen(_MsgHandle: PMsgHandle): dword; cdecl; begin MsgGetCtrlLen := _MsgHandle^.sq^.api^.GetCtrlLen(_MsgHandle); end; // Thes functions aren't actually functions, they are just wrappers to // access some fields in the AreaHandle in a controlled way. // in C they are macros. function MsgCurMsg(_AreaHandle: PAreaHandle): integer; begin Result := _AreaHandle^.cur_msg; end; function MsgGetCurMsg(_AreaHandle: PAreaHandle): integer; begin Result := _AreaHandle^.cur_msg; end; function MsgNumMsg(_AreaHandle: PAreaHandle): integer; begin Result := _AreaHandle^.num_msg; end; function MsgGetNumMsg(_AreaHandle: PAreaHandle): integer; begin Result := _AreaHandle^.num_msg; end; function MsgHighMsg(_AreaHandle: PAreaHandle): integer; begin Result := _AreaHandle^.high_msg; end; function MsgGetHighMsg(_AreaHandle: PAreaHandle): integer; begin Result := _AreaHandle^.high_msg; end; function MsgGetMsgApiErr: sword; cdecl; external LIBSMAPI_NAME name 'MsgGetMsgApiErr'; function MsgOpenApi(_MInf: PMINF): sword; cdecl; external LIBSMAPI_NAME name 'MsgOpenApi'; function MsgCloseApi: sword; cdecl; external LIBSMAPI_NAME name 'MsgCloseApi'; function MsgOpenArea(_Name: PChar; _Mode: sword; _Type: sword): PAreaHandle; cdecl; external LIBSMAPI_NAME name 'MsgOpenArea'; function MsgValidate(_Type: sword; _Name: PChar): sword; cdecl; external LIBSMAPI_NAME name 'MsgValidate'; function MsgBrowseArea(b: PBROWSE): sword; cdecl; external LIBSMAPI_NAME name 'MsgBrowseArea'; function InvalidMsgh(msgh: PMsgHandle): sword; cdecl; external LIBSMAPI_NAME name 'InvalidMsgh'; function InvalidMh(mh: PAreaHandle): sword; cdecl; external LIBSMAPI_NAME name 'InvalidMh'; procedure SquishSetMaxMsg(sq: PAreaHandle; max_msgs: dword; skip_msgs: dword; age: dword); cdecl; external LIBSMAPI_NAME name 'SquishSetMaxMsg'; function SquishHash(f: PChar): dword; cdecl; external LIBSMAPI_NAME name 'SquishHash'; function SdmOpenArea(name: PChar; mode: sword; _type: sword): PAreaHandle; cdecl; external LIBSMAPI_NAME name 'SdmOpenArea'; function SdmValidate(name: PChar): sword; cdecl; external LIBSMAPI_NAME name 'SdmValidate'; function SquishOpenArea(name: PChar; mode: sword; _type: sword): PAreaHandle; cdecl; external LIBSMAPI_NAME name 'SquishOpenArea'; function SquishValidate(name: PChar): sword; cdecl; external LIBSMAPI_NAME name 'SquishValidate'; function JamOpenArea(name: PChar; mode: sword; _type: sword): PAreaHandle; cdecl; external LIBSMAPI_NAME name 'JamOpenArea'; function JamValidate(name: PChar): sword; cdecl; external LIBSMAPI_NAME name 'JamValidate'; function CvtCtrlToKludge(ctrl: PChar): PChar; cdecl; external LIBSMAPI_NAME name 'CvtCtrlToKludge'; function GetCtrlToken(where: PChar; what: PChar): PChar; cdecl; external LIBSMAPI_NAME name 'GetCtrlToken'; function CopyToControlBuf(txt: PChar; newtext: PPChar; length: PLongInt): PChar; cdecl; external LIBSMAPI_NAME name 'CopyToControlBuf'; procedure ConvertControlInfo(ctrl: PChar; orig: PNETADDR; dest: PNETADDR); cdecl; external LIBSMAPI_NAME name 'ConvertControlInfo'; function NumKludges(txt: PChar): sword; cdecl; external LIBSMAPI_NAME name 'NumKludges'; procedure RemoveFromCtrl(ctrl: PChar; what: PChar); cdecl; external LIBSMAPI_NAME name 'RemoveFromCtrl'; function Address(a: PNETADDR): PChar; cdecl; external LIBSMAPI_NAME name 'Address'; function StripNasties(str: PChar): PChar; cdecl; external LIBSMAPI_NAME name 'StripNasties'; end.