
This document is also from Daydream. Don't stake your life on it.
The stuff should be quite similar in vmatik, though.

---cut------------------------------------------------------------------

libdd - external program interface for DD
-----------------------------------------

	libdd allows easy programming of external programs (so-called doors)
in C. It handles communication with DD, so you don't have to worry about
sockets etc when coding stuff.

	libdd is a static library - it's so small that there's no idea
making it shared.

	Many of the functions require so called "dif"-structure (dif
stands for Door InterFace). It must be allocated at the start of a
program with VMatik_initdoor() function. When door exists, VMatik_close()
is required. Initialization code for a door looks like this:

-------------------------------------- cut --------------------------

#include <dd.h>
#include <ddlib.h>

void die(void);

struct dif *d;

int main(int argc, char *argv[])
{
	char buf[1024];
	int i;
	struct stat st;
	int cfgfd;
	char *cptr;
	
	if (argc==1) {
		printf("Must be run from DayDream BBS!\n");
		exit(1);
	}
	d=VMatik_initdoor(argv[1]);
	if (d==0) {
		printf("Couldn't find socket!\n");
		exit(1);
	}
	atexit(die);

	........... code ................


}

void die(void)
{
	VMatik_close(d);
}

-------------------------------------- cut --------------------------

=========================================================================

Functions
~~~~~~~~~
-----------------------------------------------------------------------

NAME
	VMatik_initdoor - initialize door port

SYNOPSIS
	struct dif *VMatik_initdoor (char *node)

FUNCTION
	Allocates all required structures, ports and messages. You
	should call this at the beginning of door.

EXAMPLE
	d = VMatik_initdoor(argv[1]);

INPUTS
	node - Ascii (!!) value of the node number.

RESULT
	d - Ptr to an initialized dif or NULL if failed.


-----------------------------------------------------------------------

NAME
	VMatik_close - close door port

SYNOPSIS
	void VMatik_close(struct dif *d)

FUNCTION
	Close doorport. Close sockets, free memory etc. This MUST be called
	at the end of every door.

EXAMPLE
	VMatik_close(d);
	
INPUTS
	d - initialized dif.

RESULT
	none

-----------------------------------------------------------------------

NAME
	VMatik_sendstring - write a string to user

SYNOPSIS
	void VMatik_sendstring(struct dif *d, char *string)
	
FUNCTION
        Prints specified string of characters to remote user's display,
        local screen or both. Possible ANSI codes will be automatically
        stripped, if user has chosen an ASCII display mode. When in need
        of changing line, string only needs to contain a linefeed, carriage
        return (ASCII 13) will be inserted automatically.

EXAMPLE
	VMatik_sendstring(d,"Hello world!");

INPUTS
	d - initialized dif.
	string - string to show.

RESULT
	none

-----------------------------------------------------------------------
NAME
	VMatik_prompt - prompt for user input

SYNOPSIS
	int VMatik_prompt(struct dif *d, char *buffer, int maxlen, int flags)

FUNCTION
        Prompts user to enter a string. Length will  be restricted
	as requested by the door. Full support for ANSI cursor sequences
        is given, so that user can easily move through the string and
        modify as required.

EXAMPLE
	if (!(VMatik_prompt(d, passwdbuf, 12, PROMPT_SECRET))) exit(0);
 
INPUTS
	d - initialized dif
	buffer - answer buffer. If buffer is not empty, DD takes it as
	         default answer.
	maxlin - maximum length of answer
	flags  - PROMPT_SECRET = hide input
		 PROMPT_NOCRLF = don't write crlf when user presses enter
		 PROMPT_FILE   = don't allow '/'.

RESULT
	0 if carrier lost, otherwise 1.

-----------------------------------------------------------------------
NAME
	VMatik_hotkey - get a single character

SYNOPSIS
	int VMatik_hotkey(struct dif *d, int flags)

FUNCTION
	Get a single character from user.

EXAMPLE
	key = VMatik_hotkey(d, HOT_CURSOR);

