Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

User Services

Security (Locks & Keys)

As explained in Sysop’s Guide, security on Worldgroup the Major BBS is controlled at the foundation level by Locks and Keys.

...

SYSOP Top-level access to the Worldgroup Major BBS server

This routine checks if the current user has the specified key.

...

This routine is universal — it will tell you if the user has this key, and it will work whether the user is online or not.

Registerable Pseudo-Keys

You can create your own pseudo-keys for users. Say you want to give users access to some feature based upon something. The standard method of locks and keys allows Sysops to make up key names and issue keys either directly to individual users, or to classes of users via the class keyring. But some situations require more flexibility. For example, the _PORT#xx pseudo-key implicitly gives each user a special key based upon the channel number he uses for his current session.

...

By convention, and for Sysop sanity, all pseudo-keys start with the under_score character, but nothing enforces this.

Accounting (Credits)

User connect time can be controlled or measured with the system commodity called “credits”. Credits typically refer to seconds of privileged connect time: If an “approved” user is online for an hour he consumes 3600 credits. A new user doesn’t consume credits and can’t access many of the features of the system.

There are many other ways credits are used. Certain actions “cost” the user a fixed amount of credits. And credit consumption can vary depending on what service the user is in.

Charging Users

To charge a user credits, you can make use of the dedcrd() and tstcrd() routines in ACCOUNT.C:

...

int real; 1=don’t take debt or exemptions into account

Credit Consumption Rate

To change a user’s credit consumption rate, you can set usrptr->crdrat to the credits to consume per minute. For example:

...

Whenever a user exits a module of Worldgroupthe Major BBS, his credit consumption rate is restored to the default value (as specified by the Sysop in the MMUCRR CNF option located in Security & Accounting).

Global Commands

Global commands are commands that users can enter from almost any prompt on Worldgroupthe Major BBS. One exception: you can’t use global commands while inside the Full Screen Editor. Making your own global command means two things: making a handler routine, and registering the routine. The handler routine intercepts every line of user input and, if it recognizes your special global command, responds to it and returns true (otherwise returns false). Registering the routine allows the mainline program to call it with each line of user input.

...

CommandPurposeSource code
FINDSearch menu pagesMENUING.C and MAJORBBS.C
DISABLE (Sysop only)Disable a pageMENUING.C and MAJORBBS.C
ENABLE (Sysop only)Enable a pageMENUING.C and MAJORBBS.C

Full Screen Editor

The Full Screen Editor is a sub-service used by Electronic Mail and Forums for message editing. It allows a user to edit a block of text of a certain number of 80-column lines. See Sysop’s Guide for instructions on using the editor from the user’s point of view.

There are actually two editors, the Full Screen Editor and the Line Editor that depend on whether the user’s terminal has ANSI capability or not. Fortunately for developers, this distinction is transparent. The bgnedt() routine will make use of what the Worldgroup Major BBS server already knows about the user’s terminal, and fire up the appropriate editor.

...

