PC Online 1997 December

home *** CD-ROM | disk | FTP | other *** search

/ PC Online 1997 December / PCO1297.ISO / FilesBBS / DOS / INF121X.EXE / dev.doc < prev next >

Wrap

Text File | 1996-11-02 | 27.5 KB | 721 lines

______ ___________________ ______ > |____________| InfoMail/386 1.20 |____________| < ~~||~~| Centurion |~~~~~~~~~~~~~~~~~~~| 2:2502/666 |~~||~~ || ~~~~~~~~~~~~ ~~~~~~~~~~~~ || || || || || || || || CENTURION || || || || || || -*- || || || || || || InfoMail/386 1.20 || || || || A Document Server for Fidonet Systems || || || || Copyright (C) Damian Walker 1996 || || || || || || -*- || || || || || || DEVELOPER'S GUIDE || || || || || || _____ || || (____() || || / / || || / / || || (____() || || _______ || || (_)|||(_) || || ||||| || || ||||| || || ||||| || || ||||| || || ||||| || || ||||| || || ||||| || || /~~~~~\ || || ~~~~~~~ || || || || || || || || || || ____________ ____________ || __||__| Copyright |___________________| 1996 |__||__ > |~~~~~~~~~~~~| (C) Damian Walker |~~~~~~~~~~~~| < ~~~~~~ ~~~~~~~~~~~~~~~~~~~ ~~~~~~ 1. INTRODUCTION The developer's guide has been written with other software authors in mind; it is primarily designed for people who want to write programs to interface with InfoMail/386 1.20. It is laid out in the form of a reference guide, with a section for the configuration file, and a section for the document list files. Information relevant to users can be found in the User and Reference Guides (USER.DOC and REF.DOC), a full table of contents for this and the other manuals is in the file CONTENTS.DOC, and a full index is given as the file INDEX.DOC. Introduction D- 2 2. THE CONFIGURATION FILE There is only one file for the general configuration, this being INFOMAIL.CFG. The file's general format is as follows: ┌───────┬───────────────────────────────┬───────┬───────┬──────┐ │HEADER │CONFIGURATION │AKA REC│AKA REC│... │ └───────┴───────────────────────────────┴───────┴───────┴──────┘ The header is available for verification of the file. It is advisable that the header be read and verified before progressing to read the rest of the file; if the header is invalid then the rest of the file is likely to contain nonsense. The header section is 8 bytes long, and contains the following characters: ┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐ │ I │ N │ F │ 1 │ 2 │ 0 │ S │ <NUL> │ │ 73 │ 78 │ 70 │ 49 │ 50 │ 48 │ 83 │ 0 │ │ 49h │ 4Eh │ 46h │ 31h │ 32h │ 30h │ 53h │ 00h │ └───────┴───────┴───────┴───────┴───────┴───────┴───────┴───────┘ The configuration section has the following structure, presented here as a language-independent table: The Configuration File D- 3 ┌──────────────────────────────────────────────────────────────┐ │MAIN CONFIGURATION TABLE │ ├───────┬───────┬──────────────────────────────────────────────┤ │NETMAIL│char/64│netmail directory │ │LOGFILE│char/64│path and name of log file │ │FLAGS │int/2 │various flags: │ │ │ │bit 0 active │ │ │ │bit 1 kill inbound requests │ │ │ │bit 2 kill inbound updates │ │ │ │bit 3 kill inbound searches │ │ │ │bit 4 kill outbound responses │ │REQUEST│char/36│user name for requests │ │UPDATE │char/36│user name for updates │ │SEARCH │char/36│user name for searches │ │HEADER │char/64│path and name of global header │ │FOOTER │char/64│path and name of global footer │ │DOCLIST│char/64│path and name of doc list template │ │NOFILE │char/64│file name of file error template │ │INACTIV│char/64│file name of 'inactive' template │ │ACCEPT │char/64│name of update accepted template │ │REJECT │char/64│name of 'rejected' template │ │RESULTS│char/64│name of search results template │ │SPLIT │int/2 │maximum message size │ ├───────┴───────┴──────────────────────────────────────────────┤ │AKA RECORD │ ├───────┬───────┬──────────────────────────────────────────────┤ │ZONE │int/2 │fidonet zone │ │NET │int/2 │net number │ │NODE │int/2 │node number │ │POINT │int/2 │point address │ └───────┴───────┴──────────────────────────────────────────────┘ The characters before each '/' refer to the type, and the number after it refers to the size in bytes. Thus int/2 is a 2-byte integer, and char/64 is a 64-byte character string. Since InfoMail was written in C, all the character variables (i.e. all the char/36s and char/64s) are null terminated. All the int/2s are in low-byte/high-byte form, as is the normal Intel practice. These fields are all verified at the time they are entered in the configuration editor. This means that if you are planning to write to the configuration file yourself, you need to make sure that you make the same checks as InfoMail itself. These checks are described in the following sections. 2.1. The NETMAIL field This field is a 64-character ASCIIZ string, containing the netmail directory. InfoMail requires that there is a terminating backslash on this field, unless it is a simple drive letter (in which case the colon is required). Failure to add this backslash to the NETMAIL field means that InfoMail will fail to find netmail messages, possibly causing an error: The Configuration File D- 4 ! No netmails to read InfoMail itself converts the name to upper case, and converts any Unix-style slashes (/) entered by the user into DOS backslashes (\). InfoMail will run happily with either slash in the netmail field, and will also accept pathnames in upper or lower case, but if the NETMAIL field contains lower case letters or a Unix slash, this will be altered next time the user edits the NETMAIL field in the configuration editor. Thus it may be aesthetically more pleasing to format the names as InfoMail does, before writing them. 2.2. The LOGFILE field As mentioned in the user guide, this field is mandatory. A full valid path and filename must be written to this field. If a valid DOS filename is not present, InfoMail will refuse to run. Filename formatting is as per the netmail field. InfoMail converts Unix slashes to DOS backslashes and converts the filename to upper case when the field is edited in the configuration editor, but it will run with lower case filenames and Unix slashes. 2.3. The FLAGS field This is a compound binary field, containing five flags and room for eleven more. The eleven unused flags may currently be used by third-party utilities, but as InfoMail gets updated and expanded some of these may be used by the program itself. It is recommended that third-party utilities implementing their own flags in the INFOMAIL.CFG file restrict themselves to using bits 12 to 15 of the FLAGS field. Bear in mind however, that use of your utility at a user's installation may preclude the use of another utility which uses the same flag field, so unless there is very little data to be stored by your utility, it is recommended that you maintain your own configuration file for any values it may need over and above those already used by InfoMail. Bit 0 of this field is the active flag. Setting it to 1 (the normal value) indicates that the installation is active. Bit 1 of this field is the Kill Inbound Requests flag, 2 indicates 'Yes' and 0 indicates 'No'. Bit 2 of this field is the Kill Inbound Updates flag, 4 meaning 'Yes' and 0 meaning 'No'. Bit 3 of this field is the Kill Inbound Searches flag, 8 meaning 'Yes' and 0 meaning 'No'. The Configuration File D- 5 Bit 4 of this field is the Kill Outbound Responses flag, 16 meaning 'Yes' and 0 meaning 'No'. Since these are binary 2-state fields, and all combinations are valid, no validation is required before writing their value. See the reference guide for further details about their effect upon InfoMail's behaviour. 2.4. The REQUEST field This is a simple ASCIIZ character string showing the name which, when found in the 'To:' field of a message, tells InfoMail that the message is a document request. No validation is necessary, other than checks for string length and zero termination in languages which do not use fixed length/zero terminated strings. InfoMail checks for this name in inbound messages before checking for the update and search names (see next 2 sections), so document requests are not affected by having identical values in the REQUEST field and the UPDATE (and/or SEARCH) fields. 2.5. The UPDATE field This is a simple ASCIIZ character string showing the name which, when found in the 'To:' field of a message, tells InfoMail that the message is a document update. Apart from checks for string length and zero termination, it may be useful to verify that the value of this field is not identical to that of the REQUEST field. Identical values in these fields would not cause problems when running InfoMail, other than preventing document updates from being made. 2.6. The SEARCH field This is a simple ASCIIZ character string showing the name which, when found in the 'To:' field of a message, tells InfoMail that the message is a document search request. Apart from checks for string length and zero termination, it may be useful to verify that the value of this field is not identical to that of the REQUEST or UKDATE fields. Identical values in these fields would not cause problems when running InfoMail, other than preventing document searches from being requested. 2.7. The HEADER field This is a simple ASCIIZ string containing a filename. The formatting of this filename are as for the LOGFILE field. If the filename is invalid, InfoMail includes no header in outgoing messages. The Configuration File D- 6 2.8. The FOOTER field This is a simple ASCIIZ string containing a filename. The formatting of this filename is as for the LOGFILE field. If the filename is invalid, InfoMail includes no footer in outgoing messages. 2.9. The DOCLIST field This is a simple ASCIIZ string containing a filename. The formatting of this filename is as for the LOGFILE field. If the filename is invalid, the standard format is used for document lists. 2.10. The NOFILE field This is a simple ASCIIZ string containing a filename. The formatting of this filename is as for the LOGFILE field. If the filename is invalid, the standard format is used for file errors. 2.11. The INACTIV field This is a simple ASCIIZ string containing a filename. The formatting of this filename is as for the LOGFILE field. If the filename is invalid, the standard format is used for document inactive errors. 2.12. The ACCEPT field This is a simple ASCIIZ string containing a filename. The formatting of this filename is as for the LOGFILE field. If the filename is invalid, the standard format is used for update accepted responses. 2.13. The REJECT field This is a simple ASCIIZ string containing a filename. The formatting of this filename is as for the LOGFILE field. If the filename is invalid, the standard format is used for reject messages. 2.14. The RESULTS field This is a simple ASCIIZ string containing a filename. The formatting of this filename is as for the LOGFILE field. If the filename is invalid, the standard format is used for search results. 2.15. The SPLIT field This is a standard, unsigned 2-byte integer. All possible values of this field are valid, so no checking is necessary. The Configuration File D- 7 2.16. The AKA LIST records InfoMail does not limit the number of these records which can be added to the end of a configuration file, so the number which might exist is limited only by disk space. It does not check for duplicate values on loading these records, so if duplicate addresses are created this will have a slight impact on InfoMail's running speed. It is best to check for duplicate values in your own program, especially when adding addresses yourself which may already be present. The list is not sorted in any way, so checks for addresses must consist of a complete search of all addresses present. InfoMail does not record the number of addresses present, so the file size must be recorded or an EOF check made to ensure you don't read past the end of the file. All integers are 2-byte signed values, as per the normal Fidonet standard. All addresses are full 4D-addresses, with a point value of zero for full node addresses. The Configuration File D- 8 3. THE DOCUMENT LIST FILES There are two files used to store the document list, INFOMAIL.DAT and INFOMAIL.NDX. INFOMAIL.DAT is the main data file, and INFOMAIL.NDX is the index file. The files have the following overall format: ┌───────┬───────────────┬───────────────┬──────┐ INFOMAIL.DAT │HEADER │DOCUMENT │DOCUMENT │... │ └───────┴───────────────┴───────────────┴──────┘ ┌───────┬───────────────┬───────────────┬──────┐ INFOMAIL.NDX │HEADER │INDEX RECORD │INDEX RECORD │... │ └───────┴───────────────┴───────────────┴──────┘ The header of both files is used to verify their validity, in case of corruption or copying of other files over the valid document list. The HEADER section for INFOMAIL.DAT contains the following characters: ┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐ │ I │ N │ F │ 1 │ 2 │ 0 │ D │ <NUL> │ │ 73 │ 78 │ 70 │ 49 │ 50 │ 48 │ 68 │ 0 │ │ 49h │ 4Eh │ 46h │ 31h │ 32h │ 30h │ 44h │ 00h │ └───────┴───────┴───────┴───────┴───────┴───────┴───────┴───────┘ and the header section of INFOMAIL.NDX contains the following: ┌───────┬───────┬───────┬───────┬───────┬───────┬───────┬───────┐ │ I │ N │ F │ 1 │ 2 │ 0 │ X │ <NUL> │ │ 73 │ 78 │ 70 │ 49 │ 50 │ 48 │ 88 │ 0 │ │ 49h │ 4Eh │ 46h │ 31h │ 32h │ 30h │ 58h │ 00h │ └───────┴───────┴───────┴───────┴───────┴───────┴───────┴───────┘ If any other sequence of characters forms the first eight bytes of either file, it is recommended that you close the files immediately and terminate the program (or run it without the use of these files, where possible). Invalid values in these headers mean that the format of the files may be invalid and may confuse your program. The format of a document record in the file INFOMAIL.DAT is represented in language-independent form in the following table: The Document List Files D- 9 ┌───────┬───────┬──────────────────────────────────────────────┐ │DELETED│int/2 │deleted flag │ │DOCNAME│char/18│document name/tag │ │FLAGS │int/2 │general document flags │ │ │ │bit 0 macros │ │ │ │bit 1 listed │ │ │ │bit 2 smart routing (unused in this version) │ │ │ │bit 3 active │ │SUBJECT│int/72 │subject line │ │ATTR │int/2 │attributes for outgoing messages │ │REQUEST│char/9 │request password │ │UPDATE │char/9 │update password │ │FILE │char/64│primary document text file │ │SECFILE│char/64│secondary document text file │ │COUNTER│int/2 │document access counter │ └───────┴───────┴──────────────────────────────────────────────┘ The format of the index file INFOMAIL.NDX is as follows: ┌───────┬───────┬──────────────────────────────────────────────┐ │DOCNAME│char/18│document name │ │FILEPOS│int/4 │record position in list file │ └───────┴───────┴──────────────────────────────────────────────┘ As with the configuration file, the type description is 'type/size', size being in bytes, and all char values are null-terminated ASCIIZ strings, and all verifications of these fields are made while in the document list editor, so developers writing to these files will have to perform the appropriate verifications themselves, according to the information in the following subsections. 3.1. The DELETED field This field indicates that the document record has been marked as deleted. Currently any value in this field other than zero is taken as 'deleted'. In normal usage, this field should never be set when InfoMail is not running. The document list editor sets this field to 1 when records are deleted by the user, and removes all such records when the user leaves the editor. Also, the field is briefly used by the netmail scan to mark records NOT matching search criteria during a document search; after the search results are sent to the user, all records are marked as undeleted (i.e. a 0 is stored in this field). Other third-party utilities may make use of the field in a similar fashion, as long as all records are marked as NOT deleted (i.e. DELETED = 0) before InfoMail could possibly be run. The Document List Files D-10 3.2. The DOCNAME field This field, in both the index file and the document list file, contains the document name. Taking InfoMail as it stands, the name in the document list file itself seems superfluous, but it may be that third-party utilities create indexes on other fields for their own use, and thus the document name would be required in the main file. Although this field is 18 characters, allowing 17-character document names, no document name should exceed 16 characters (plus the terminating NULL). The reason for the extra character in the file is that the DJGPP compiler word-aligns fields. 3.3. The FLAGS field This field contains various Yes/No type information about each individual document. Developers implementing their own document flags in this field should restrict themselves to using bits 12 to 15, as InfoMail may make use of flags 4 to 11 in future releases. Bit 0 is the Macros flag, a value of 1 meaning 'Yes' and a value of 0 meaning 'No'. Bit 1 is the Listed flag, a value of 2 meaning 'Yes' and a value of 0 meaning 'No'. Bit 2 is the Smart Routing flag, which is currently unused. This flag should be left alone by third-party programs, as it may be used in future, even for the current release of InfoMail (by a secondary add-on program). Bit 3 is the Active flag, a value of 8 meaning 'Yes' and a value of 0 meaning 'No'. See the reference guide for more information about the effect of these flags on the behaviour of the InfoMail program. 3.4. The SUBJECT field This is a simple ASCIIZ string containing the subject line for outgoing messages. It is a freeform text field. Although it is 72 characters long, only 64 characters should be used (creating a maximum subject length of 63 characters). Longer subject lines will cause InfoMail to crash. 3.5. The ATTR field This is the attributes field which will be stamped on outgoing primary messages for this document. Refer to the document FTS-1 for details on the exact meaning of these flags. Although the Pvt and Local flags do not appear in the document editor, they will always be set in the document list file. The Document List Files D-11 If your program modifies the values of attributes not directly supported by the document list editor, InfoMail will not change these. It is therefore recommended that you leave the Pvt and Local flags set. 3.6. The REQUEST field This is a request password, and is a freeform ASCIIZ string. InfoMail does not do any case conversion of this value in the file, even though the password comparison is case insensitive. 3.7. The UPDATE field This is an update password, and is a freeform ASCIIZ string. InfoMail does not do any case conversion of this value in the file, even though the password comparison is case insensitive. 3.8. The FILE field This filename field is an ASCIIZ string, its contents following normal DOS filename conventions. Exact details of formatting are as for the LOGFILE field in the configuration file, see section 2.2 for these. 3.9. The SECFILE field The SECFILE field has the same format and behaviour as the FILE field described in section 3.8. 3.10. The COUNTER field This is a 2-byte integer, unsigned. All possible values are valid, so no checking is necessary. 3.11. Details of the Index File The index file is sorted in alphabetical/ASCII order, although the sorting is case insensitive, i.e. the records Acorn, apple, Banana would appear in that order. The FILEPOS field is a signed integer pointing to the position in INFOMAIL.DAT where a particular document lies, that document being identified in the index file by document name (DOCNAME). The DOCNAME field in each file should match exactly. The first byte of the file is position 0. If a third-party application leaves the index in a mess (unsorted, or sorted in a case-sensitive order), then InfoMail will exhibit strange behaviour, often failing to find documents which are present. If this problem occurs during development, you should load the document list editor and quit it immediately (since the final document pack in the editor re-indexes the file). The INFOMAIL.DAT file is completely unsorted. The Document List Files D-12