ftp.wwiv.com/ftp.wwiv.com.zip/ftp.wwiv.com/pub/WW4SHARE/W424ASRC.ZIP/W424ASRC.DOC

Text File | 1994-09-08 | 31KB | 773 lines

                 WWIV Source Documentation
                         for v4.24a







                             by








                         Wayne Bell





 This document was a chapter in the 4.24 bbs documentation.
It has been moved to a separate document for 4.24a.  Wayne
Bell will continue to revise and update this document.

                          (c) 1995
                         Wayne Bell



               WWIV Source Code Documentaion

        ╔═══════════════════════════════════════╗
        ║        WWIV Source Documentation      ║
        ║ Copyright (c) 1988-1995 by Wayne Bell ║
        ╚═══════════════════════════════════════╝

 4.1  Source Distribution

    Although this document is being included with the pre-
 compiled (shareware) version, its primary use is for those
 sysops who have registered.  Unregistered sysops may also
 learn from it and may see some of the advantages of being
 registered--advantages which include but are not limited
 to the availability of certain options discussed in this
 document.

   The source code is ONLY available to people who have
 registered; IT IS NOT FOR ANY OTHER PEOPLE.  As can be
 seen in the license agreement in Chapter 3 as well as by
 the notice at the beginning of all the source files,
 DISTRIBUTION OF THE SOURCE BY ANYONE EXCEPT BY WAYNE BELL
 OR A SOURCE DISTRIBUTION SYSTEM (SDS) AUTHORIZED BY ME IS
 PROHIBITED.  Even if your best friend mails a registra-
 tion check right before your eyes, he must get the source


                            -1-



 from ME or from an SDS BBS, you may not give him a copy.

 If you have somehow gotten ahold of the WWIV source code
 WITHOUT either downloading it from my BBS, downloading it
 from an SDS BBS, or receiving it in the mail from WWIV
 Software Services, then you are hurting the cause of good
 software.  If you continue to possess and use this source
 code, you may place yourself and the person from whom you
 received it in legal jeopardy.  If it turns out that it
 is not possible to control distribution of the source by
 reasonable means, you will probably find that the source
 WILL NOT BE AVAILABLE for future versions.

 The source is provided to registered sysops so that it
 may be modifed to suit their own needs and desires. You
 may not give out a copy of your modified program to
 anyone (either the source or compiled).

 4.1.A  Distribution of Changes to Source Code

 This does not mean, however, that you can't distribute
 CHANGES.  You may not distribute a copy of WWIV that you
 have compiled, ever, or any major portions of the source
 code without expressed permission of Wayne Bell.  If you
 would like to help another registered sysop modify their
 code, you must follow these procedures:

 One registered WWIV sysop can legally have another regis-
 tered WWIV sysop install mods for him.  The rules for
 doing this are:

 1. Both the person doing the modding, and the person re-
    questing it, must be registered WWIV sysops.

      a. This is verified by having both the requester and
         the modder email WWIVnet 1@1 from their account
         on an SDS, where they have access to the source
         code (ie, are on the list).

      b. The requester and modder must coordinate before-
         hand on when this is to be done.

      c. The email will say, "I wish to do modding for Joe
         Blow #xxx @yyyy", or "I want Jane blow #zzz @aaaa
         to do some modding for me." where both accounts
         listed (giving name, user-number, and system
         number) are accounts on an SDS, with access to the
         source code.  The two emails must be sent within a


                            -2-



         week or two of each other.

      d. After both emails are received, and registration
         is verified [actually, registration will have
         been verified beforehand, due to their having SDS
         access] then WWIVnet 1@1 will email back to both
         saying it has been approved.  (Approval here
         relies only upon registration, and will not be
         denied if both are listed for SDS access.)

 2. The modder may start out either with the unmodified
    source code to the latest version of WWIV, or from a
    version of the source code sent by the requester.

 3. The modder will then make available to the requester the
    modified source code, plus, optionally, a compiled .exe
    (but may not only give the .exe, must make available the
    modified source also).

 4. For purposes of sending source code and/or compiled
    .exe's in 2 and 3 above, this must be done either
    directly (eg, call up each other in a term program
    and xfer it there, or hand deliver it on floppy), or
    via the BBS of either requester or modder, where the
    BBS is that system on which that person is account #1,
    and in that case, only in an xfer directory where only
    the requester and modder have access (via DAR
    restriction).  No other remote sysops or co-sysops
    may have access to that directory.

 5. Neither Wayne Bell nor WWIV Software Services are
    responsible for enforcing any modding arrangements.  If
    the modder never actually ends up doing it, don't come
    crying to us.

 Note, that this only applies if you must transfer the
 files between systems.  If you wish, you can have someone
 else (registered or not) come over and make mods on your
 system, without any approval from anyone.  That person
 just can't take (WWIV source) files to or from your
 system (without the approval method listed above).

 You may also distribute changes (commonly called mod-
 ifications, or "mods") you made to the source, so that
 other people with the source may make the same changes.

 For example, suppose you made a modification to function
 send_email() in bbsovl1.c, and wanted to allow other


                            -3-



 people to make the same modification.  Now, since
 function send_email() is under 50 lines (rather short),
 you may just go ahead and distribute the entire
 procedure, telling people they need to replace function
 send_email() in bbsovl1.c with your new one.

 Suppose, on the other hand, that you have made modifica-
 tions to function scan() in msgbase1.c.  Since function
 scan() is around 700 lines, it is unlikely you will have
 made modifications to the entire thing.  Most likely, it
 will be just a block of code, maybe 50-75 lines long,
 that contains the bulk of your changes.  Just pull out
 those blocks that you have made changes to, and
 distribute those, along with a short note telling which
 lines to delete, and where to insert your new ones.

 4.1.B  Permission to distribute source code changes

 Suppose, instead, that your modification required you to
 insert 3 new variables, and put in a few lines of code in
 4 of the source files.  DO NOT JUST DISTRIBUTE ALL THE
 FILES YOU CHANGED.  Instead, document where you made the
 changes, and list where to insert (or delete) the few
 lines of code you did change.  If your modifications
 would require you to distribute over 100 lines of the
 initial BBS code, you should contact Wayne Bell (1@1)
 before you distribute it, sending me a copy, and asking
 if it's OK.  Most likely it will be.

 If you have any questions about this policy, or how it
 might apply to you, feel free to contact Wayne Bell at
 Amber BBS at 310-798-9993 300/1200/2400/V.32bis/HST/24
 hrs.

 You may wonder why I have put such restrictions on
 distribution of changes.  The main reason is the reckless
 abandon some people have exhibited in just doing whatever
 they damn well pleased with earlier versions of WWIV.
 I've heard of people making changes to the code,
 inserting profanity in comments throughout the program,
 and distributing that as if it were a perfectly normal
 copy of WWIV.  This is what I want to prevent.

 As long as your changes don't contain a significant
 portion of the BBS source in them, I will probably have
 no problems about your distributing them.  But, do check,
 BEFOREHAND! The old adage that "It is easier to ask for
 forgiveness than it is permission" does not apply in this


                            -4-



 case, and you could be liable for legal damages if you do
 not follow this policy.

 Also, any changes that you do distribute, I'd appreciate
 it if you'd upload a copy to my system, so that there can
 be a sort of "central area" where people can find things.

 About INIT.EXE.  As you can see, I'm not distributing the
 source to the init program.  The source to the init
 program is not available to anyone, nor is the source to
 the network program available.


 /******************************************************/

 4.2  Compiler versions

 There.  Now that I'm through with that, I can get about
 describing the source a bit.  First, how to set
 everything up so that it compiles.  WWIV will compile
 correctly under Turbo C++ v2.0 and later.  It will not
 compile correctly under any other compilers, and it will
 not compile correctly under Microsoft C, or any other C
 compiler.

 With overlays, necessary compiler options, RIPDRIVE
 support, and the shrinking features, it would be too
 difficult (if it's even possible at all) to get it to
 compile and link under the Borland IDE.  Therefore, you
 must use the external "make" utility (that comes with the
 compiler) to compile and link WWIV.

 First, un-zip the WWIV source archive into a directory of
 its own.  DO NOT put it in your Turbo C directory.  At
 the very least, make a separate "WWIV" directory
 somewhere, and do development in there.  By putting the
 source files in their own directory like this, you keep
 them separate from all your other files. It makes it much
 easier to manage.

 Whatever directory you use, you must create two
 sub-directories off it, "obj" and "exe".  For example,
 you might say:

 C:\>mkdir wwiv
 C:\>cd wwiv
 C:\WWIV>pkunzip \telix\dl\wwivs424.zip
 C:\WWIV>mkdir obj


                            -5-



 C:\WWIV>mkdir exe

 (Note you must first extract the wwivs424.zip file from
 the wwiv424s.zip file.  See the license.agr file in
 wwiv424s.zip file for instructions on that.)

 The "obj" directory will hold "*.obj" files.  You will
 never need to look at those, but you need to have them.
 Note that there are also .obj files in your WWIV source
 directory.  Leave them there.

 Now, whenever you want to re-compile any changed files
 and re-link the executables, go to the WWIV source
 directory and type "make".

 If everything is set up correctly, the source should
 compile without any errors or warnings.  If you have any
 errors or warnings, you have done something wrong.  Go
 back and check to ensure that you have the directory
 variables set up correctly.

 4.2.A  FCNS.H

 There is another feature when using make -- it creates
 the fcns.h file based upon your source files. To
 re-create the fcns.h file just type "make fcns".  This is
 what I have used to create it in the first place, so if
 you run it on an unmodified copy of the source, it should
 end up being the same. Additionally, if you add
 additional source files, this will include the prototypes
 from those files also (assuming, of course, that you use
 the same function declaration style that I do - the
 technique of making the function prototypes is pretty
 dumb, but it works).  Note that if you do "make fcns",
 then all your source will re-compile, so I recommend only
 doing a "make fcns" when something significant has
 changed.

 /******************************************************/

 4.3  General Comments about the source

 The rest of this section is to describe some general
 things about the source, and is not meant to describe how
 to use Turbo C.  If you need help with the TC integrated
 environment, look through the manual, and play around
 with it a bit.



                            -7-




 4.3.A  Header files:

 VARDEC.H - holds the type declarations and #define's for
            the BBS.

 FCNS.H - holds function declarations for all functions in
          the BBS.

 VARS.H - Holds declarations (and externs) for all global
          variables.

 NET.H - holds structure definitions for WWIVnet.

 All the BBS files (except bbs.c) have, after the
 copyright notice, #include "vars.h" #pragma hdrstop

 Any additional source (.c) files you add should include
 vars.h, and then have the #pragma hdrstop after that (the
 #pragma is for the BC++ precompiled header files).  Note
 that vars.h includes several standard C header files, so
 you won't have to manually include those yourself.

 4.3.B  Main source files:

 The source files fall into two categories: overlaid, and
 non-overlaid.  There are two reasons why a file is in the
 non-overlaid category: it cannot be overlaid; it would be
 too slow if it were.  Anything that might be called from
 an external program (screen and com port IO, for example)
 cannot be overlaid.

 You will find that some functions end up in strange
 places.  These are mostly rarely-used sysop services that
 get moved to an overlay from their previous location, in
 an attempt at "overlay-balancing."

 bbs.c - holds the main() function, and getcaller().
 getcaller() processes WFC commands.

 bbsutl*.c - hold miscellaneous BBS utility functions.

 com.c - holds com port related services, and combined
 screen/modem IO.

 conio.c - holds console related IO services (that is,
 things that display locally but not remotely).



                            -8-



 connect1.c - holds many WWIVnet-related interfacing
 functions.  Most of reading/writing network files is done
 here.

 extrn.c - holds code for interfacing with external
 programs, mostly DOS call intercepting.  You will
 probably not want to touch anything here unless you are
 very familiar with low level DOS.

 mmenu.c - holds the main menu and main transfer menu.  If
 you add in something that you want to be available from
 the main menu, you'll need to add in a few lines here to
 call it.

 modem.c - handles talking to the modem (answering phone,
 etc).

 msgbase*.c - the message base code (scan prompt, reading
 msgs, etc).

 share.c - handles file sharing for multiple instances.
 ALL FILE IO should be done using the services in share.c
 Use sh_open(), sh_open1(), or fsh_open() to open files.
 Also use the sh_ or fsh_ versions of read, write, and
 close, from here.

 strings.c - handles accessing *.STR files, including
 caching.

 subacc.c - handles accessing message base data files,
 primarily to resynchronize when they are changed by
 another instance.

 utility.c - generic utility functions

 xfer.c - most common transfer section commands

 lilo.c - handles logging users on and off the system.

 netsup.c - holds higher-level WWIVnet services than those
 in connect1.c.

 Many others should be obvious by their name: batch.c,
 chnedit.c, conf.c, defaults.c, etc.

 4.3.C  Common functions:

 char getkey() - waits for, and returns one character of


                            -9-



 input

 void input(char *s, int len) - inputs len characters
 (uppercase only) to string s.

 void inputl(char *s, int len) - same as input, but allows
 lowercase.

 int yn() - returns 1 for yes, 0 for no.  C/R=no

 int ny() - same as yn(), but C/R=yes

 void ansic(int n) - selects a color (if user supports
 ANSI).  n is 0 to 7.

 char onek(char *s) - pass it a string, and it allows the
 user to hit one key in the string, which it returns.  ie,
 you want Delete, Ignore, Retry, so you do onek("DIR"),
 and it will return D, I, or R.  If the user hangs up, it
 returns the first character, so if one option is Quit,
 have the Q first.

 void prt(int i, char *s) - selects color i, prints string
 s, returns to color 0.

 void nl() - does a carriage return/line feed - go to new
 line.

 void npr(char *, ...) - works the same as printf() does,
 only puts the output to the com port, also.

 void pl(char *s) - prints string s, with a cr/lf on end

 void outstr(char *s) - prints s, no cr/lf on end

 void pla(char *s, int *abort) - prints s, allowing abort.
 Pass pointer to an integer, if user aborts, *abort will
 be 1, and output is terminated.  You MUST initialize
 *abort to zero.

 void outs(char *s) - outputs a string, to the screen only
 (not to remote user).

 void tleft(int x) - updates time left display at top of
 screen.  If x is non-zero, the user will be hung up on if
 his time is expired.  If x is zero, time display will be
 updated, but user won't be hung up on.



                            -10-



 void topscreen() - updates top of screen info.

 char *mmkey(int n) - inputs data for the main menu.  see
 odc below.

 void *malloca(unsigned long nbytes) - allocates space,
 does appropriate logging of out of memory errors.

 void stuff_in(...) - creates a commandline for an
 external program by "stuffing in" arguments.

 int so(void) - returns non-zero if the sysop (sl=255) is
 the current user (or the sysop hit the temp sysop key).

 int cs(void) - returns non-zero if a co-sysop is the
 current user (typically, sl>=100, but is settable in the
 SL editor in INIT).

 unsigned int finduser(unsigned char *s) - converts a user
 name to a user number.

 void sysoplog(char *s) - loggs a message to the sysop's
 log

 void dump() - dumps all pending data from the modem.

 checkhangup() - checks to see if the remote user has hung
 up.

 int printfile() - prints a file from the gfiles directory.

 void printmenu(int i) - prints a numbered menu.

 char *get_string(int n) - returns string #n from the
 current bbs.str.

 int okansi(void) - returns non-zero if ansi graphics is
 currently turned on.

 void read_user(unsigned int un, userrec *u) - read's a
 user's information from user.lst

 void write_user(unsigned int un, userrec *u) - writes a
 user's information back out to user.lst

 unsigned char *nam1(...) - gives a nice description of
 a user ("John Doe #123 @456")



                            -11-



 double nsl(void) - Number of Seconds Left for the user
 for this call.

 void changedsl(void) - re-sets-up many tables, when a
 user's SL has changed.

 void wait1(long l) - pauses for l ticks (1 tick is 1/18.2
 of a second).

 double freek1(char *s) - returns the number of free k on
 the drive where the specified file resides.

 int exist(char *s) - non-zero if the named file exists
 (or, with a wildcard, if any file matches).

 void giveup_timeslice(void) - gives up a timeslice to the
 current multitasker.  If you are writing code, you should
 call giveup_timeslice() if you find that you hit an idle
 time, to allow other programs to use that time.

 void read_status(void) - reads status.dat.  Before
 accessing anything in the "status" global status
 structure, you should call read_status() to make sure the
 info is up-to-date (and hasn't been updated by another
 instance).

 void lock_status(void) / void save_status(void) - To
 update status.dat, first call lock_status(), then update
 the field, then call save_status().  Try to avoid
 assuming that the status hasn't changed, unless you've
 protected it by lock_status()/save_status().

 int okfn(char *s) - tells you if the filename is "OK."
 That is, someone didn't enter a filename to extract or
 upload that could harm your system.

 char *make_abs_cmd(char *out) - Finds where an exectuable
 actually is, and makes the commandline "absolute."  That
 is, if you say "pkunzip \bbs\dloads\misc\asdf.zip *.doc",
 it would resolve that to "c:\dos\util\pkunzip
 \bbs\dloads\misc\asdf.zip *.doc", for security reasons.
 Typically, for an external program, you'll want to call
 stuff_in() with some values, then make_abs_cmd() to make
 sure it's safe.

 void dliscan(void) - opens up disk files for the current
 xfer section



                            -12-



 int recno(char *s) / int nrecno(char *s, int i1) -
 searches the xfer database of the current directory for a
 file match.  recno() returns the record number of the
 first match, and nrecno (passed the first or most recent
 match) will find the next one.

 void sublist(void) / void dirlist(void) - list out the
 subs (or dirs) available to the current user.

 void val_cur_user(void) - is the F1 key user editor

 int extern_prog(char *cmdline, unsigned short flags) -
 runs an external program.  The flags are EFLAG_ #defines
 from vardec.h that can be |-d together.


 4.3.D  global variables:

 int using_modem - is non-zero if there is a remote user

 int hangup - is non-zero if the user has hung up.  MUST
 BE AN EXIT CONDITION FOR ALL LOOPS THAT DO I/O.

 userrec thisuser - holds information about the current
 user

 int usernum - holds user number of current user

 configrec syscfg - holds system configuration.  SHOULD
 NOT BE MODIFIED IN PROGRAM.  The data in here should be
 changed ONLY in init, the main BBS should use this as
 READ-ONLY.

 configoverrec syscfgovr - override information for syscfg
 info.  Used to allow instance-specific settings for such
 things as com port info, etc.

 statusrec status - holds current stats information.  See
 lock_status() discussion above for correct access
 mechanism.

 char odc[81] - If you want to have an input like the main
 menu (ie, certain characters mean get a second character,
 ie, you hit O at main menu, it goes right to that
 function, hitting / will get another character), set odc
 to a string containing the characters you wish a second
 character for, then call mmkey(2) - will return a pointer
 to a string for the data entered.


                            -13-




 ie, if you want to enter a number 1-19, you have to get a
 second character if the user hits one, so you'd say:

 char *ss;

 strcpy(odc,"1"); ss=mmkey(2);

 Then ss can point to a string "1", "5","15","1X",
 "G","19", etc.

 char curspeed[80] - string holding current baud rate in
 use, can be "KB","300","1200","2400","9600", or "19200",
 or "RIP/14400/V.32/LAPM/V.42bis"

 char cdir[81] - the full main BBS directory path.

 char *languagedir, *net_data - should be used for finding
 language or net specific data.  These can change while a
 user is logged on.

 curdir - current directory, index into udir[].
 cursub - current sub, index into usub[].
 curldir - index into directories[].
 curlsub - index into subboards[].
 usub[]/udir[] - information on currently available
 subs/dirs
 subboards[]/directories[] - information on all subs and
 dirs in the system.

 Be sure not to get curdir/curldir or cursub/curlsub
 confused.  They point into different arrays.  You should
 never convert any of the indexes into numbers for display
 to a user.  To display that, look in
 usub/udir[curlsub/curldir].keys.


 4.4  Contacting the Author

 OK, that's all I can think of for now.  Any questions, or
 comments, please f-back me on my system, 310-798-9993--
 300/1200/2400/V.32bis/HST/24 hrs.  Anything you think I
 left out or could expand upon more, tell me, and I'll
 have that in the next version of the source docs.  If you
 wish to write me via US mails, write to Wayne Bell care
 of

 WWIV Software Services


                            -14-



 PO Box 720455
 McAllen, TX  78504-0455















































                            -15-