What's Up Status System
Copyright 1994 Arthur Ward

This document applies to the source code as it exists in the 1.xx versions.
Theoretically it will remain the same long into the future.


                      User contributed status modules

    If you have knowledge of C programming, you are welcome to write your
own module to be included in What's Up in a new version. First off, this is
open *only* for C code and nothing else (no C++, no Pascal, just straight
C). Second, it should compile under Borland C++ 4.0 with a minimum of
changes or else it may be rejected. Thirdly, it should use ANSI calls where
possible. Finally, the Borland conditionals may be used if you need calls
that are different between platforms, and you should also tell me if your
code will only work under DOS or Windows, etc.

    *IMPORTANT*
    Once contributed, your code is considered part of the project!
    To keep things simple, any received donations will *not* be divided
    among contributors! At any time in the future if this program becomes
    commercial or shareware, income from purchases/registrations will not
    be divided.
    On the other hand, you will get a blurb in the docs as long as your
    code/advice/whatnot is in use.
    If you wish your source to remain non-public domain (ie. between the
    people working on the What's Up projects only) in the event that other
    sources are released, mark it clearly on everything.

    This policy may or may not change. Assume that you are releasing code
    into the public domain for no charge when writing.

    The system is very easy to deal with: Your routine will be called every
time the display is updated in order to generate an entirely new listing.
There is no correspondence between one update and another, they are all
generated fresh. Because your routine will be called at potentially high
frequencies (once or twice a second, with others needing to run, plus
display & time release to multitasker), it should work quickly.

    Configuration: Provide me with a list of items that needs to be filled
from the configuration file, and I will add them to the configuration
loader (easy). When naming your configurable variables, please remember
that they must be public to all other modules, so use a unique name (like
some mangled form of the software followed by the name of the data;
BinkOutbound, MaxIPC are some that I use already). Currently only strings
(copied from configuration as-is minus leading & trailing whitespace (as
set by isspace() ), unsigned integers, and whole-line reads (like the
UserFlag verb) have code. Others will require more time to implement.

    Source format: Your code may not remain in your source file! My style
uses 4 space tab stops for grouping (ie. the inside of {}'d code, etc.),
and when brief debugging status entries are needed from all of the modules,
the DEBUG define will be declared. If your code uses multiple procedures,
follow the guideline for configuration variables. When writing your module,
I strongly encourage you *NOT* to do anything requiring one-time
initalization/deinit setups, as there are not really any provisions for
this. If you need memory for storage, I recommend alloca() and use the
stack, although if you really need to, malloc() is OK as long as it is
freed at the end of the module. Your module will be running in the LARGE
model, so don't worry about farmalloc() or anything like that.

    Available What's Up calls:

void AddStatusItem(_status Status)

    AddStatusItem appends a new status entry to the status list, allocating
memory as needed. All you do is fill a _status structure and pass it to
AddStatusItem to have it displayed when the screen is redrawn following
the completion of all status modules. If there is insufficent memory for
AddStatusItem to complete the operation, it will simply ignore all new
status entries. (meantime, it will have changed the last available entry to
an error message so the user knows what has happened)

    Available structures 'n stuff:

typedef struct {
	char	Name[ST_NAMELEN],  		/* Name of program/user/whatever */
			Status[ST_STATLEN];		/* Whassup */
} _status;

Obviously, this is the structure that holds each entry. ST_NAMELEN and
ST_STATLEN are two defines that contain the size of the Name & Status
fields (respectively), including the null terminator.


Ta-da, that's it. A whole 2 basic units to make this entire thing tick.
Have fun.

Arthur Ward
May 26, 1994
(revised slightly June 23, 1994)
(revised slightly December 18, 1994 for 1.02)