* Feedback to Sysop (sample module discussed in the *

* Developer's Guide for Worldgroupthe Major BBS) *

* - RNStein *

* *

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

...

When a user selects this service, he is introduced to it with the HELLO{} message, and a (N)onstop, (Q)uit or (C)ontinue? choice. Then he enters the Full Screen Editing mode, where he types in a topic and a message. When the user presses ctrl+G, the topic and message (along with other information) are appended onto the end of the text file GALFBK.TXT. The Sysop can periodically read this file and delete it.

struct module fbkmodule

This module structure defines the text-line input entry point fbkinp(), the standard system default status handler dfsthn(), and a shutdown routine fbkfin().

struct fbkusr

This is the structure template for this module’s use of the Volatile Data Area. The body and topic of the feedback will be stored here. The fbkptr macro casts vdaptr into a pointer to an fbkusr structure, for convenient coding.

init__feedback()

This initialization routine registers the feedback module and opens the GALFBK.MCV file with the text blocks for the module. The call to dclvda() declares this module’s requirements for the size of the Volatile Data Area.

fbkinp()

This is the input text line handler for the module. It is coded with the standard command concatenation and X-to-exit features, although neither of them are actually used. They’re in there to make it easier for you to edit this source code into a module of your own. But the only action happening in fbkinp() is that when the user enters the module, he’s greeted and then shuffled straight off to the Full Screen Editor.

fbkdun()

This function is the when-done routine associated with the module’s invocation of bgnedt(). Notice that it’s identified in the bgnedt() call. If the user did not ctrl+O quit the editing, then the text is written to disk. First the \r line-terminators that the FSE uses are translated into the \n line-terminators that fprintf() likes. Then the file GALFBK.TXT is opened in append-ASCII mode. Then the User-ID, date, time, topic and message body are written to the file. Finally the user is thanked for his efforts. Returning 0 means to return to the parent menu page, as opposed to staying in this module.

Full Screen Data Entry

FSD can perform the following functions:

...

Display dataEnter data, full-screen modeEnter data, linear modeFull-screen entry mode requires ANSI capability and a large enough user screen to hold the entire template. Data displaying, or linear entry, can take place whether the user has ANSI capability or not. To use FSD with Worldgroupthe Major BBS, you’ll need to create these:

...

The title in fsdrhd() is only for smooth operation for RIPscrip users — this should simply be a character string title for viewing above the entry screen. For example, Contact Database.

Avoiding Fields

If your program needs to conditionally blank out some fields in the display, you need to (1) modify the template, and (2) flag the appropriate fields as avoid. For (1), use the tpwipe() routine on the results of fsdrft() (before passed to fsddsp()) to modify the supporting text for the appropriate fields of the template. For (2), set the FFFAVD flag for the fields to be avoided (see FSD.H) after calling fsdapr().

...

In linear entry mode, you just need to set the FFFAVD flag for the appropriate fields after calling fsdapr().

Getting Answers After a Session

After an entry session is over there are a few ways to get the answers. See FSD.H for more details.

...

int fldno; field number 0 to N-1

Handling Answers at Other Times

After a session, the data structures allocated by fsdapr() allow quick access to pieces of the answer string. But at other times, the following routines from FSD.C can be used to deal with answer strings (see FSD.H for more details):

...

For an example of a simple module that uses Full Screen Data Entry, download the file GALCTX.ZIP from the Galacticomm Demo System at (305) 583-7808.

File Transfer

Uploads

Assuming that you’ve already taken care of all interactive aspects of your application (if you haven’t, see about creating interactive modules on page 42), then here are the steps to add file uploading capability:

...

char *prot; protocol code string

...

Upload Handler Routine

...

This routine is a collection of what we call exit points. After your special-purpose module hands control over to the general-purpose file transfer service, FTF, there are several cases when FTF is going to need to consult back with your application.

...

From the remodeling analogy, this is like the decorator talking to the homeowner.

...

FUPPTH - Where would we put this file?

...

Tell me what DOS path you plan to use for this file coming up, and store that path in ftfbuf. If the protocol was capable of telling us a filename, I’ve put it in ftfscb->fname, otherwise ftfscb->fname is "". Usually you’ll return 1 in this case.

...

You could also just return 0 (and skip putting the path in ftfbuf) if you don’t plan on supporting file upload resume after abort, and don’t plan on supporting the upload-if-exists/newer/bigger options that ZMODEM is capable of.

...

FUPBEG - Begin uploading this file

...

Verify whether the user is allowed to upload this file. See ftfscb->fname and ftfscb->estbyt for the filename and size, if the protocol has supplied them. The file time and date may be in one of three forms:

...

An important feature of the file uploading service is that you can count on the fact that for every FUPBEG call, there will be exactly one call to either FUPSKP (upload of this file aborted) or FUPEND (upload of this file was successful), except in extreme cases such as power loss.

...

FUPREF - Refer to file, don't upload it

...

You’ll never get this case if you haven’t willingly and knowingly set the ftuptr->flags¦=FTFREF flag after you called fileup(). This all has to do with uploading a file by reference. Electronic Mail and the Forums have this ability. The Sysop can upload a file that already exists on the Worldgroup Major BBS server’s disk using the F file-import protocol. The file may stay where it is, and the e-mail or forum message that it’s attached to just refers to the real location of the file.

...

If you have a use for the standard upload file in your file-reference scheme, your FUPREF exit point is a good time to write to it: it’s already open and you don’t have to close it (you can use ftfrwr()). If you don’t want this file, then unlink() it in your FUPEND exit point. Don’t unlink() it in the FUPREF() exit point because the file is still open at that time, and will be closed later.

...

FUPEND - This file uploaded successfully

...

The file was uploaded successfully. The actual size of the final file is available to you in ftfscb->actbyt. If the upload was resumed using ZMODEM’s resume-after-abort feature, ftfscb->actbyt is the total bytes in the file, not just the portion stuck on in this session. There’s no way to find out whether a resume took place or not, or to figure the size of the portion.

...

I’m not expecting any return value from either your FUPEND or FUPSKP exit points, so you should return 0.

...

FUPSKP - This file upload aborted

...

The current file upload has been aborted for some reason. The size of the fragment is available to you in ftfscb->actbyt. If you don’t want fragments of aborted uploads lying around you need to delete the file now. You can do this by coming up with the file path name and passing it to unlink().

Here also, if you’ve been reserving the filename or a file handle since FUPBEG, now’s the time to unreserve it.

...

FUPFIN - End of uploading session

...

This step winds up the upload session and returns control to your regularly scheduled program. This is distinguished from FUPEND which only winds up from the upload of a single file. So for multiple file uploads there could be several FUPBEG/FUPEND pairs (or FUPBEG/FUPSKP if things didn’t work out).

...

Another handy feature of the file transfer service is that each fileup() invocation is followed (eventually) by exactly one FUPFIN or FUPHUP exit point invocation, except in dire cases (power loss for example).

...

FUPHUP - Channel hanging up

...

This is the alternative to FUPFIN that occurs when the user or the channel is hanging up for some reason in the middle of the upload session. No return value is expected, so you should return 0. You don’t need to worry about termination of the individual file upload, if one had been in progress, because FUPSKP will have been called already. But if there’s any session-level (as opposed to file-level) cleanup to be done, now’s your chance.

This brings up a tricky point that you may want to be aware of. When a user disconnects in the middle of one of your uploads, your module’s own hang-up entry point (see page 54) will be called eventually, as it always is at logoff. But you may not be able to recognize that the user was “in” your module because his usrptr->state will be that of the file transfer’s state code. One way out of this is your FUPHUP exit point. When the file transfer service’s own huprou() gets called, it will call your FUPHUP exit point in your upload handler routine. That’s when you can do your module’s last minute housekeeping on this channel.

...

Uploading Example #1

...

Here’s a very simple example of a module that uploads files onto a Worldgroup Major BBS server. Many shortcuts have been taken in this code for the sake of brevity. It uses a minimum of features, has few conveniences, and has none of the security precautions that should be in place before putting software online for users to access. Its sole purpose is to introduce you to the components of file uploading. You can download the source code and other files relevant to this example from the Galacticomm Demo System at (305) 583-7808. Look for GALUPX.ZIP in the File Libraries:

...

This module allows users to upload files into the UPLDIR subdirectory of the Worldgroup Major BBS server computer. As is the case with most modules, Sysops need to create a module page somewhere in their Menu Tree that uses it, normally the child page of some menu. When users are online and choose this service they are asked to type in a filename. When they do, control is turned over to the upload service and the user chooses a protocol. After the upload is complete, the user is returned to the parent menu page. Here is a discussion of the major components of this program.

...

struct module uplmodule

...

This module identifies only one custom entry point: uplinp() for the sttrou() text line input handler. The default status handler, dfsthn() is the stsrou() entry point for unusual status conditions.

...

init__uploader()

...

The initialization routine for this module registers the module using the description in the corresponding module definition file. It also creates the UPLDIR subdirectory to store the uploaded files, if one doesn’t exist already.

...

uplinp()

...

This routine handles text line input from the user after he selects this upload service. Upon entry, the user is prompted to enter a filename. If the user just presses enter, he is returned to the parent menu without uploading. If he types in a filename, that name is stored in his Volatile Data Area, and then he is handed over to the file transfer service. The middle parameter to fileup() is ? to give the user a list of available upload protocols.

...

fupupl()

...

This is the upload handler routine as described starting on page 150. The FUPBEG and FUPEND exit points are used by FTF to get the file’s full path name for opening the file, and for setting its time and date. The FUPFIN exit point merely restores the upload service’s state code and returns 0, which requests that the user be returned to the parent menu page. All other exit points simply return 0.

...

Potential Improvements to Upload Example #1

...

Here are some of the features left out of this brief example that you should consider if you are using uploads in your application:

...

Limits on file size and quantity in the upload directoryChecking for conflicts between the filename and DOS devicesDeleting the fragment left behind from an aborted uploadMultiple-file uploadsSysop-configurable prompts in an .MSG fileSysop-configurable upload directoryFormal declaration and limitation on VDA usageCommand concatenationAutomatic reprompt after /p page command, etc.Full module structure in source code, with commentsAll of these features are included in upload example #2.

...

Uploading Example #2

...

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

...

U * <protocol> Upload multiple files using a protocol

...

struct module uplmodule

...

In this example, the module structure is fleshed out with a helpful comment for each field. An uplfin() routine has been added to clean up before shutdown.

...

init__uploader()

...

The initialization routine does the same work as does the one in the first example, plus it also supports a Sysop-configurable directory for uploads, and reads in Sysop-configurable byte and file limits. The dclvda() call formally declares the need for enough space in the VDA to store a filename.

...

uplinp()

...

Some immediately obvious renovations are the checking for X to exit, and the use of command concatenation routines (bgncnc(), cncxxx(), endcnc()). When first entering this module, the cncchr() call helps with concatenated commands the user could have entered from the parent menu page. The user is prompted to enter a name for the uploaded file.

The UPLNAME substate handles the reaction to the upload filename prompt. The user can respond by pressing * or enter to signify that multiple files will be uploaded. But the first special case we handle is when the INJOIP flag is set, meaning we need to reprompt after a /p page message or other unexpected event. After that, parsin() reparses the input into separate margv[] words (see about how bgncnc() unparses on page 105). These are passed to an internal function, uplfil(), with default values for protocol and filename as appropriate.

...

uplfil()

...

This function translates * for filename into the "" that the first parameter of fileup() needs to signify multiple file uploads. It then proceeds to check the filename for dangerous characters like colon (:), backslash (\) and twin periods (..). There are many other (less dangerous) illegal characters for filenames, but most of these are caught eventually when FTF tries to create the file. If the filename is safe, it’s stored in the VDA and fileup() is called. Notice that the filename is checked for size limitations before writing to the VDA. Avoiding buffer overruns is a wonderful habit to get into, although we’re not exactly at high risk here.

...

fupupl()

...

In the FUPBEG exit point, we recheck for reserved names. This is necessary for multi-file uploads when we don’t know the names until this point. We also need to check file size and quantity limits since these too are dynamic. This may be a little impolite to the user to bring up this file quantity limitation so late in the game, but it must be checked for each file in a multi-file upload, so it needs to be in FUPBEG anyway.

Even this check is not completely air-tight: if two users started uploading 5 meg files at the same time, and the UPLBMAX setting is 6 meg, they will probably both be allowed to complete their uploads. That’s because the directory contents are measured only at the beginning of each upload without taking into account uploads that are already underway.

...

uplfin()

...

This routine politely closes the GALUPX2.MCV file when the Worldgroup Major BBS server shuts down.

ASCII Downloads

To dump an ASCII file to the user’s terminal, you can use:

...

Note that the (*whndun)() routine does not need to call outprf(). If it does call outprf() for any reason, it should then call clrprf() to avoid double prompting.

Downloads

Assuming that you’ve already taken care of all interactive aspects of your application, then here are the steps to take to add file downloading capability:

...

If ftgsbm() returns 1, then it has changed the usrptr->state, and either TSHFIN or TSHHUP will get invoked exactly once eventually. If ftgsbm() returns 0, then usrptr->state and usrptr->substt have either not been changed, or already restored by the TSHFIN exit point of your download handler routine.

...

Tagspecs

...

A tagspec is a 17-byte application-specific structure for keeping track of each file downloaded. Its main purpose is to allow file tagging, where a user identifies a file for download at some later time. But all files that are downloaded use tagspecs, even if they aren’t explicitly tagged.

...

Or perhaps you could restrict your application to using the same path prefix for all files. If you were desperate to give users the ability to tag up to MAXTAGS number of files, each with an arbitrary path prefix, then your application could allocate a monster 3D array, 61 bytes by MAXTAGS by nterms, and store all the path prefixes there.

...

Download Handler Routine

...

This routine is a collection of exit points for all the application-specific tasks that need to be done during the general-purpose downloading session. See page 150 for a discussion of the concept of exit points as regards the upload handler routine.

...

If you need any other global variables, be sure to set them up in your routine. The meaning of your routine’s return value depends on the type of exit point (which is coded in tshcod). These will be discussed individually for each exit point. In some cases, no return value is expected. You should return 0 in each of those cases to allow for future expansion.

...

TSHDSC - Describe the file(s) in English

...

Format a description for the single file or multiple files in the tshmsg buffer. You should word the description so that it looks right when following the word the, as in Do you want to download the %s (y/n)? (see CNF option SRETRYV in Edit Text Blocks).

The tagspec you originally submitted is in ftgptr->tagspc. This exit point must work with a multi-file tagspec, as well as the single-file tagspecs that you’ll be breaking it down into. The return value doesn’t matter, but it’s a good practice to return 0 for future expansion.

...

TSHVIS - Visible to this user?

...

Is this file visible? Return 1=visible to user, or 0=not visible.

...

If the file is visible, read the first TSHLEN bytes (80 bytes) into the tshmsg buffer. This will allow tests for a compressed file, such as a .ZIP file, to know whether or not to present the user with the V protocol choice. If you don’t read in the first TSHLEN bytes of this file, then the V protocol will never be available.

...

TSHSCN - Break down multiple filespec

...

If you submit a multi-file tagspec (by setting ftgptr->flags¦=FTGWLD), then you’ll be asked to break it down into single-file tagspecs when the time comes for downloading.

If the multi-file tagspec refers to one or more files, then return 1 and store the tagspec for the first file in the tshmsg buffer. Return 0 if the multi-file tagspec ends up referring to no files at all. You can also return 2 to indicate that there may be files available, but that you aren’t supplying a tagspec in tshmsg yet — you’ll do that in TSHNXT.

...

TSHNXT - Next file in multi-file spec

...

This continues the work that TSHSCN started. Return 1 if there are more single-file tagspecs, and store the next one in tshmsg. Return 0 if there are no more files. Return 2 if there may be more files, but you want to be called again to make a tagspec out of them. This may help simplify certain multi-file breaking-down schemes.

See the example module source code starting on page 182 for a way to do TSHSCN and TSHNXT with fnd1st() and fndnxt(). See page 325 about the routines themselves. For your convenience, ftuptr->fb is a user-specific fndblk structure that you can use with fnd1st() and fndnxt() in this context.

...

TSHBEG - Begin downloading this file

...

Verify that the user is allowed to download this file. If not, put a reason in tshmsg (a complete sentence, as in You don't have access rights to that file.) and return 0.

...

Does the filename have the proper syntax?Does the filename conflict with a reserved name?Does the user have permission to download this file?Are too many users opening files at once (thereby using up all file handles)?Can this user afford the download charges, if any?Is another user currently modifying/uploading/deleting this file?If downloading is ok, store the DOS path for the file in tshmsg and return 1. In case this protocol can communicate filenames, put the filename into ftfscb->fname. For example, if downloading with ZMODEM, this filename will be the one used on the user’s terminal. It doesn’t have to be the same as the one used on the Worldgroup Major BBS server, but it usually is.

There is another special option in the TSHBEG exit point. You can return -1 to indicate that the file is not yet available for download, but it will be later. The file won’t be downloaded during this download session, but it will remain tagged for download, and can be downloaded later. This is used to accommodate files that are not instantly available such as those on a multi-disk CD ROM drive (as opposed to those that are, such as on your hard disk).

...

TSHEND - File download was successful

...

You may wish to record the download, or charge the user for it at this point. Use this exit point to cancel whatever reserving was done in the TSHBEG entry point. For example, if you had some scheme for preventing the Sysop from deleting this file while this user was downloading it, now’s the time to recognize that it’s ok to delete the file. The return value doesn’t matter, but it’s a good practice to return 0 for future expansion.

You can count on the fact that for every TSHBEG call there will be exactly one TSHEND or TSHSKP call. The only exception would be a very abrupt termination like a power loss.

...

TSHSKP - This file download aborted

...

Here you’ll need to do the same unreserving that is done in the TSHEND exit point. You may also wish to make some record of the aborted download.

...

TSHFIN - End of downloading session

...

This is the most important exit point: the one where FTF turns control back over to your application. Be sure to restore your usrptr->state and usrptr->substt, and prompt the user for what comes next.

...

Another handy feature of the file transfer service is that each ftgsbm() invocation that returns 1 is followed (eventually) by exactly one TSHFIN or TSHHUP exit point invocation, except in dire cases (power loss for example).

...

TSHHUP - Channel hanging up

...

Use this exit point to clean up your affairs in case the user hangs up or the channel disconnects while the user is in the download session. This only occurs in place of a TSHFIN, and will probably not be called if one of your files is tagged for download and the actual download is interrupted by a disconnect. In that case, TSHFIN had long since been called, after the user tagged the file.

...

See the discussion on the upload handler exit point FUPHUP on page 158 about making sure your module’s cleanup code executes exactly once for users in your module.

...

Downloading Example #1

...

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

...

***  DOWNLOAD COMPLETE  ***

     TOP (TOP)
Make your selection (T,I,F,E,L,A,P,R,D,O,W,U,N,S,? for help, or X to exit): _

...

init__downloader()

...

This function registers the GALDNX2 module, opens the GALDNX2.MCV file, and reads in the Sysop-configured download directory prefix.

...

dnlinp()

...

This text-line input handling function returns to the parent menu if the user enters X and otherwise uses command concatenation routines to parse user input. When a user enters this module he’s given a list of the files available (more on fllist() below), and asked to type in the name of a file, or file specification with wildcards, to download.

...

An entry in the tag table is obtained, if available, by ftgnew(). In this example, the use of wildcard characters ? or * in the filename signifies a multi-file download, and the FTGWLD flag is set. The FTGABL flag is always set. If the user concatenated a protocol code after his file specification, that is passed to ftgsbm(). Otherwise, a list of protocols is requested. FTF will handle invalid protocol codes with a warning and a list of the available codes.

...

fllist()

...

This function scans through the files in the download directory and lists them on the user’s terminal, with file size, date, and time.

The size of the output buffer (CNF option OUTBSZ in Hardware Setup) effectively limits the number of files that can be put online for download. With OUTBSZ set to 4096, you can probably handle somewhere around 100 files. Much more than that, and the output buffer will overflow.

...

tshdnl()

...

Here the description is the same simple file <filename>. Multi-file tagspecs are visible if any matching files exist. Single-file tagspecs are visible if the file can be opened, and if so, the first TSHLEN bytes are read in so the V protocol can be supported.

...

The TSHFIN exit point just restores the state code and returns 0, indicating that control should return to the download module’s parent menu page when downloading is complete.

Download Manager Support in Agents

Applies to: WG2+

If your agent supports apps getting files from it, apps may use the new Download Manager to get those files. Without you doing anything special, this will appear to work fine. But, examined more closely, things may not be all that fine. You do need to do one simple thing to support the new Download Manager from your agent: support apps getting the status of your file dynapaks with stsdpk(). To do this, you need to pay attention to forreal()’s return value where appropriate in your read handler. Be sure that your read handler doesn’t do anything like charge for files gotten by apps without checking forreal() first.

Applies to: WG2+

Header check (GCSPSRV.H): BOOL forreal(void); (GCSP.H): the dynapak status length is carried in struct typlen (APTYPLEN) for stsdpk().

File Transfer Protocol

To define a file transfer protocol for Worldgroupthe Major BBS, define a file transfer protocol specification structure. Here is an example of the structure for XMODEM-CRC downloads.

...