@database "MAXs BBS linkable library for GCC"
@width 80
@index index
@node main "MAXs BBS linkable library for GCC"

@{B}A MAXs BBS door library for GCC.@{UB}

Contents

        @{"Introduction" link intro}
        @{"Creating doors" link create}		Making doors with this library.
	@{"Functions" link funcs}		Door library functions.
	@{"Global Variables" link globs}	Variables you may need to use.
        @{"Other Compilers" link other}

	@{"License etc." link cont}		Read this last...
	@{"Copyright" link copy}
@endnode
@node intro "Introduction"

Hi, I've had this a while now, but never got round to writing docs. Anyway,
its a link library for making MAXs doors. These doors can run each other
quite happily (it seems, so far - I've only ever had 3 going at once.)

The programming isn't great by any means but I haven't found any bad bugs,
so I'm just trying to make it a bit faster/smaller.

Well anyway, it should make writing your doors a bit quicker and easier.
@endnode
@node create "Making doors"

It is easy enough to make doors with this library. Just write your program
using the functions you need. The only thing you have to do is write:

	@{B}int door(int argc, char *argv[])@{UB}

instead of main(). 

All the args from main() are passed straight throughto door(). The function
main(int argc, char *argv[]) is included in the library and handles the
setting up and closing down of the door. Remember not to exit() or you could
be waiting a while for the BBS to continue.
@endnode
@node funcs "MAXs BBS linkable library - Functions"

Standard MAXs BBS Functions

	@{"AddMins" link f01}		Add/remove minutes remaining
	@{"ChangeInt" link f02}	Change int value
	@{"CheckFile" link f03}	Check file exists
	@{"CheckKey" link f04}	Check for keypress - non block
	@{"CloseDoor" link f05}	Finish door
	@{"GetAutoInsert" link f06}	Get autoinsert value
	@{"GetIntInf" link f07}	Get integer variable
	@{"GetRand" link f08}		Generate random int
	@{"GetString" link f09}	Get string variable
	@{"HotKey" link f10}		Get a keypress with prompt
	@{"Menu" link f11}		Do menu function
	@{"Print" link f12}		Print a string
	@{"PrintFile" link f13}	Print a text/ansi file
	@{"PrintGR1" link f14}	Print file with .GR1 suffix (?)
	@{"PrintLocal" link f15}	Print string to local
	@{"Prompt" link f16}		Prompt with string
	@{"PutLocal" link f17}	Put character to local
	@{"PutModem" link f18}	Put character to remote
	@{"PutScreen" link f19}	Put character to screen
	@{"SetLevel" link f20}	Set new access level
	@{"SPrompt" link f21}		Prompt
	@{"Twit" link f22}		Twit user

Other Functions

	@{"newdoor" link o01}		Run a door (compiled with this lib)
	@{"SendPort" link o02}	Send data to BBS port.
@endnode
@node f01 "AddMins"

USAGE:

	void AddMins(int mins)

Adds minutes to the time remaining. A negative value will subtract.
@endnode
@node f02 "ChangeInt"

USAGE:

	void ChangeInt(int type, long value)

Changes the int variable specified by @{I}type@{UI} to its new value.
@endnode
@node f03 "CheckFile"

USAGE:

	int CheckFile(char *filename)

Checks to see if the filename is in the MAXs filebase. Returns -1 on failure,
and 1 on success.
@endnode
@node f04 "CheckKey"

USAGE:

	char CheckKey()

This function will check for a keypress without waiting. It returns either the
value of the key being pressed, or '\0'.
@endnode
@node f05 "CloseDoor"

USAGE:

	void CloseDoor()

This is not really a function for public use, as it is automatically called when
door() returns. It sends the quit message to the BBS anyway.
@endnode
@node f06 "GetAutoInsert"

USAGE:

	char *GetAutoInsert(char letter)

This returns gets the relevant % insert for the character. As some of the values
are strings, it returns (char*) so use atoi().
@endnode
@node f07 "GetIntInf"

USAGE:

	int GetIntInf(type)

This function will return the int value specified by @{I}type@{UI}
@endnode
@node f08 "GetRand"

USAGE:

	int GetRand(int max)

Returns a random number between 0 and the specified maximum.
@endnode
@node f09 "GetString"

USAGE:

	char *GetString(int type)

This will return a string variable based on @{I}type@{UI}.
@endnode
@node f10 "HotKey"

USAGE:

	char HotKey(char *prompt)

Prints up a prompt and then waits for a key to be pressed.
@endnode
@node f11 "Menu"

USAGE:

	void Menu(int func, int extra, char string)

This will execute a maxs menu function given as @{I}func@{UI}, passing the
values @{B}extra@{UB} and @{B}string@{UB} (As in the Menu editor). 
@endnode
@node f12 "Print"

USAGE:

	void Print(char *text)

Sends a line of text to the terminal.
@endnode
@node f13 "PrintFile"

USAGE:

	void PrintFile(char *filename)

This will attempt to open the file given in @{I}filename@{UI} and then print
it to the screen.
@endnode
@node f14 "PrintGR1"

USAGE:

	void PrintGR1(char *filename)

I don't really know what this function is for so I included it just in case
it is actually useful. It will append the suffix @{B}.gr1@{UB} to the file
name, and try to open the file for printing. I'd like to know more about this.
@endnode
@node f15 "PrintLocal"

USAGE:

	void PrintLocal(char *text)

This will print a line of text on the local terminal only.
@endnode
@node f16 "Prompt"

USAGE:

	char *Prompt(char *prompt, int chars)

This sends the line of text to the screen, and gets a line of text with no more
than @{I}chars@{UI} characters.
@endnode
@node f17 "PutLocal"

USAGE:

	void PutLocal(char letter)

Sends a single char to the local terminal only.
@endnode
@node f18 "PutModem"

USAGE:

	void PutModem(char letter)

Sends a single char to the remote terminal only.
@endnode
@node f19 "PutScreen"

USAGE:

	void PutScreen(char letter)

Sends a single char to the terminal.
@endnode
@node f20 "SetLevel"

USAGE:

	void SetLevel(int access)

This changes the access level to a new value.
@endnode
@node f21 "SPrompt"

USAGE:

	char *SPrompt(char *prompt, int chars)

Prompts user with text, as Prompt(). '/' will cause separated lines, but
not in MAXs :( .
@endnode
@node f22 "Twit"

USAGE:

	void Twit()

This will force the current user off line. Make sure you are checking carrier
or are not in a loop if you use this.
@endnode
@node o01 "newdoor"

USAGE:

	int newdoor(char *command)

Execute a door on top of the existing one. The return value is that of the
door being run. It will append the node number to the args automatically.

Just like system() really. Only for doors.

Example:

	rval=newdoor("doors:command arg1");
@endnode
@node o02 "SendPort"

USAGE:

	void SendPort()

Send contents of message to the BBS and receive reply in @{"MsgRet" link g02}
@endnode
@node globs "MAXs BBS linkable library - variables"

Global variables for general use.

	@{"node" link g01}		Current node door is running on.
	@{"MsgRet" link g02}		Reply message from MAXs
	@{"MAXDoor" link g03}		The message to send.
@endnode
@node g01 "Node number"
If your door needs to know which node it is on, use the int variable @{I}node@{UI}
to pass that information.
@endnode
@node g02 "MAXs reply messages"
Sometimes a return value (or void) isn't enough. After each function call, the
variable MsgRet points to the reply message sent by MAXs. Use it for carrier
checking & the like.
@endnode
@node g03 "MAXs message"
If you need to send a message direct, the structure is pointed to by @{I}MAXDoor@{UI}.
@endnode
@node other "Other compilers"
GCC and other compilers don't seem to like each others object files. Some Amiga
users and GCC also do not get on too well. As an afterthought I added some
files that can be linked with Storm C projects but don't expect miracles as
I don't really know how to use Storm/create libraries for it.

If you want to convert it to another compiler & neither lib works, send
an email to @{B}rich@theforest.demon.co.uk@{UB}
@endnode
@node cont "License.."
Feel free to write lots of new doors, update existing ones etc.
Maybe send me an email -> @{B}rich@theforest.demon.co.uk@{UB} especially if
you find bugs, or want another function added or whatever.
@endnode
@node copy "Copyright notice"
Copyright 1997-8 © R. Smith.
@endnode
@node index "Index"
@endnode