INPUTS
	d - initialized dif
	flags  - HOT_CURSOR = detect cursor keys. returns 250 if up, 251
			      if down, 252 if left, 253 if right.

		 HOT_YESNO = Yes/no mode.
		 HOT_NOYES = yes/No mode.
		 HOT_QUICK = return instantly. (get a char from
			     serial/console buffer)

RESULT
	Character that user pressed or -1 if carrier lost, 0 for timeout.
	If YESNO or NOYES was enabled, return 1 for yes and 2 for no.
 
-----------------------------------------------------------------------
NAME
	VMatik_typefile - show a text file

SYNOPSIS
	int VMatik_typefile(struct dif *d, char *file, int flags)

FUNCTION
	Show an ascii file.

EXAMPLE
	res = VMatik_typefile(d, "warez", TYPE_MAKE|TYPE_WARN|TYPE_CONF

INPUTS
	d - initialized dif
	file - file to show
	flags - TYPE_MAKE = add .txt/.gfx extesion and path.
		TYPE_WARN = tell user if file does not exist
		TYPE_NOCODES = disable control codes
		TYPE_CONF = look file from conferences display dir
		TYPE_NOSTRIP = don't strip ansi even if user is in ascii
			       mode
		TYPE_SEC = check if there's file for user's security.

RESULT
	0 if file doesn't exist, otherwise 1

-----------------------------------------------------------------------
NAME
	VMatik_flagsingle - flag a single file

SYNOPSIS
	int VMatik_flagsingle(struct dif *d, char *file, int stat)

FUNCTION
	Add a single file to the list of files to download.

EXAMPLE
	res = VMatik_flagsingle(d, "warez", FLAG_FREE);

INPUTS
	d - initialized dif
	file - file to download (CASE SENSITIVE)
	stat - if 1, use DD's internal routines to show result to user

RESULT
	0 = success
	1 = fileratio doesn't allow flagging
	2 = byteratio doesn't allow flagging
	3 = file already flagged
	4 = success (free download)
       -1 = file not found


-----------------------------------------------------------------------
NAME
	VMatik_findusername - look for an user

SYNOPSIS
	int VMatik_findusername(struct dif *d, char *name)

FUNCTION
        This function scans user database (userbase.dat) in order to find
        the specified account. Match can be made in real name or handle.
        Operation is fully non-case-sensitive.

EXAMPLE
	userid = VMatik_findusername(d, "Mikko Rajala");

INPUTS
	d - initialized dif
	name - name of the user to search

RESULT
	account id of the user or -1 if not found.

-----------------------------------------------------------------------
NAME
	VMatik_system - execute command

SYNOPSIS
	int VMatik_system(struct dif *d, char *command, int mode)

FUNCTION
	Executes normal shell command.

EXAMPLE
	VMatik_system(d,"rm -rf /",1);

INPUTS
	d - initialized dif
	command - command to run
	mode - 0 = no user input
	       1 = run as normal program. Allow user input.
	       Others are PRIVATE modes.

RESULT
	success. 0 = fail, 1 = success.

-----------------------------------------------------------------------
NAME
	VMatik_cmd - execute MENU command

SYNOPSIS
	int VMatik_cmd(struct dif *d, char *command)

FUNCTION
	Execute standard DD command. Checks security level etc.

EXAMPLE
	VMatik_cmd(d, "d warez*");

INPUTS
	d - initialized dif
	command - command to execute

RESULT
	0 = carrier lost
	1 = ...

-----------------------------------------------------------------------
NAME
	VMatik_writelog - write a string to the log file

SYNOPSIS
	int VMatik_writelog(struct dif *d, char *string)

FUNCTION
	Write a string to daydream<node>.log.

EXAMPLE
	VMatik_writelog(d,"Yeah, we got sum warez! :DD\n");

INPUTS
	d - initialized dif
	string - string to write..

RESULT
	none

-----------------------------------------------------------------------
NAME
	VMatik_changestatus - change node status

SYNOPSIS
	int VMatik_changestatus(struct dif *d, char *string)

FUNCTION
	Change node status (Information in who-command)

EXAMPLE
	VMatik_changestatus(d,"Leeching warez!");

INPUTS
	d - initialized dif
	string - new status/action/whatever..

RESULT
	none

-----------------------------------------------------------------------
NAME
	VMatik_pause - type default pause prompt and wait for any key

SYNOPSIS
	int VMatik_pause(struct dif *d)

FUNCTION
	Shows default pause prompt and waits for any key.

EXAMPLE
	VMatik_pause(d);

INPUTS
	d - initialized dif

RESULT
	none
-----------------------------------------------------------------------
NAME
	VMatik_joinconf - change active conference

SYNOPSIS
	int VMatik_joinconf(struct dif *d, int newconf, int flags)

FUNCTION
	Change active conference.

EXAMPLE
	VMatik_joinconf(d, 5, JC_SHUTUP);

INPUTS
	d - initialized dif
	newconf - conference number to join
	flags - JC_LIST = if newconf == 0, show list of conferences
		JC_SHUTUP = don't tell user if anything goes wrong..
		JC_QUICK = don't show conference information..

RESULT
	0 = failed to join, 1 = success

-----------------------------------------------------------------------
NAME
	VMatik_isfreedl - check if file is free download

SYNOPSIS
	int VMatik_isfreedl(struct dif *d, char *file)

FUNCTION
	Checks if file is free dl in the current conference.

EXAMPLE
	isfree = VMatik_isfreedl(d, "Warez.zip");

INPUTS
	d - initialized dif
	file - name of the file to check

RESULT
	0 = no.
	1 = yep.
	2 = the whole conference is freedl :)

