980218 Thor 2.6 API documentation Copyright © 1994-1998 Ultima Thule Software, All Rights Reserved. Authors: Eivind Nordseth, Kjell Irgens, Petter Nilsen This API documentation package is NOT public domain, but it is freely distributable. In other word it is FreeWare. (Note: Thor is ShareWare.) This means that you can copy this API documentation package and give it to all your friends, upload it to a BBS or include it in a PD-library. The only restrictions are: All the files included in this archive must be in their original form without additions, deletions or modifications of any kind. Thor API documentation may not be distributed for profit. Only a nominal charge may be associated with its distribution. The Thor API documentation is provided "AS IS" without warranty of any kind, and the authors is not responsible for any damage this software may do. (Just in case :-) Do not release any modifications of the code examples included in this package. If you have suggestions for code improvements, please contact the authors. INTRODUCTION ~~~~~~~~~~~~ The Thor API documentation package consists of: o docs/bbsread.doc - Autodoc for V5 of bbsread.library. o include/#? - Include files for V5 of bbsread.library. o parsemsg/#? - Source code of a message parser, which adds messages from ABBS/MBBS to the message database. Will also parse newfiles lists and conference lists. o scriptserv/#? - Source code for a script server. This program is used by the ABBS/MBBS Ncomm scripts to gain knowledge of the different events to do. It has also other features used by this NComm script. o packhippo/?# - Source code for an events packer, which makes upload packets in Hippo format. o common/#? - Some small code stubs which are common for scriptserv and parsemsg. o WatchTHOR/#? - Source code for the WatchTHOR mail notification utility. Some of the source uses utgui.library for displaying progress requesters. The api for utgui.library is not included here. (Since the utgui.library probably will be obsolete in later versions of Thor, the docs for utgui.library is not released.) If you want to compile the soures which uses utgui.library, you must comment out all calls to utgui.library. HOW TO USE ~~~~~~~~~~ We have not included any detailed step by step guide to how to program utilites and modules for Thor. Some general advices: o You should read the source code provided, docs/bbsread.doc and include/libraries/bbsread.h carefully before doing any programming. o If you are to write a module for Thor, you should first make a working message parser. After the parser is up and running, you should set up the event configuration for the events you want to support, and then make a event packer. o If you are uncertain of how to use any of the provided functions, look into the source code examples to see how thay are used there. If you still are uncertain, send us an email and we'll try to answer your questions. If you have any questions regarding the use of the Thor API we are reachable on the Thor support email address: thor@thule.no HISTORY ~~~~~~~ 951105 - Initial release of the API documentation 950524 - THOR 2.3 API documentation, no changes except for the archive name 951020 - THOR 2.4 API documentation, minor header files changes 970825 - THOR 2.5 API documentation, changes: - Length of paths for UnArchive() and Archive() has been doubled to 500 characters. - Forwarded messages will not be purged on pack/purge before the event has been executed and the events purged. MDF_REFERENCED is the private flag added to messages that should not be purged. - API change allows for creating a list of file attachments at pack/purge time, so they can be browsed later for copying, deletion etc. New tag PD_AttachmentList to PackDataFile() added for this purpose. - WBRK_MarkDeleted can be set on a kill, which will really delete a message if it matches a kill. WriteBRMessage() will not write the message to the database if a match with this tag is found. NOTE: This introduces a slight API change in in what WriteBRMessage() returns. If possible, do not rely on this return value if it's anything else but 0, which means failure. -1 is returned on messages that are not added to the database due to a kill match on the above tag. - BRKILL_Description tag added to the kill interface. - UnArchive() will now fail if the archive is 0 bytes. - The temp directory when packing will be created now if it doesn't exist. - Messages with MDF_DELETED flag set can still be read, unless the MDF_UNRECOVERABLE flag is set. - New public function SortMessageArray() added. - Replaced the internal function for sorting lists with a new one based on the mergesort algoritm, which is a lot faster. - Subject sorting will also make sure the messages are sorted on date, so the oldest messages comes first. - 2 new tags added, UBRM_ClearMarked and UBRM_SetMarked. 980218 - THOR 2.6 API documentation, changes: - Bumped the version to 6. - confdata.cd_ExtraFlags field added with CDXF_ONLYHEADERS as the only flag for now. - confinternal.ci_NumQueued added that will contain the number of queued messages in this conference. - confdata.cd_HighMark added that can contain the high mark for messages or headers collected for this conference. - New message flags: MDF_QUEUED - Message is queued for future collection of the main body and header MDF_EMPTY_BODY - Message consists of only a header and no full body - New tag for ConfigConf(): CC_HighMark - New tags for WriteBRMessage(): BRMSG_MsgSize, BRMSG_SpecialID, BRMSG_ErrorString, BRMSG_TextPartUniqueID, BRMSG_TextPartFilename, WBRMSG_Queued and WBRMSG_EmptyBody. - Many of the tags for WriteBRMessage() can now also be used in UpdateBRMessage(). - New tags for UpdateBRMessage(): UBRM_SetQueued, UBRM_ClearQueued, UBRM_UpdateHeaders and UBRM_UpdateText. - Will search in message-id too as default in SearchBRMessage() - Comments on kills works as they should.