|
|
@@ -0,0 +1,1420 @@
|
|
|
+ JAMLIB
|
|
|
+
|
|
|
+ A JAM subroutine library
|
|
|
+
|
|
|
+ by Björn Stenberg
|
|
|
+
|
|
|
+ modifications by Johan Billing
|
|
|
+
|
|
|
+ version 1.3.2
|
|
|
+
|
|
|
+ 2004-07-10
|
|
|
+
|
|
|
+
|
|
|
+GENERAL
|
|
|
+=======
|
|
|
+
|
|
|
+History
|
|
|
+-------
|
|
|
+JAMLIB 1.0 was originally released by Björn Stenberg 1996-03-06. Since
|
|
|
+the original license did not permit modification of the library,
|
|
|
+Johan Billing contacted Björn Stenberg and asked him to change the
|
|
|
+license. Björn Stenberg agreed to change the license to the GNU Lesser
|
|
|
+General Public License 1999-12-21 (see the accompanying file LICENSE).
|
|
|
+
|
|
|
+ After that, some minor additions and bug fixes were made by Johan
|
|
|
+Billing and JAMLIB 1.1 was released under the new license.
|
|
|
+
|
|
|
+Changes in 1.3.2:
|
|
|
+
|
|
|
+ * Updated the Win32-specific parts of the code to make it compatible with
|
|
|
+ newer versions of MinGW (tested with 3.1.0-1).
|
|
|
+
|
|
|
+Changes in 1.3.1:
|
|
|
+
|
|
|
+ * Backported the following bugfixes and improvements from JAMLIB 1.4.7 while
|
|
|
+ retaining the platform-independence and high portability of the early
|
|
|
+ versions of JAMLIB.
|
|
|
+
|
|
|
+ - JAMLIB now uses calloc() instead of malloc() followed by memset()
|
|
|
+
|
|
|
+ - JAM_OpenMB() and JAM_CreateMB() will set (*NewArea_PPS) to NULL if
|
|
|
+ calloc() failed
|
|
|
+
|
|
|
+ - JAM_CreateMB() no longer attempts indefinitely to lock the newly created
|
|
|
+ messagebase. If the first attempt fails, it will return an error.
|
|
|
+
|
|
|
+ - jam_Lock() now sets Base_PS->Errno under Linux
|
|
|
+
|
|
|
+ - JAM_NewSubPacket() and JAM_PutSubField() would give memory leaks under
|
|
|
+ conditions of low memory conditions. Fixed.
|
|
|
+
|
|
|
+ - JAM_ReadMsgHeader() would give memory leaks on failure. Fixed.
|
|
|
+
|
|
|
+ - Added JAM_DeleteMessage()
|
|
|
+
|
|
|
+ Big thanks to Sir Raorn (and others?) for finding and fixing these bugs!
|
|
|
+
|
|
|
+ * JAM_CreateMB() would never unlock or close the newly created messagebase
|
|
|
+ upon failure. Fixed.
|
|
|
+
|
|
|
+ * Improved handling of ActiveMsgs counter. JAM_AddMessage() now only
|
|
|
+ increases ActiveMsgs if the added message does not have MSG_DELETED set.
|
|
|
+ JAM_ChangeMsgHeader() decreases ActiveMsgs if MSG_DELETED is set and the
|
|
|
+ message wasn't already deleted. JAM_DeleteMessage() now only decreases
|
|
|
+ ActiveMsgs if the message wasn't already deleted.
|
|
|
+
|
|
|
+ * Updated the documentation to reflect the need to free() memory after
|
|
|
+ JAM_CloseMB() and failed calls to JAM_OpenMB() and JAM_CreateMB().
|
|
|
+
|
|
|
+ * Eliminated compiler warnings
|
|
|
+
|
|
|
+Changes in 1.3:
|
|
|
+
|
|
|
+ * JAM_AddMessage() would fail when trying to add an empty message
|
|
|
+ to the messagebase under Linux. Fixed.
|
|
|
+
|
|
|
+Changes in 1.2:
|
|
|
+
|
|
|
+ * Since JAM_GetSubField() is not reentrant and cannot be used in
|
|
|
+ multi-threaded applications, JAM_GetSubField_R() was added as a
|
|
|
+ replacement for cases where a reentrant function is needed.
|
|
|
+
|
|
|
+Changes in 1.1:
|
|
|
+
|
|
|
+ * Added support for Win32 and Linux
|
|
|
+
|
|
|
+ * Added JAM_AddEmptyMessage()
|
|
|
+
|
|
|
+ * Rewrote the Makefiles
|
|
|
+
|
|
|
+ * Rewrote the CRC32 routine
|
|
|
+
|
|
|
+ * Fixed broken JAM_FindUser()
|
|
|
+
|
|
|
+ * Fixed broken JAM_GetSubfield()
|
|
|
+
|
|
|
+ * Changed JAM_OpenMB so that files are opened in binary mode. This is
|
|
|
+ necessary to use JAMLIB under Windows.
|
|
|
+
|
|
|
+ * Improved JAM_ReadMsgHeader() to give the error JAM_NO_MESSAGE if
|
|
|
+ the message no longer exists in the messagebase and JAM_CORRUPT_MSG
|
|
|
+ if the subfields of the message have been corrupted.
|
|
|
+
|
|
|
+ * Improved portability by changing JAMLIB so that it no longer reads
|
|
|
+ and writes stuctures directly using fread() and fwrite().
|
|
|
+
|
|
|
+ * Improved ANSI-C compatibilty by no longer including the non-ANSI
|
|
|
+ header file memory.h and using feof() to check for EOF instead of
|
|
|
+ errno == EPASTEOF.
|
|
|
+
|
|
|
+ * Added an #ifdef so that ushort and ulong are no longer defined in
|
|
|
+ jam.h when compiling under Linux. These are normally already defined
|
|
|
+ in the standard header files.
|
|
|
+
|
|
|
+
|
|
|
+License
|
|
|
+-------
|
|
|
+JAMLIB - A JAM subroutine library
|
|
|
+Copyright (C) 1999 Björn Stenberg
|
|
|
+
|
|
|
+This library is free software; you can redistribute it and/or
|
|
|
+modify it under the terms of the GNU Lesser General Public
|
|
|
+License as published by the Free Software Foundation; either
|
|
|
+version 2.1 of the License, or (at your option) any later version.
|
|
|
+
|
|
|
+This library is distributed in the hope that it will be useful,
|
|
|
+but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
+Lesser General Public License for more details.
|
|
|
+
|
|
|
+You should have received a copy of the GNU Lesser General Public
|
|
|
+License along with this library; if not, write to the Free Software
|
|
|
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
|
+
|
|
|
+
|
|
|
+Description
|
|
|
+-----------
|
|
|
+These are a collection of subroutines that encapsulate much of the
|
|
|
+format-specific and tedious details of the JAM message base format. The
|
|
|
+idea is that application programmers by using these routines can
|
|
|
+concentrate on the more high-level issues of their programs instead of
|
|
|
+worrying about their JAM routines.
|
|
|
+
|
|
|
+ I [Björn Stenberg] wrote these routines primarily because I needed
|
|
|
+them myself. I was trying to implement JAM support in my FrexxLink BBS
|
|
|
+system and was frustrated by the poor level of documentation supplied in
|
|
|
+the JAMAPI archive distributed by the JAM authors. Finally, I dove into
|
|
|
+the JAMAPI source code in a desperate attempt at finding out how to use it.
|
|
|
+To my despair, I discovered that the JAMAPI is targeted at a very low level.
|
|
|
+I would need to implement a lot of JAM-handling code into my own program.
|
|
|
+
|
|
|
+ This library is an attempt to do two things:
|
|
|
+
|
|
|
+ Firstly, provide an, at least sparingly, _documented_ API, allowing
|
|
|
+application programmers to easily implement JAM into their programs.
|
|
|
+
|
|
|
+ Secondly, raise the level of functionality above that of the original
|
|
|
+JAMAPI package, so that the application programmer does not have to learn
|
|
|
+and understand all the internals of the JAM message base format to
|
|
|
+implement support for it.
|
|
|
+
|
|
|
+ I have not succeded completely on any of the two points, of course.
|
|
|
+Documentation can never be too good, and there are still a few things about
|
|
|
+JAM you must know in order to use it. But I think I have made it somewhat
|
|
|
+easier than perhaps was the case before.
|
|
|
+
|
|
|
+
|
|
|
+References
|
|
|
+----------
|
|
|
+If you are extra curious about the JAM message format, I suggest you get
|
|
|
+a hold of an archive called JAMAPI.ARJ. That archive contains a file called
|
|
|
+JAM.DOC which is the file I have used as reference for the development of
|
|
|
+these routines.
|
|
|
+
|
|
|
+
|
|
|
+Credits
|
|
|
+-------
|
|
|
+All original code except for the CRC32 routine was written by Björn
|
|
|
+Stenberg. The CRC32 code was rewritten by Johan Billing for JAMLIB 1.1
|
|
|
+to replace the original CRC32 code whose origin and copyright was unclear.
|
|
|
+The jam.h header file is a compilation of the best from the various header
|
|
|
+files in the JAMAPI package with some of additions by Björn Stenberg as well.
|
|
|
+Additions and modifications by Johan Billing.
|
|
|
+
|
|
|
+ The JAM message base proposal is:
|
|
|
+
|
|
|
+ JAM(mbp) - Copyright 1993 Joaquim Homrighausen, Andrew Milner,
|
|
|
+ Mats Birch, Mats Wallin.
|
|
|
+ ALL RIGHTS RESERVED
|
|
|
+
|
|
|
+
|
|
|
+Contact Information
|
|
|
+-------------------
|
|
|
+For questions about JAMLIB, please contact:
|
|
|
+
|
|
|
+ Johan Billing
|
|
|
+
|
|
|
+ E-mail: [email protected]
|
|
|
+
|
|
|
+ If you wish to contact Björn Stenberg, his current e-mail address (as of
|
|
|
+1999-12-21) is [email protected].
|
|
|
+
|
|
|
+
|
|
|
+THE LIBRARY
|
|
|
+===========
|
|
|
+
|
|
|
+The Source Code
|
|
|
+---------------
|
|
|
+ I made a point of making this library as system independant as I could.
|
|
|
+Only one function needs to be altered when porting this to another system:
|
|
|
+The file locking. ANSI C does not include file locking so there is not much
|
|
|
+I can do about it.
|
|
|
+ The choice of C over C++ is a part of this philosophy aswell. More
|
|
|
+systems have C compilers than C++ compilers, and more people know C than
|
|
|
+C++. Also, converting this library to a C++ class should be fairly simple.
|
|
|
+If you do, send me a copy.
|
|
|
+
|
|
|
+ I use some naming conventions throughout the code and in the examples.
|
|
|
+These are invented by myself as a reaction to the stunningly ugly and
|
|
|
+hard-to-read Hungarian Notation promoted by some people. The rules of my
|
|
|
+notation are simple:
|
|
|
+
|
|
|
+ * All library-global identifiers are prefixed with 'JAM_'. All
|
|
|
+ file-global identifiers are prefixed with 'jam_'. Local identifiers do
|
|
|
+ not have prefixes.
|
|
|
+
|
|
|
+ * All variables have a suffix describing their basic type. Suffixes used
|
|
|
+ in this library are:
|
|
|
+ _I - integer (int Example_I)
|
|
|
+ _C - character (char Example_C)
|
|
|
+ _S - struct (struct Example_S)
|
|
|
+ _P - pointer (void* Example_P)
|
|
|
+ _A - array
|
|
|
+
|
|
|
+ Suffixes are then combined, to show the correct type:
|
|
|
+ _PI - pointer to integer (int* Example_PI)
|
|
|
+ _PC - pointer to char (char* Example_PC)
|
|
|
+ _AC - array of char (char Example_AC[x])
|
|
|
+ _PPS - pointer to pointer to struct (struct** Example_PPS)
|
|
|
+
|
|
|
+ * Functions do not have suffixes
|
|
|
+
|
|
|
+ The whole idea is that it is quicker to read and comprehend a variable
|
|
|
+called 'Text_PC' than one called 'pszText'. We read from left to right, and
|
|
|
+thus the most important information - the name - should be the leftmost
|
|
|
+data in the word. The variable type is additional information and is
|
|
|
+therefore added to the end where it does not disturb the reader.
|
|
|
+
|
|
|
+
|
|
|
+The Functions
|
|
|
+-------------
|
|
|
+ The library is divided into five groups:
|
|
|
+
|
|
|
+ * Message base functions
|
|
|
+ * Message functions
|
|
|
+ * Subfield functions
|
|
|
+ * LastRead functions
|
|
|
+ * Miscellanous functions
|
|
|
+
|
|
|
+
|
|
|
+--------------------------------------------------------------------------
|
|
|
+
|
|
|
+ Message base functions
|
|
|
+ ----------------------
|
|
|
+
|
|
|
+ These functions handle JAM message bases, by opening, locking, scanning
|
|
|
+etc the contents of a message base. These are fairly straight-forward and
|
|
|
+simple routines that you should have little, if any, trouble with.
|
|
|
+
|
|
|
+ A message base is identified by a message base handle, which is obtained
|
|
|
+from either JAM_OpenMB() och JAM_CreateMB(). All functions that read or
|
|
|
+write from the message base take this handle as parameter, to know which
|
|
|
+message base to use.
|
|
|
+
|
|
|
+================================
|
|
|
+JAM_OpenMB - Open a message base
|
|
|
+================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_OpenMB( uchar* Basename_PC, t_JamBase** NewBase_PPS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Opens a message base. Only one message base can be open at a time.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Basename_PC The path and base filename of the message base.
|
|
|
+ "Base filename" means the filename without the
|
|
|
+ JAM-specific extension.
|
|
|
+
|
|
|
+ NewBase_PPS A pointer to a message base handle where the new
|
|
|
+ message base handle will be written. On error you
|
|
|
+ must free() this memory if (*NewBase_PPS) not NULL.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_BAD_PARAM if NewBas_PPS is NULL
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ Result_I = JAM_OpenMB( "c:\\jam\\mybase", &Base_PS );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_OpenMB returned %d.\n", Result_I );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+================================
|
|
|
+JAM_CloseMB - Close message base
|
|
|
+================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_CloseMB( Base_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Unlocks (if locked) and closes the currently open message base.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to close. Note, that you must
|
|
|
+ free() this memory by yourself.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_LOCK_FAILED if the message base could not be unlocked
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ Result_I = JAM_CloseMB( Base_PS );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_CloseMB returned %d.\n", Result_I );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+========================================
|
|
|
+JAM_CreateMB - Create a new message base
|
|
|
+========================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_CreateMB( uchar* Basename_PC,
|
|
|
+ ulong BaseMsg_I,
|
|
|
+ s_JamBase** NewBase_PPS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Creates the necessary files for a new message base and writes a
|
|
|
+ new message base header.
|
|
|
+ If the message base already exists, its contents are destroyed.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Basename_PC The path and base filename of the new message base.
|
|
|
+
|
|
|
+ BaseMsg_I The base message number (first message #) for the
|
|
|
+ new message base. This number is used when
|
|
|
+ calculating new messages' unique message number. It
|
|
|
+ should not be set to 0.
|
|
|
+
|
|
|
+ NewBase_PPS A pointer to a message base handle where the new
|
|
|
+ message base handle will be written. On error you
|
|
|
+ must free() this memory if (*NewBase_PPS) not NULL.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_BAD_PARAM if BaseMsg_I is 0 or NewBase_PPS is NULL
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ Result_I = JAM_CreateMB( "c:\\jam\\mybase", 1, &Base_PS );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_CreateMB returned %d.\n", Result_I );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+====================================
|
|
|
+JAM_RemoveMB - Remove a message base
|
|
|
+====================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_RemoveMB( ErrorBase_PS, uchar* Basename_PC );
|
|
|
+
|
|
|
+Description
|
|
|
+ Deletes all files associated with a message base. No checking is
|
|
|
+ done as to whether the message base is currently open or not.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ ErrorBase_PS The message base in which to store the I/O error,
|
|
|
+ if any. This parameter does *NOT* specify the
|
|
|
+ message to be removed, it is only used for error
|
|
|
+ tracking purposes. If an i/o error occurs when
|
|
|
+ removing the message base files, this message base
|
|
|
+ handler will simply hold the error code.
|
|
|
+
|
|
|
+ Basename_PC The path and base filename of the message base to
|
|
|
+ remove.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_BAD_PARAM if ErrorBase_PS is NULL
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ Result_I = JAM_RemoveMB( Base_PS, "c:\\jam\\mybase" );
|
|
|
+ if ( Result_I ) {
|
|
|
+ printf("JAM_RemoveMB returned %d.\n", Result_I );
|
|
|
+ if ( Result_I == JAM_IO_ERROR )
|
|
|
+ printf( "i/o error %d\n", JAM_Errno( ErrorBase_PS ) );
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+===================================================
|
|
|
+JAM_LockMB - Lock message base for exclusive access
|
|
|
+===================================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_LockMB( t_JamBase* Base_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Locks the currently open message base so that no other programs may
|
|
|
+ modify it. The message base should be locked for only small periods
|
|
|
+ of time, or the performance of tossers and other software may be
|
|
|
+ affected.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to lock
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_LOCK_FAILED if the message base is currently locked by another
|
|
|
+ process
|
|
|
+ JAM_BAD_PARAM if Base_PS is NULL
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ while ( 1 ) {
|
|
|
+ Result_I = JAM_LockMB( Base_PS );
|
|
|
+ if ( Result_I ) {
|
|
|
+
|
|
|
+ if ( Result_I == JAM_LOCK_FAILED )
|
|
|
+ /* base locked by someone else, wait for unlock */
|
|
|
+ sleep( 1 );
|
|
|
+
|
|
|
+ else {
|
|
|
+ /* error */
|
|
|
+ printf("JAM_LockMB returned %d.\n", Result_I );
|
|
|
+ return -1;
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+==================================
|
|
|
+JAM_UnlockMB - Unlock message base
|
|
|
+==================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_UnlockMB( s_JamBase* Base_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Unlocks message base, allowing other programs to modify it.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to unlock
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_BAD_PARAM if Base_PS is NULL
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ Result_I = JAM_UnlockMB( Base_PS );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_UnlockMB returned %d.\n", Result_I );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+===========================================
|
|
|
+JAM_ReadMBHeader - Read message base header
|
|
|
+===========================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_ReadMBHeader( s_JamBase* Base_PS,
|
|
|
+ s_JamBaseHeader* Header_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Reads the message base header from the start of the JAM header
|
|
|
+ file.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ Header_PS A pointer to a base header structure where the base
|
|
|
+ header will be stored.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_BAD_PARAM if Base_PS or Header_PS is NULL
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamBaseHeader BaseHeader_S;
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ Result_I = JAM_ReadMBHeader( Base_PS, &BaseHeader_S );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_ReadMBHeader returned %d.\n", Result_I );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+=============================================
|
|
|
+JAM_WriteMBHeader - Write message base header
|
|
|
+=============================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_WriteMBHeader( s_JamBase* Base_PS,
|
|
|
+ s_JamBaseHeader* Header_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Increases the ModCounter field by one, resets the header signature
|
|
|
+ and writes the message base header to the start of the JAM header
|
|
|
+ file.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ Header_PS A pointer to the base header to be stored
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_BAD_PARAM if Base_PS or Header_PS is NULL
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_NOT_LOCKED if the message base is not locked
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamBaseHeader BaseHeader_S;
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ /* modify header here */
|
|
|
+
|
|
|
+ Result_I = JAM_WriteMBHeader( &BaseHeader_S );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_WriteMBHeader returned %d.\n", Result_I );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+=====================================
|
|
|
+JAM_FindUser - Find message to a user
|
|
|
+=====================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_FindUser( s_JamBase* Base_PS,
|
|
|
+ ulong UserCrc_I,
|
|
|
+ ulong StartMsg_I,
|
|
|
+ ulong* MsgNo_PI );
|
|
|
+
|
|
|
+Description
|
|
|
+ Scans the message base looking for a message written to a specific
|
|
|
+ user.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ UserCrc_I The CRC32 value for the searched name
|
|
|
+
|
|
|
+ StartMsg_I The first message number to look at. This value is
|
|
|
+ not the message's unique number, but rather the
|
|
|
+ absolute position of the message in the message
|
|
|
+ base. Message 0 therefore means the first message.
|
|
|
+
|
|
|
+ MsgNo_PI A pointer to a variable where the message number
|
|
|
+ for the found message will be stored. This number
|
|
|
+ is the absolute message position in the message
|
|
|
+ base. Message 0 means the first message.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if a message was found
|
|
|
+ JAM_NO_USER if no message was found
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ uchar Name_AC[32];
|
|
|
+ int Result_I;
|
|
|
+ ulong Crc_I;
|
|
|
+ ulong Msg_I;
|
|
|
+
|
|
|
+ strcpy( Name_AC, "Bjorn Stenberg" );
|
|
|
+
|
|
|
+ Crc_I = JAM_Crc32( Name_AC, strlen( Name_AC ) );
|
|
|
+
|
|
|
+ Result_I = JAM_FindUser( Base_PS, Crc_I, 0, &Msg_I );
|
|
|
+
|
|
|
+ switch ( Result_I ) {
|
|
|
+ case JAM_NO_USER:
|
|
|
+ printf("No message for me.\n");
|
|
|
+ break;
|
|
|
+
|
|
|
+ case JAM_IO_ERROR:
|
|
|
+ printf("IO error %d\n", JAM_Errno() );
|
|
|
+ break;
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+==========================================================
|
|
|
+JAM_GetMBSize - Get the number of messages in message base
|
|
|
+==========================================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_GetMBSize( s_JamBase* Base_PS,
|
|
|
+ ulong* Messages_PI );
|
|
|
+
|
|
|
+Description
|
|
|
+ Finds out the number of messages (deleted and undeleted) in the
|
|
|
+ message base.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ Messages_PI A pointer to a variable where the number of
|
|
|
+ messages will be stored.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ int Result_I;
|
|
|
+ ulong Size_I;
|
|
|
+
|
|
|
+ Result_I = JAM_GetMBSize( Base_PS, &Size_I );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_GetMBSize returned %d.\n", Result_I );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+--------------------------------------------------------------------------
|
|
|
+
|
|
|
+ Message functions
|
|
|
+ -----------------
|
|
|
+
|
|
|
+ These functions handle individual JAM messages. A JAM message contains of
|
|
|
+three parts:
|
|
|
+
|
|
|
+ * Message Header
|
|
|
+ * Message Header Subfields
|
|
|
+ * Message Text
|
|
|
+
|
|
|
+ The message header is a simple C structure and the message text is a
|
|
|
+simple text buffer.
|
|
|
+ The subfields, however, are a bit more tricky. These contain everything
|
|
|
+that is not covered by the header, including the TO, FROM, SUBJECT fields,
|
|
|
+origin and destination network adresses etc. There can be an unlimited
|
|
|
+number of subfields to a message.
|
|
|
+ In this routine library the subfields are encapsulated by a 'subfield
|
|
|
+packet', which is handled by its own set of routines. See a later section
|
|
|
+of this document for an explanation of those.
|
|
|
+
|
|
|
+=============================================================
|
|
|
+JAM_ReadMsgHeader - Read a message's header and its subfields
|
|
|
+=============================================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_ReadMsgHeader( s_JamBase* Base_PS,
|
|
|
+ ulong MsgNo_I,
|
|
|
+ s_JamMsgHeader* Header_PS,
|
|
|
+ s_JamSubPacket** Subfields_PPS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Reads a message header and (optionally) the message header
|
|
|
+ subfields.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ MsgNo_I The message number, i.e. the absolute position of
|
|
|
+ the message in the message base. Message 0 is the
|
|
|
+ first message.
|
|
|
+
|
|
|
+ Header_PS A pointer to a message header structure where the
|
|
|
+ message header will be stored.
|
|
|
+
|
|
|
+ Subfields_PPS A pointer to a subpacket pointer, where the
|
|
|
+ subfield packet handle will be stored.
|
|
|
+ If this parameter is NULL, no subfields are read.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_NO_MEMORY if a memory allocation failed
|
|
|
+ JAM_NO_MESSAGE if message has been removed
|
|
|
+ JAM_CORRUPT_MSG if message subfields are corrupted
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamMsgHeader Header_S;
|
|
|
+ s_JamSubPacket* SubPack_PS
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ Result_I = JAM_ReadMsgHeader( 0, &Header_S, &SubPack_PS );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_ReadMsgHeader returned %d.\n", Result_I );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+=======================================
|
|
|
+JAM_ReadMsgText - Read a message's text
|
|
|
+=======================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_ReadMsgText( s_JamBase* Base_PS,
|
|
|
+ ulong Offset_I,
|
|
|
+ ulong Length_I,
|
|
|
+ uchar* Buffer_PC );
|
|
|
+
|
|
|
+Description
|
|
|
+ Reads the body text associated with a message.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ Offset_I The text position in the text file. This
|
|
|
+ information is stored in the message header.
|
|
|
+
|
|
|
+ Length_I The text length. This information is stored in the
|
|
|
+ message header.
|
|
|
+
|
|
|
+ Buffer_PC A pointer to where the text should be stored.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamMsgHeader Header_S;
|
|
|
+ uchar* Buffer_PC;
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ /* read msg header */
|
|
|
+ Result_I = JAM_ReadMsgHeader( Base_PS, 0, &Header_S, &SubPack_PS );
|
|
|
+ if ( Result_I ) {
|
|
|
+ printf("JAM_ReadMsgHeader returned %d.\n", Result_I );
|
|
|
+ return;
|
|
|
+ }
|
|
|
+
|
|
|
+ /* allocate buffer text */
|
|
|
+ Buffer_PC = (uchar*) malloc( Header_S.TxtLen );
|
|
|
+ if ( !Buffer_PC ) {
|
|
|
+ printf("malloc failed.\n");
|
|
|
+ return;
|
|
|
+ }
|
|
|
+
|
|
|
+ /* read text */
|
|
|
+ Result_I = JAM_ReadMsgText( Base_PS,
|
|
|
+ Header_S.TxtOffset,
|
|
|
+ Header_S.TxtLen,
|
|
|
+ Buffer_PC );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_ReadMsgText returned %d.\n", Result_I );
|
|
|
+
|
|
|
+ free( Buffer_PC );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+==============================================
|
|
|
+JAM_AddMessage - Add a message to message base
|
|
|
+==============================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_AddMessage( s_JamBase* Base_PS,
|
|
|
+ s_JamMsgHeader* Header_PS,
|
|
|
+ s_JamSubPacket* SubPack_PS,
|
|
|
+ uchar* Text_PC,
|
|
|
+ ulong TextLen_I );
|
|
|
+
|
|
|
+Description
|
|
|
+ Adds a message to the message base. Fully automatic.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ Header_PS A pointer to the message header struct. The
|
|
|
+ function will set the following header fields:
|
|
|
+ Signature, Revision, TxtOffset, TxtLen, SubfieldLen
|
|
|
+ and MsgNum. Whatever you set these fields to will
|
|
|
+ be overwritten.
|
|
|
+
|
|
|
+ SubPack_PS A subfield packet handler, containing all subfields
|
|
|
+ for the message.
|
|
|
+
|
|
|
+ Text_PC A pointer to the first byte of the message text.
|
|
|
+
|
|
|
+ TextLen_I The length of the message text, excluding any zero
|
|
|
+ termination characters.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_NOT_LOCKED if the message base is not locked
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamSubPacket* SubPacket_PS;
|
|
|
+ s_JamSubfield Subfield_S;
|
|
|
+ s_JamMsgHeader Header_S;
|
|
|
+ uchar Text_AC[64];
|
|
|
+ uchar Field_AC[64];
|
|
|
+
|
|
|
+ /*
|
|
|
+ ** Fix message header
|
|
|
+ */
|
|
|
+
|
|
|
+ JAM_ClearMsgHeader( &Header_S );
|
|
|
+ Header_S.DateWritten = time(NULL);
|
|
|
+
|
|
|
+ /*
|
|
|
+ ** Create subfield packet
|
|
|
+ */
|
|
|
+
|
|
|
+ SubPacket_PS = JAM_NewSubPacket();
|
|
|
+ if ( !SubPacket_PS ) {
|
|
|
+ printf("JAM_NewSubPacket returned NULL.\n" );
|
|
|
+ return;
|
|
|
+ }
|
|
|
+
|
|
|
+ /* set up subfield 1 */
|
|
|
+ strcpy( Field_AC, "This is field #1" );
|
|
|
+ Subfield_S.LoID = JAMSFLD_SENDERNAME;
|
|
|
+ Subfield_S.HiID = 0;
|
|
|
+ Subfield_S.DatLen = strlen( Field_AC );
|
|
|
+ Subfield_S.Buffer = Field_AC;
|
|
|
+ JAM_PutSubfield( SubPacket_PS, &Subfield_S );
|
|
|
+
|
|
|
+ /* set up subfield 2 */
|
|
|
+ strcpy( Field_AC, "This is field #2" );
|
|
|
+ Subfield_S.LoID = JAMSFLD_RECVRNAME;
|
|
|
+ Subfield_S.HiID = 0;
|
|
|
+ Subfield_S.DatLen = strlen( Field_AC );
|
|
|
+ Subfield_S.Buffer = Field_AC;
|
|
|
+ JAM_PutSubfield( SubPacket_PS, &Subfield_S );
|
|
|
+
|
|
|
+
|
|
|
+ /*
|
|
|
+ ** Add message
|
|
|
+ */
|
|
|
+
|
|
|
+ strcpy( Text_AC, "Hello world!\nThis is a test.");
|
|
|
+
|
|
|
+ /* [lock the message base] */
|
|
|
+
|
|
|
+ Result_I = JAM_AddMessage( Base_PS, &Header_S, SubPacket_PS,
|
|
|
+ Text_AC, strlen( Text_AC ) );
|
|
|
+ if ( Result_I ) {
|
|
|
+ printf("JAM_AddMessage returned %d.\n", Result_I );
|
|
|
+ return;
|
|
|
+ }
|
|
|
+
|
|
|
+ /* [unlock the message base] */
|
|
|
+
|
|
|
+ JAM_DelSubPacket( SubPacket_PS );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+=================================================================
|
|
|
+JAM_AddEmptyMessage - Add a empty message entry to a message base
|
|
|
+=================================================================
|
|
|
+Syntax
|
|
|
+ int JAM_AddEmptyMessage( s_JamBase* Base_PS);
|
|
|
+
|
|
|
+Description
|
|
|
+ Adds an empty message header to the message base. Useful
|
|
|
+ when writing a messagebase maintenance utility.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_NOT_LOCKED if the message base is not locked
|
|
|
+
|
|
|
+Example
|
|
|
+ none
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+===============================================
|
|
|
+JAM_ChangeMsgHeader - Change a message's header
|
|
|
+===============================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_ChangeMsgHeader( s_JamBase* Base_PS,
|
|
|
+ ulong MsgNo_I,
|
|
|
+ s_JamMsgHeader* Header_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Writes over an old message header with a new one. Only the header -
|
|
|
+ not the subfields - can be changed due to the subfields' dynamic
|
|
|
+ size.
|
|
|
+ NOTE! Use this function with caution. It is easy to corrupt a
|
|
|
+ message by giving it an incorrect header.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ MsgNo_I The absolute message number. Message #0 is the
|
|
|
+ first in the message base.
|
|
|
+
|
|
|
+ Header_PS A pointer to the header structure to write.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_NOT_LOCKED if the message base is not locked
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamMsgHeader Header_S;
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ /* [lock the message base] */
|
|
|
+
|
|
|
+ Result_I = JAM_ReadMsgHeader( Base_PS, 0, &Header_S, NULL );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_ReadMsgHeader returned %d.\n", Result_I );
|
|
|
+
|
|
|
+ Header_S.TimesRead++;
|
|
|
+
|
|
|
+ Result_I = JAM_ChangeMsgHeader( Base_PS, 0, &Header_S );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_ChangeMsgHeader returned %d.\n", Result_I );
|
|
|
+
|
|
|
+ /* [unlock the message base] */
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+=====================================================
|
|
|
+JAM_ClearMsgHeader - Clear a message header structure
|
|
|
+=====================================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_ClearMsgHeader( s_JamMsgHeader* Header_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Clears a message header structure and prepares it for use. This
|
|
|
+ includes setting the Signature field and the Revision field to
|
|
|
+ their correct values, and setting the CRC fields to JAM_NO_CRC.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Header_PS A pointer to the structure to prepare.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_BAD_PARAM if Header_PS is NULL
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+===================================================
|
|
|
+JAM_DeleteMessage - Delete message from messagebase
|
|
|
+===================================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_DeleteMessage( s_JamBase* Base_PS,
|
|
|
+ ulong MsgNo_I );
|
|
|
+
|
|
|
+
|
|
|
+Description
|
|
|
+ Deletes message from messagebase by setting HdrOffset and UserCRC
|
|
|
+ in index to 0xFFFFFFFF. ActiveMsgs in base header also updated.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ MsgNo_I The absolute message number. Message #0 is the
|
|
|
+ first in the message base.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_NOT_LOCKED if the message base is not locked
|
|
|
+
|
|
|
+Example
|
|
|
+ none
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+--------------------------------------------------------------------------
|
|
|
+
|
|
|
+ Subfield packet functions
|
|
|
+ -------------------------
|
|
|
+
|
|
|
+ As described earlier, a subfield is a part of the message header. Due to
|
|
|
+the complexity of the different network types in use, it is not feasible to
|
|
|
+try and cram all data into one header struct. Therefore, JAM uses a fairly
|
|
|
+small header struct and instead marks all additional data fields as
|
|
|
+'subfields'.
|
|
|
+ In order to make life a little more easy, I have used the concept of a
|
|
|
+container for all subfields. I call it a 'Subfield Packet'. It is
|
|
|
+identified by a struct pointer, and should be looked upon as a file or a
|
|
|
+list that you manipulate via the following four functions:
|
|
|
+
|
|
|
+
|
|
|
+===============================================
|
|
|
+JAM_NewSubPacket - Create a new subfield packet
|
|
|
+===============================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ s_JamSubPacket* JAM_NewSubPacket( void );
|
|
|
+
|
|
|
+Description
|
|
|
+ Creates a new, empty, subfield packet.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ None
|
|
|
+
|
|
|
+Returns
|
|
|
+ The subpacket handle, if successful, or NULL if a memory allocation
|
|
|
+ failed.
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamSubPacket* SubPacket_PS;
|
|
|
+
|
|
|
+ SubPacket_PS = JAM_NewSubPacket();
|
|
|
+ if ( !SubPacket_PS ) {
|
|
|
+ printf("JAM_NewSubPacket returned NULL.\n" );
|
|
|
+ return;
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+===========================================
|
|
|
+JAM_DelSubPacket - Delete a subfield packet
|
|
|
+===========================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_DelSubPacket( s_JamSubPacket* SubPack_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Frees all memory used by a subfield packet. All subfields in the
|
|
|
+ packet will be lost and the packet handle will not be valid any
|
|
|
+ more.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ SubPack_PS The subfield packet to delete
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_BAD_PARAM if SubPack_PS is NULL.
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamSubPacket* SubPacket_PS;
|
|
|
+
|
|
|
+ SubPacket_PS = JAM_NewSubPacket();
|
|
|
+ if ( !SubPacket_PS ) {
|
|
|
+ printf("JAM_NewSubPacket returned NULL.\n" );
|
|
|
+ return;
|
|
|
+ }
|
|
|
+
|
|
|
+ SubPacket_PS = JAM_DelSubPacket();
|
|
|
+ if ( !SubPacket_PS ) {
|
|
|
+ printf("JAM_DelSubPacket returned NULL.\n" );
|
|
|
+ return;
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+=======================================================================
|
|
|
+JAM_GetSubfield - Get a subfield from a subfield packet (not reentrant)
|
|
|
+=======================================================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ s_JamSubfield* JAM_GetSubfield( s_JamSubPacket* SubPack_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Returns a pointer to the first/next subfield struct in the subfield
|
|
|
+ packet.
|
|
|
+
|
|
|
+ WARNING: This function is not reentrant and should not be used in
|
|
|
+ multi-threaded applications unless you know what you are doing.
|
|
|
+
|
|
|
+ Use JAM_GetSubfield_R instead when a reentrant function is needed.
|
|
|
+
|
|
|
+Parameter
|
|
|
+ SubPack_PS The subfield packet to use. If this parameter is
|
|
|
+ NULL, the next subfield from the subfield packet
|
|
|
+ previously scanned will be returned.
|
|
|
+
|
|
|
+Returns
|
|
|
+ A pointer to a subfield, if successful, or NULL if there are no
|
|
|
+ more subfields in the packet.
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamSubPacket* SubPack_PS;
|
|
|
+ s_JamSubfield* Subfield_PS;
|
|
|
+ s_JamMsgHeader Header_S;
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ Result_I = JAM_ReadMsgHeader( 0, &Header_S, &SubPack_PS );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_ReadMsgHeader returned %d.\n", Result_I );
|
|
|
+
|
|
|
+ for ( Subfield_PS = JAM_GetSubfield( SubPack_PS ); Subfield_PS;
|
|
|
+ Subfield_PS = JAM_GetSubfield( NULL ) )
|
|
|
+ printf("Subfield id %d\n", Subfield_PS->LoID );
|
|
|
+
|
|
|
+ JAM_DelSubPacket( SubPack_PS );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+=====================================================================
|
|
|
+JAM_GetSubfield_R - Get a subfield from a subfield packet (reentrant)
|
|
|
+=====================================================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ s_JamSubfield* JAM_GetSubfield( s_JamSubPacket* SubPack_PS,
|
|
|
+ ulong* Count_PI );
|
|
|
+
|
|
|
+Description
|
|
|
+ Returns a pointer to the first/next subfield struct in the subfield
|
|
|
+ packet.
|
|
|
+
|
|
|
+ This function is a reentrant replacement for JAM_GetSubfield.
|
|
|
+
|
|
|
+Parameter
|
|
|
+ SubPack_PS The subfield packet to use.
|
|
|
+
|
|
|
+ Count_PI Pointer to a variable that contains the number of
|
|
|
+ the subfield to retrieve. The variable should be
|
|
|
+ set to zero the first time the function is called
|
|
|
+ and is then automatically increased by the function
|
|
|
+ for any subsequent calls.
|
|
|
+
|
|
|
+Returns
|
|
|
+ A pointer to a subfield, if successful, or NULL if there are no
|
|
|
+ more subfields in the packet.
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamSubPacket* SubPack_PS;
|
|
|
+ s_JamSubfield* Subfield_PS;
|
|
|
+ s_JamMsgHeader Header_S;
|
|
|
+ ulong Count_I;
|
|
|
+ int Result_I;
|
|
|
+
|
|
|
+ Result_I = JAM_ReadMsgHeader( 0, &Header_S, &SubPack_PS );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_ReadMsgHeader returned %d.\n", Result_I );
|
|
|
+
|
|
|
+ Count_I = 0;
|
|
|
+
|
|
|
+ while( ( Subfield_PS = JAM_GetSubfield_R( SubPack_PS , &Count_I ) ) )
|
|
|
+ printf("Subfield id %d\n", Subfield_PS->LoID );
|
|
|
+
|
|
|
+ JAM_DelSubPacket( SubPack_PS );
|
|
|
+ }
|
|
|
+
|
|
|
+=======================================================
|
|
|
+JAM_PutSubfield - Put a subfield into a subfield packet
|
|
|
+=======================================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_PutSubfield( s_JamSubPacket* SubPack_PS,
|
|
|
+ s_JamSubfield* Subfield_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Puts a subfield into a subfield packet. The subfield is copied
|
|
|
+ before being put into the subfield packet.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ SubPack_PS The subfield packet to add to
|
|
|
+
|
|
|
+ Subfield_PS The subfield to put in the packet
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_NO_MEMORY if a memory allocation failed
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ s_JamSubPacket* SubPacket_PS;
|
|
|
+ s_JamSubfield Subfield_S;
|
|
|
+ uchar Field_AC[64];
|
|
|
+
|
|
|
+ SubPacket_PS = JAM_NewSubPacket();
|
|
|
+ if ( !SubPacket_PS ) {
|
|
|
+ printf("JAM_NewSubPacket returned NULL.\n" );
|
|
|
+ return;
|
|
|
+ }
|
|
|
+
|
|
|
+ /* set up subfield 1 */
|
|
|
+ strcpy( Field_AC, "This is field #1" );
|
|
|
+ Subfield_S.LoID = JAMSFLD_SENDERNAME;
|
|
|
+ Subfield_S.HiID = 0;
|
|
|
+ Subfield_S.DatLen = strlen( Field_AC );
|
|
|
+ Subfield_S.Buffer = Field_AC;
|
|
|
+ JAM_PutSubfield( SubPacket_PS, &Subfield_S );
|
|
|
+
|
|
|
+ /* set up subfield 2 */
|
|
|
+ strcpy( Field_AC, "This is field #2" );
|
|
|
+ Subfield_S.LoID = JAMSFLD_RECVRNAME;
|
|
|
+ Subfield_S.HiID = 0;
|
|
|
+ Subfield_S.DatLen = strlen( Field_AC );
|
|
|
+ Subfield_S.Buffer = Field_AC;
|
|
|
+ JAM_PutSubfield( SubPacket_PS, &Subfield_S );
|
|
|
+
|
|
|
+ JAM_DelSubPacket( SubPacket_PS );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+--------------------------------------------------------------------------
|
|
|
+
|
|
|
+ LastRead functions
|
|
|
+ ------------------
|
|
|
+
|
|
|
+ JAM implements the often-used concept of high water marking for
|
|
|
+remembering which user read how many messages in each area.
|
|
|
+ Personally I think this concept stinks, since it does not store *which*
|
|
|
+messages a user has read, only the number of the highest message he has
|
|
|
+read. But since it's a part of JAM and it's fairly straightforward and
|
|
|
+easy, I've implemented two support functions for it.
|
|
|
+ I would, however, strongly recommend all BBS programmers to use proper
|
|
|
+message mapping systems instead, so your users can read their messages in
|
|
|
+whatever order they wish.
|
|
|
+
|
|
|
+
|
|
|
+=========================================
|
|
|
+JAM_ReadLastRead - Read a lastread record
|
|
|
+=========================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_ReadLastRead( s_JamBase* Base_PS,
|
|
|
+ ulong User_I,
|
|
|
+ s_JamLastRead* Record_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Reads a lastread record from the lastread file.
|
|
|
+
|
|
|
+Parameter
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ User_I A system-unique user number.
|
|
|
+
|
|
|
+ Record_PS A pointer to the lastread struct where the record
|
|
|
+ will be stored.
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_BAD_PARAM if Record_PS is NULL
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+ JAM_NO_USER if the user number was not found
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ int Result_I;
|
|
|
+ s_JamLastRead LastRead_S;
|
|
|
+
|
|
|
+ Result_I = JAM_ReadLastRead( Base_PS, 4711, &LastRead_S );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_ReadLastRead returned %d\n", Result_I );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+===========================================
|
|
|
+JAM_WriteLastRead - Write a lastread record
|
|
|
+===========================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_WriteLastRead( s_JamBase* Base_PS,
|
|
|
+ ulong User_I,
|
|
|
+ s_JamLastRead* Record_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ Writes a lastread record to the lastread file. If the user number
|
|
|
+ could not be found, the record will be appended to the end of the
|
|
|
+ file.
|
|
|
+
|
|
|
+Parameter
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+ User_I A system-unique user number
|
|
|
+
|
|
|
+ Record_PS A pointer to the lastread struct to be written
|
|
|
+
|
|
|
+Returns
|
|
|
+ 0 if successful
|
|
|
+ JAM_BAD_PARAM if Record_PS is NULL
|
|
|
+ JAM_IO_ERROR if an I/O error occured. see JAM_Errno()
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ int Result_I;
|
|
|
+ s_JamLastRead LastRead_S;
|
|
|
+
|
|
|
+ Result_I = JAM_WriteLastRead( Base_PS, 4711, &LastRead_S );
|
|
|
+ if ( Result_I )
|
|
|
+ printf("JAM_WriteLastRead returned %d\n", Result_I );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+--------------------------------------------------------------------------
|
|
|
+
|
|
|
+ Miscellanous functions
|
|
|
+ ----------------------
|
|
|
+
|
|
|
+
|
|
|
+==============================================
|
|
|
+JAM_Crc32 - Calculate CRC32 on a block of data
|
|
|
+==============================================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ ulong JAM_Crc32( uchar* Buffer_PC,
|
|
|
+ ulong Length_I );
|
|
|
+
|
|
|
+Description
|
|
|
+ Calculates the Crc32 value for a block of data. All ASCII
|
|
|
+ characters are converted to lowercase before calculating
|
|
|
+ the CRC (the input data is unchanged).
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Buffer_PC A pointer to the first byte of the data block
|
|
|
+
|
|
|
+ Length_I The number of bytes in the data block
|
|
|
+
|
|
|
+Returns
|
|
|
+ The Crc32 value
|
|
|
+
|
|
|
+Example
|
|
|
+ {
|
|
|
+ ulong Crc_I;
|
|
|
+ uchar Text_AC[32];
|
|
|
+
|
|
|
+ strcpy( Text_AC, "Hello world!\n");
|
|
|
+
|
|
|
+ Crc_I = JAM_Crc32( Text_AC, strlen( Text_AC ) );
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+=============================
|
|
|
+JAM_Errno - Specify I/O error
|
|
|
+=============================
|
|
|
+
|
|
|
+Syntax
|
|
|
+ int JAM_Errno( s_JamBase* Base_PS );
|
|
|
+
|
|
|
+Description
|
|
|
+ When any of these library routines return JAM_IO_ERROR, you can
|
|
|
+ call this function to find out exactly what went wrong.
|
|
|
+
|
|
|
+Parameters
|
|
|
+ Base_PS The message base to use
|
|
|
+
|
|
|
+Returns
|
|
|
+ Standard 'errno' values, as the C compiler generated them, or if
|
|
|
+ the I/O error was system specific, the return code is (10000 +
|
|
|
+ system status code).
|
|
|
+
|
|
|
+Examples
|
|
|
+ {
|
|
|
+ int Result_I;
|
|
|
+ uchar Text_AC[10];
|
|
|
+
|
|
|
+ /* generate an I/O error */
|
|
|
+ Result_I = JAM_ReadMsgText( 0xffffffff, 10, Text_AC );
|
|
|
+ if ( Result_I ) {
|
|
|
+ errno = JAM_Errno( Base_PS );
|
|
|
+ perror("JAM i/o error");
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+
|