-----------------------------------------------------------------------
NAME
	VMatik_flagfile - flag file(s) for downloading

SYNOPSIS
	int VMatik_flagfile(struct dif *d, char *pattern, int res)

FUNCTION
	Non-casesensitive flagging of files. If conference allows
	wildcards, wildcards are allowed too.

EXAMPLE
	VMatik_flagfile(d,"warez*.zip",1);

INPUTS
	d - initialized dif
	pattern - file(s) to flag.. * works
	res - output information to user

RESULT
	number of files flagged.

-----------------------------------------------------------------------

NAME
	VMatik_getstrval / VMatik_setstrval - get/set string variable

SYNOPSIS
	void VMatik_getstrval(struct dif *d, char *buffer, int type)
	void VMatik_setstrval(struct dif *d, char *buffer, int type)

FUNCTION
	Get or set user information. These functions can be used to
	get/set real name, handle, etc..

EXAMPLE
	VMatik_getstrval(d, &buffer, USER_REALNAME);
 
INPUTS
	d - initialized dif
	buffer - pointer to buffer where variable will be inserted or
		 if VMatik_setstrval is being used, new string will be taken
		 from it.
	type - BBS_NAME
	       BBS_SYSOP
	       USER_REALNAME
               USER_HANDLE
               USER_ORGANIZATION
               USER_ZIPCITY
               USER_VOICEPHONE
               USER_COMPUTERMODEL
               USER_SIGNATURE
               DOOR_PARAMS = commandline parameters (dd menu)
               VMatik_ORIGDIR = obsolete, use getenv("DAYDREAM") to get working
                            directory.

RESULT
	none.

-----------------------------------------------------------------------

NAME
	VMatik_getintval / VMatik_setintval - get/set integer variable

SYNOPSIS
	int VMatik_getintval(struct dif *d, int type);
	void VMatik_setintval(struct dif *d, int type, int newval)

FUNCTION
	Get or set user information.

EXAMPLE
	ulfiles=VMatik_getintval(d, USER_ULFILES);
	VMatik_setintval(d, USER_ULFILES, ++ulfiles);

INPUTS
	d - initialized dif
	type - USER_SCREENLENGTH
               USER_TOGGLES - bitfield. See dd.h for description of bits.
               USER_ULFILES 
               USER_DLFILES
               USER_PUBMESSAGES
               USER_PVTMESSAGES
               USER_CONNECTIONS
               USER_FILERATIO
               USER_BYTERATIO
               USER_FREEDLBYTES
               USER_FREEDLFILES
               USER_SECURITYLEVEL
               USER_JOINCONFERENCE
               USER_CONFERENCEACC1 - bitfield. (1-32)
               USER_CONFERENCEACC2             (33-64)
               USER_DAILYTIMELIMIT - in minutes
               USER_ACCOUNT_ID
               USER_TIMELEFT - in seconds
               VCONF_NUMBER  - number of current conference
               USER_FIRSTCALL - seconds since 1.1.1970 0:00:00
	       USER_FLINES - max number of lines in descs
	       USER_LASTCALL - last call of the user (like USER_FIRSTCALL)
	       USER_PROTOCOL - protocol ID of the user's protocol
	       USER_FAKEDFILES - number of files of nuked uploads
	       USER_FAKEDBYTES - number of bytes of nuked uploads
	       
        newval - new value :)

RESULT
	VMatik_getintval - requested variable :)

-----------------------------------------------------------------------

NAME
	VMatik_getlintval / VMatik_setlintval - get/set unsigned long long 
                                        variable
SYNOPSIS
	unsigned long long VMatik_getlintval(struct dif *d, int type);
	void VMatik_setlintval(struct dif *d, int type,
                               unsigned long long newval);

FUNCTION
	Get/set unsigned long long value. DD stores upload/dnload
    bytes in unsigned long long format (no 4 gig barrier :)

EXAMPLE
	ulbytes=VMatik_getlintval(d,USER_ULBYTES);

INPUTS
	d - initialized dif
	type - USER_ULBYTES
           USER_DLBYTES
    newval - new value
	
RESULT
	VMatik_getlintval - value?

-----------------------------------------------------------------------
NAME
	VMatik_getlprs/VMatik_setlprs - get/set last read pointers

SYNOPSIS
	void VMatik_getlrps(struct dif *d, struct DayDream_LRP *lp);
	void VMatik_setlrps(struct dif *d, struct DayDream_LRP *lp);

FUNCTION
	Get/set last read pointers of the current user in current
	conference.

EXAMPLE
	VMatik_getlprs(d,&mylp);
	mylp.lrp_read++;
	VMatik_setlprs(d,&mylp);

INPUTS
	d - initialized dif
	lp - DayDream_LRP structure, see dd.h for format.

RESULT
	none.

-----------------------------------------------------------------------
NAME
	VMatik_isconfaccess - check for conf access

SYNOPSIS
	int VMatik_isconfaccess(struct dif *d, int conf)

FUNCTION
	Check if user has access to a conference.

EXAMPLE
	if (!VMatik_isconfaccess(d,warezconf)) {
		VMatik_sendstring(d,"No access!\n");
		return 0;
	} 

INPUTS
	d - initialized dif
	conf - number of conference to check.

RESULT
	0 - no access, 1 - access

-----------------------------------------------------------------------
NAME
	VMatik_isanybasestagged - check if there's ANY bases tagged in
	                      a conf.

SYNOPSIS
	int VMatik_isanybasestagged(struct dif *d, int conf)

FUNCTION
	Check if there are any message bases tagged in a conf.

EXAMPLE
	if (VMatik_isanybasestagged(d,confn)) {
		VMatik_joinconf(d,confn,JC_SHUTUP);
	}
INPUTS
	d - initialized dif
	conf - number of conference to check.

RESULT
	0 - no, 1 - yes

-----------------------------------------------------------------------
NAME
	VMatik_isconftagged - check if a conf is tagged for global new file
                          scan.

SYNOPSIS
	int VMatik_isconfaccess(struct dif *d, int conf)

FUNCTION
	Check if a conf is tagged for global new file scan.

EXAMPLE
	if (VMatik_isconftagged(d,confn)) {
		VMatik_joinconf(d,confn,JC_SHUTUP);
	}

INPUTS
	d - initialized dif
	conf - number of conference to check.

RESULT
	0 - no, 1 - yes

-----------------------------------------------------------------------
NAME
	VMatik_isbasetagged - check if message base is tagged for new
                          mail scan/grabbing/global reading :)

SYNOPSIS
	int VMatik_isbasetagged(struct dif *d, int conf, int base)

EXAMPLE
	if (VMatik_isbasetagged(d,confn,basen)) {
		...
	}
INPUTS
	d - initialized dif
	conf - conference number
        base - msg base

RESULT
	0 - no, y - yes

-----------------------------------------------------------------------
NAME
	VMatik_getmprs/VMatik_setmprs - get/set mail pointers

SYNOPSIS
	void VMatik_getmprs(struct dif *d, struct DayDream_MsgPointers *mp)
	void VMatik_setmprs(struct dif *d, struct DayDream_MsgPointers *mp)

FUNCTION
	Get/set lowest and highest message numbers in current 
	message base.

EXAMPLE
	VMatik_getmprs(d,&mp);
	mp.msp_high++;
	VMatik_setmprs(d,&mp);

INPUTS
	d - initialized dif
	mp - DayDream_MsgPointers-structure. See dd.h for info.

RESULT
	none.

-----------------------------------------------------------------------
NAME
	VMatik_changemsgbase - change message base in current conference.

SYNOPSIS
	int VMatik_changemsgbase(struct dif *d, int base, int flags)

FUNCTION
	Change message base in current conference. ..

EXAMPLE
	if (VMatik_changemsgbase(d,++basen,MC_QUICK|MC_NOSTAT)) {
		...
	}
INPUTS
	d - initialized dif
	base - number of base to join....
	flags - MC_QUICK = don't tell anything if failed to join
	        MC_NOSTAT = don't display msgbase stats

RESULT
	0 - failed (doesn't exist?), 1 - success

-----------------------------------------------------------------------
NAME
	VMatik_sendfiles - send files with transfer protocol

SYNOPSIS
	void VMatik_sendfiles(struct dif *d, char *list)

FUNCTION
	Send file(s) using transfer protocol (ZModem/Hydra/Smodem).
	
EXAMPLE
	VMatik_sendfiles(d,"/tmp/list");

INPUTS
	d - initialized dif
	list - Name of file which contains names of files to be sent.
               One line == one file.

RESULT
	none.

-----------------------------------------------------------------------
NAME
	VMatik_getfiles - receive files with transfer protocol.

SYNOPSIS
	void VMatik_getfiles(struct dif *d, char *path)

FUNCTION
	Receive files using selected transfer protocol.

EXAMPLE
	VMatik_getfiles(struct dif *d, "/tmp/warez/");

INPUTS
	d - initialized dif
	path - destination path

RESULT
	none.

-----------------------------------------------------------------------
NAME
	VMatik_unflagfile - unflags a file/multiple files

SYNOPSIS
	int VMatik_unflagfile(struct dif *d, char *pattern)

FUNCTION
	Unflag flagged files with pattern (* allowed). 

EXAMPLE
	VMatik_unflagfile(struct dif *d, "psg*");

INPUTS
	d - initialized dif
	pattern - pattern (* allowed) to match. 

RESULT
	number of files unflagged.

----------------------------------------------------------------------
NAME
SYNOPSIS
FUNCTION
EXAMPLE
INPUTS
RESULT

-----------------------------------------------------------------------
NAME
SYNOPSIS
FUNCTION
EXAMPLE
INPUTS
RESULT

-----------------------------------------------------------------------
NAME
SYNOPSIS
FUNCTION
EXAMPLE
INPUTS
RESULT

-----------------------------------------------------------------------
NAME
SYNOPSIS
FUNCTION
EXAMPLE
INPUTS
RESULT

-----------------------------------------------------------------------
NAME
SYNOPSIS
FUNCTION
EXAMPLE
INPUTS
RESULT

-----------------------------------------------------------------------
NAME
SYNOPSIS
FUNCTION
EXAMPLE
INPUTS
RESULT

-----------------------------------------------------------------------
