Versions Compared

Key

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

...

Now the Sysop can change this option so that another key is required. All you have to do is:

Code Block
        if (hasmkey(SAMPKY)) {
             welcomemyfriend();
        }
        else {
             sorrynotachance();
        }

By convention, all security-related CNF options are stored in level 3 — Security & Accounting. If you specify any locks of your own here, we recommend that you use one of the four pre-defined lock names for the default values of your option when you can:

...

Here’s the corresponding pseudo-key routine from MAJORBBS.C:

Code Block
        STATIC int
        prtpsk(unum,lock)      /* validate the _PORT# pseudo-key      */
        int unum;              /* user number, 0 to nterms-1          */
        char *lock;            /* lock name that the key is for       */
        {
             int chn;

             sscanf(lock,"_
PORT#%x
PORT#%x",&chn);
             return(channel[unum] == chn);
        }

Applies to: WG3.x

Header check: STATIC is not defined in WG3.2 (WG2 GCOMM.H:257); write static (chapter 2 note).

And here’s how it gets registered:

...

char *lock; full name of the key required

For example:

Code Block
        register_pseudok("_PORT#",prtpsk);

The registration call says in effect “If anyone asks about users having a key that starts with _PORT#, then let me make the determination”. Now suppose there’s some code somewhere like this:

Code Block
        haskey("_PORT#2C");

Then prtpsk() swings into action and determines whether this user happens to be on channel 2C hexadecimal or not.

...

Here’s an example of a global command called /now to tell the time of day:

Code Block
        int
        glotime(void)     /* global command for telling the time of day */
        {
             if (margc == 1 && sameas(margv[0],"/now")) {
                  prf("At the tone, the time will be %s\7\r",nctime(now()));
                  outprf(usrnum);
                  return(1);
             }
             return(0);
        }

Applies to: WG3.x

const CHAR * vs CHAR * hazard. ncdate() and nctime() return const CHAR * in WG3.2 (DNTAPI.H:209,217; WG2 returned char *). Passing them to prf()/prfmsg() as %s arguments, as here, is fine. Assigning the result to a plain CHAR *, writing through it, or returning it from a register_textvar() routine is not: declare the receiver const CHAR * or copy it out first. The result points into a library-local buffer that the next call overwrites.

...

The next step is registering the global command as part of your initialization routine (page 42):

Code Block
        int glotime(void);                       /* this is the prototype */
        :
        :
        void EXPORT
        init__myroutine()            /* the module initialization routine */
        {
             :
             globalcmd(glotime);
             :
        }

Tip: The global command feature has possible utility beyond defining global commands for users. For example, you could make a routine to intercept all user input for diagnostic or management purposes.

...

All global command handlers can be temporarily disabled for a channel by setting the special NOGLOB flag, as in:

Code Block
        usrptr-
>flags¦
>flags¦=NOGLOB;

and later cleared with:

Code Block
        usrptr-
>flags
>flags&=
~NOGLOB
~NOGLOB;

This is done during teleconference chat modes, for example.

...

An excerpt from MAJORBBS.H, defining the bits of the last parameter:

Code Block
                                   /* flags that can be passed to bgnedt()    */
      #define ED_READON      2     /* "read only" mode                        */
      #define ED_CLRTOP      4     /* clear topic buffer upon entry           */
      #define ED_CLRTXT      8     /* clear text buffer upon entry            */
      #define ED_FILESD     16     /* use "file" flavor of editor             */
      #define ED_LINEMO     32     /* force use of the line editor            */
      #define ED_FIXTOP     64     /* don't allow changing of the topic field */

Note: the ED_FILIMP flag that appears in MAJORBBS.H is not supported.

...

#include "majorbbs.h"

#include "galfbk.h"

Code Block
STATIC int fbkinp(void);
STATIC int fbkdun(int flags);
STATIC void fbkfin(void);
int fbkstt; /* Feedback module state number */
FILE *fbkmb; /* feedback configuration variables */
FILE *fbkfp; /* feedback text file */
struct module fbkmodule={ /* module interface block */
"", /* name used to refer to this module */
NULL, /* user logon supplemental routine */
fbkinp, /* input routine if selected */
dfsthn, /* status-input routine if selected */
NULL, /* "injoth" routine for this module */
NULL, /* user logoff supplemental routine */
NULL, /* hangup (lost carrier) routine */
NULL, /* midnight cleanup routine */
NULL, /* delete-account routine */
fbkfin /* finish-up (sys shutdown) routine */
};
#define TPCSIZ 40 /* maximum characters in topic */
#define FBKSIZ 1921 /* maxchars in feedback(for 24 lines)*/
struct fbkusr { /* feedback to Sysop user data block */
char text[FBKSIZ]; /* text buffer */
char topic[TPCSIZ]; /* topic buffer */
};
#define fbkptr ((struct fbkusr *)vdaptr)

Applies to: v10

TPCSIZ here is this sample's own define (40). The engine's TPCSIZ is 51 (GME.H:48, unchanged from WG3.2). The 41 of the old C teleconference header (ENTTLC.H:32) is not a v10 symbol: that header is not shipped. Do not #define TPCSIZ yourself in a module that includes GME.H. See chapter 29, section 29.8.

Applies to: WG3.x

Header check: opnmsg() returns HMCVFILE, not FILE * (MCVAPI.H:54); declare fbkmb as HMCVFILE (see chapter 3).

Code Block
void EXPORT
init__feedback()        /* initialize feedback stuff         */
{
      stzcpy(fbkmodule.descrp,gmdnam("GALFBK.MDF"),MNMSIZ);
      fbkstt=register_module(&fbkmodule);
      fbkmb=opnmsg("GALFBK.MCV");
      dclvda(sizeof(struct fbkusr));
}

STATIC int
fbkinp(void)            /* feedback handler                  */
{
     setmbk(fbkmb);
     if (margc == 1 && sameas(margv[0],"X")) {
          return(0);
     }
     do {
          bgncnc();
          switch(usrptr-
>substt
>substt) {
          case 0:
               cncchr();
               prfmsg(HELLO);
               outprf(usrnum);
               bgnedt(FBKSIZ,fbkptr-
>text
>text,
                      TPCSIZ,fbkptr-
>topic
>topic,fbkdun,ED_CLRTOP+ED_CLRTXT);
               break;
          }
     } while (!endcnc());
     outprf(usrnum);
     return(1);
}

STATIC int
fbkdun(                      /* feedback editing when-done   */
int quitex)
{
     char *cp;

     usrptr-
>state
>state=fbkstt;
     setmbk(fbkmb);
     if (quitex == 0) {
          for (cp=fbkptr-
>text
>text ; *cp != '\0' ; cp++) {
               if (*cp == '\r') {
                    *cp='\n';
               }
          }
          if ((fbkfp=fopen("GALFBK.TXT",FOPAA)) == NULL) {
               catastro("Cannot open GALFBK.TXT for append!");
          }
          fprintf(fbkfp,"*** From %s on %s at %-5.5s   %s\n%s\n\n\n",
               usaptr-
>userid
>userid,ncdate(today()),nctime(now()),
               fbkptr-
>topic
>topic,fbkptr-
>text
>text);
          fclose(fbkfp);
          prfmsg(THANKS,usaptr-
>userid
>userid);
          outprf(usrnum);
     }
     return(0);
}
Code Block
STATIC void
fbkfin(void)                 /* feedback shutdown            */
{
     clsmsg(fbkmb);
}

Here are the Text Block CNF options which go with this example:

esc represents the Escape character, ASCII 27.

Code Block
        LEVEL6 {}

        HELLO {esc[0;1;
32m
32m
        Hello, and welcome to the Sysop Feedback Forum.  This service is
        provided to encourage your comments and criticisms.
        When you are done typing, you can hit esc[
37m<Ctrl-G>esc[32m
37m<Ctrl-G>esc[32m to
        save your comments.
        } T Feedback welcome message

        THANKS {esc[0;1;
32m
32m
        Thank you for taking the time to leave your comments,
        esc[
33m%sesc[32m
33m%sesc[32m!
        } T Feedback thanks for comments

This source code and all support files are available on the Galacticomm Demo System, (305) 583-7808, in a file named GALFBK.ZIP.

...

3. Find out how much memory to allocate. Make a call like this if the template is for an entry session

Code Block
        nbytes=fsdroom(tmpmsg,fldspc,0);

but make a call like this if the template is for displaying:

Code Block
        nbytes=fsdroom(tmpmsg,fldspc,-1);

Make a call like this from your init__routine() and identify the above Template and Field Specification strings (after opening the appropriate .MCV file of course). This will tell you the size of the region you must provide to support data entry or display. Call fsdroom() for all templates/field specification combinations you will be using to make sure you’ll have enough room for all of them.

...

6a. To display data call:

Code Block
        fsdroom(tmpmsg,fldspc,-1);
        fsdapr(sesbuf,seslen,answers);
        fsddsp(fsdrft());

6b. To begin a full-screen entry session, call:

Code Block
        fsdroom(tmpmsg,fldspc,1);
        fsdapr(sesbuf,seslen,answers);
        fsdrhd(title);
        fsdbkg(fsdrft());
        fsdego(fldvfy,whndun);

6c. To begin a linear entry session, call:

Code Block
        fsdroom(tmpmsg,fldspc,0);
        fsdapr(sesbuf,seslen,answers);
        fsdego(fldvfy,whndun);

Notes:

Fields are numbered 0 to N-1. How do you tell FSD what N is? N is computed from the field specs by fsdroom() and stored in fsdscb->numfld. The number of fields that are also represented in the template is fsdscb->numtpl, which usually equals but never exceeds N. You can’t display or enter a field outside the range 0 to fsdscb->numtpl-1.

...

For example, to display all data but blank out field 5 and some of the supporting text surrounding field 5, you could code something like:

Code Block
        char *tp;
Code Block
        fsdroom(tmpmsg,fldspc,0);
        fsdapr(sesbuf,seslen,answers);
        tp=fsdrft();
        tpwipe(tp,5,1,1);
        fsdscb-
>flddat
>flddat[5].flags¦=FFFAVD;
        fsddsp(tp);

This works almost identically for avoiding fields in a full screen entry mode, except you need to intercept things before fsdbkg() is called (instead of before fsddsp()). On the other hand, to show a protected field that the user can see but can’t change, the FFFAVD flag should be set after fsdbkg() is called, but before fsdego(), and don’t call tpwipe() at all.

...

Here’s an example of creating an answer string from scratch using sprintf():

Code Block
        sprintf(answers,"NAME=
%s%cRANK
%s%cRANK=
%s%cSERIALNO
%s%cSERIALNO=%s%c",name,'\0',
                                                          rank,'\0',
                                                          serno,'\0');

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.

...

1. In your source code, include the following special-purpose header file:

Code Block
        #include "filexfer.h"

2. Code your own upload handler routine. The upload handler routine includes all the ways that the file transfer service will be asking you for assistance after you’ve turned control over to it. This is most of the work, and it’s discussed in detail below.

...

Here’s an informal pseudo-code template for an upload handler routine. This is mostly in C code, but it’s liberally laced with English descriptions where appropriate.

Code Block
int
fupxxx(                              /* Handle the application-specific  */
int fupcod)                          /* aspects of your uploads          */
{                                    /* (fupcod=code for each aspect)    */
     int rc=0;

     setmbk(whatever your application uses);
     (be sure to set any other appropriate globals)
     switch(fupcod) {
     case FUPPTH:                     /* Where would we put this file?    */
          sprintf(ftfbuf,"<DOS path for the file>",ftfscb-
>fname
>fname);
          rc=
<resume
<resume 
upload>
upload> ? 2 : 1;
          break;
     case FUPBEG:                /* Begin uploading this file       */
          if (user can't upload this file) {
               sprintf(ftfbuf,"He can't upload this file because.");
          }
          else {
               sprintf(ftfbuf,"<DOS path for the file>",ftfscb-
>fname
>fname);
               reserve file
               rc=1;
          }
          break;
     case FUPREF:                     /* Refer to file, don't upload it  */
          strcpy(
<somewhere>
<somewhere>,ftfbuf);
          break;
     case FUPEND:                     /* This file uploaded successfully */
          unreserve file
          record a completed upload
          sprintf(ftfbuf,"<DOS path for the file>",ftfscb-
>fname
>fname);
          break;
     case FUPSKP:                     /* This file upload aborted        */
          unreserve file
          record an aborted upload
          break;
     case FUPFIN:                     /* End of uploading session        */
          usrptr-
>state
>state=your state
          usrptr-
>substt
>substt=your substate
          prompt(whatever comes next);/* (don't call outprf())           */
          rc=1;
          break;
     case FUPHUP:                     /* Channel hanging up              */
          the FUPFIN exit point never got called, clean up as req'd
          break;
     }
     return(rc);
}

You might find it handy to download FUPXXX.C from the Galacticomm Demo System, (305) 583-7808, which contains the above pseudo-code, and then edit it line-by-line into what your upload handler will need.

...

The pseudo-code for FUPFIN handling on page 150 assumes you want to take control back. Here’s an alternative pseudo-coding of the FUPFIN exit point to allow you to exit to your module’s parent menu page:

Code Block
     case FUPFIN:                      /*       End of uploading session     */
          usrptr-
>state
>state=your state
          prompt(exiting);             /*       (don't call outprf())        */
          rc=0;
          break;

This may be appropriate if your module really doesn’t want to regain control of the channel when the upload is done. In this case you only need to restore the user’s state code (module number), not the substate. Your module never actually regains control of the user’s channel. You can prompt him with some parting words, but you don’t need to. For consistency you should do whatever you normally do when the user exits from your module to the parent menu.

...

#include "majorbbs.h"

#include "filexfer.h"

Code Block
STATIC int uplinp(void);
STATIC int fupupl(int fupcod);
int uplstt; /* Uploading module state number */
struct module uplmodule={"",NULL,uplinp,dfsthn};

void EXPORT

Code Block
init__uploader(void) /* Uploader initialization */
{
stzcpy(uplmodule.descrp,gmdnam("GALUPX.MDF"),MNMSIZ);
uplstt=register_module(&uplmodule);
mkdir("UPLDIR");
}
Code Block
STATIC int
uplinp(void)                           /* Uploader input handler          */
{
     switch (usrptr-
>substt
>substt) {
     case 0:
          prf("Name of file to upload: ");
          usrptr-
>substt
>substt=1;
          break;
     case 1:
          if (margc == 0) {
               return(0);
          }
          fileup(strcpy(vdaptr,margv[0]),"?",fupupl);
     }
     outprf(usrnum);
     return(1);
}

int
fupupl(                                /* Handle the application-specific */
int fupcod)                            /* aspects of the upload example   */
{                                      /* (fupcod=code for each aspect)   */
     int rc=0;

     switch(fupcod) {
     case FUPBEG:                      /* Begin uploading this file       */
     case FUPEND:                      /* This file uploaded successfully */
          sprintf(ftfbuf,"UPLDIR\\%s",vdaptr);
          rc=1;
          break;
     case FUPFIN:                      /* End of uploading session        */
          usrptr-
>state
>state=uplstt;
     }
     return(rc);
}

This module allows users to upload files into the UPLDIR subdirectory of the 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.

...

#include "filexfer.h"

#include "galupx2.h"

Code Block
STATIC int uplinp(void);
STATIC void uplfil(char *filnam,char *protoc);
STATIC int fupupl(int fupcod);
STATIC void uplfin(void);
int uplstt; /* Enhanded uploader module state number */
static FILE *uplmb; /* file pointer for GALUPX2.MCV */
char *upldir; /* UPLDIR upload directory */
long uplbmax; /* max bytes allowed in UPLDIR */
long uplfmax; /* max files allowed in UPLDIR */
struct module uplmodule={ /* module interface block */
"", /* name used to refer to this module */
NULL, /* user logon supplemental routine */
uplinp, /* input routine if selected */
dfsthn, /* status-input routine if selected */
NULL, /* "injoth" routine for this module */
NULL, /* user logoff supplemental routine */
NULL, /* hangup (lost carrier) routine */
NULL, /* midnight cleanup routine */
NULL, /* delete-account routine */
uplfin /* finish-up (sys shutdown) routine */
};

void EXPORT

Code Block
init__uploader(void) /* Uploader initialization */
{
stzcpy(uplmodule.descrp,gmdnam("GALUPX2.MDF"),MNMSIZ);
uplstt=register_module(&uplmodule);
uplmb=opnmsg("GALUPX2.MCV");
mkdir(spr("%s.",upldir=stgopt(UPLDIR)));
uplbmax=lngopt(UPLBMAX,0,
2147483647L
2147483647L);
uplfmax=numopt(UPLFMAX,0,32767);
dclvda(8+1+3+1);
}
Code Block
STATIC int
uplinp(void)                         /* Uploader input handler                */
{
     setmbk(uplmb);
     if (margc == 1 && sameas(margv[0],"X")) {
          return(0);
     }
     do {
          bgncnc();
          switch (usrptr-
>substt
>substt) {
          case 0:
               cncchr();
               prfmsg(usrptr-
>substt
>substt=UPLNAME);
               break;
          case UPLNAME:
               if (usrptr-
>flags
>flags&INJOIP) {
                    prfmsg(UPLNAME);
                    break;
               }
               cncall();
               parsin();
               switch (margc) {
               case 0:
                    uplfil("","?");
                    break;
               case 1:
                    uplfil(margv[0],"?");
                    break;
               default:
                    uplfil(margv[0],margv[1]);
               }
               break;
          }
     } while (!endcnc());
     outprf(usrnum);y
     return(1);
}

STATIC void
uplfil(                            /* upload file(s)                          */
char *filnam,                      /* filename, or "" for multi-file          */
char *protoc)                      /* protocol, or "?" for list               */
{
     if (sameas(filnam,"*")) {
          filnam="";
     }
     if (rsvnam(filnam)
      ¦¦ strchr(filnam,':') != NULL
      ¦¦ strchr(filnam,'\\') != NULL
      ¦¦ strstr(filnam,"..") != NULL) {
          prfmsg(UPLRSV);
          prfmsg(UPLNAME);
     }
     else {
          stzcpy(vdaptr,filnam,8+1+3+1);
          fileup(filnam,protoc,fupupl);
     }
}
Code Block
int
fupupl(                           /* Upload handling routine                  */
int fupcod)
{
     int rc=0;

     setmbk(uplmb);
     switch(fupcod) {
     case FUPBEG:                /* Begin upload, check permission, reserve   */
          if (vdaptr[0] == '\0' && rsvnam(ftfscb-
>fname
>fname)) {
               strcpy(ftfbuf,"Filename is a reserved DOS device name.");
               break;
          }
          cntdir(spr("%s*.*",upldir));
          if (numfils >= uplfmax) {
               strcpy(ftfbuf,"Upload directory is full.");
               break;
          }
          ftfscb-
>maxbyt
>maxbyt=uplbmax-numbyts;
          sprintf(ftfbuf,"%s%s",upldir,vdaptr[0] == '\0' ? ftfscb-
>fname
>fname
                                                         : vdaptr);
          rc=1;
          break;
     case FUPEND:                 /* End complete upload of a file, unreserve */
          sprintf(ftfbuf,"%s%s",upldir,vdaptr[0] == '\0' ? ftfscb-
>fname
>fname
                                                         : vdaptr);
          break;
     case FUPSKP:                       /* Skip incomplete upload of a file   */
          unlink(spr("%s%s",upldir,vdaptr[0] == '\0' ? ftfscb-
>fname
>fname
                                                     : vdaptr);
          break;
     case FUPFIN:                  /* Finish file upload session              */
          usrptr-
>state
>state=uplstt;
          if (ftfscb-
>actfil
>actfil >= 1) {
              prfmsg(UPLTHX);
          }
          break;                   /* rc == 0, so we exit to parent menu page */
     }
     return(rc);
}
Code Block
STATIC void
uplfin(void)                       /* Finalize uploading example              */
{
     clsmsg(uplmb);
}

Here are the CNF options for upload example #2:

...

esc represents the Escape character, ASCII 27.

Code Block
UPLNAME {esc[0;1;36m
Name of file to upload (or "*" for multiple files): } T Upload example II file
name

UPLRSV {esc[0;1;35m
That's a reserved or invalid DOS filename, please choose another name.
} T Upload example II filename collides with device list

UPLFUL {esc[0;1;35m
The upload directory is full.
} T Upload example II too many files

UPLTHX {esc[0;1;32m
Thanks for uploading.
} T Upload example II finished

This code, plus support files, is available for download on the Galacticomm Demo system in the file GALUPX2.ZIP.

Here’s what the module would look like online:

Code Block
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): U

Name of file to upload (or "*" for multiple files): COLDEMO.EXE

To start uploading COLDEMO.EXE, type:

    A ... ASCII                           B ... YMODEM Batch
    M ... XMODEM-Checksum                 G ... YMODEM-g
    C ... XMODEM-CRC                      Z ... ZMODEM
    1 ... XMODEM-1K                       K ... Kermit / Super Kermit

(Add '!' to automatically log off when done)

Your choice (or 'X' to exit): Z

(Hit Ctrl-X a few times to abort)
Beginning ZMODEM upload of the file COLDEMO.EXE
**B0100000023be50

(uploading takes place)

***  UPLOAD COMPLETE  ***

Thanks for uploading.

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): _

Assuming that the menu selection to invoke the uploading service is U, the user can enter any of the following concatenated commands from that menu:

...

An example initiation of an ASCII download:

Code Block
        listing("E:\
DOC93
DOC93\
SATNAV
SATNAV.HLP",lstback);

An example (*whndun)() routine:

Code Block
        void
        lstback(int all)
        {
             usrptr-
>state
>state=snstate;
             prfmsg(usrptr-
>substt
>substt=all ? FULLPMT : SHORTPMT);
        }

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.

...

1. In your source code, include the following special-purpose header file:

Code Block
        #include "filexfer.h"
  1. Define your own tagspec data structure. This can be up to 17 bytes of data for storing information on your file, in any format you choose. A tagspec may refer to a single file or to multiple files (for example you could store "FILE.TXT" or "*.TXT"). To allow your files to be tagged for later download, you’ll need to store enough information in this 17-byte structure to later reconstruct the file’s DOS path, and any security and accounting information. We’ll talk more about tagspecs below.

...

This pseudo-code template roughly outlines the tasks expected at each of the exit points.

Code Block
 int
 tshxxx(                              /* Handle the application-specific     */
 int tshcod)                          /* aspects of your downloads           */
 {                                    /* (tshcod=code for each aspect)       */
     int rc=0;

     setmbk(whatever your application uses);
     (be sure to set any other appropriate globals)
     switch(tshcod) {
     case TSHDSC:                     /* Describe the file(s) in English     */
          sprintf(tshmsg,"app-specific description of file",ftgptr-
>tagspc
>tagspc);
          break;
     case TSHVIS:                     /* Visible to this user?               */
          if (file exists, or user is allowed to know it doesn't)  {
               open & read first TSHLEN bytes into tshmsg, as in:
               if ((fp=fopen("<DOS path for the file>",FOPRB)) != NULL) {
                    fread(tshmsg,1,TSHLEN,fp);
                    rc=1;
               }
          }
          break;
     case TSHSCN:                     /* Break down multiple filespec        */
          if (there's at least one file in this multi-file tagspec) {
               store tagspec for the individual file in tshmsg
               rc=1;
          }
          break;
     case TSHNXT:                     /* Next file in multi-file spec        */
          if (there are more subfiles) {
               store tagspec for the individual file in tshmsg
               rc=1;
          }
          break;
Code Block
     case TSHBEG:                           /* Begin downloading this file   */
          if (file can't be downloaded by this user) {
               sprintf(tshmsg,"You can't download the file because...");
          }
          else {
               reserve it
               sprintf(tshmsg,"<DOS path for file>",ftgptr-
>tagspc
>tagspc);
               strcpy(ftfscb-
>fname
>fname,"<filename for the protocol>");
               rc=1;
          }
          break;
     case TSHEND:                           /* File download was successful  */
          unreserve it
          record a completed download
          break;
     case TSHSKP:                           /* This file download aborted    */
          unreserve it
          record an aborted download
          break;
     case TSHFIN:                           /* End of downloading session    */
          usrptr-
>state
>state=your state
          usrptr-
>substt
>substt=your substate
          prompt (you don't need to call outprf here)
          rc=1;
          break;
     case TSHHUP:                           /* Channel hanging up            */
          the TSHFIN exit point never got called, clean up as req'd
          break;
     }
     return(rc);
}

This code is available in file TSHXXX.C on the Galacticomm Demo System, (305) 583-7808. You may want to download it and use it as a template to write your own download handler routine.

...

The pseudo-code for TSHFIN handling on page 173 assumes you want to take control back. Here’s an alternative of the TSHFIN exit point to allow you to exit to your module’s parent menu page:

Code Block
     case TSHFIN:                    /* End of downloading session      */
          usrptr-
>state
>state=your state
          prompt(exiting);           /* (don't call outprf())           */
          rc=0;
          break;

This may be appropriate if your module really doesn’t want to regain control of the channel when the download is done. In this case you only need to restore the user’s state code (module number), not the substate. Your module never actually regains control of the user’s channel. You can prompt him with some parting words, but you don’t need to. For consistency you should do whatever you normally do when the user exits from your module to the parent menu.

...

#include "majorbbs.h"

#include "filexfer.h"

Code Block
STATIC int dnlinp(void);
STATIC int tshdnl(int tshcod);
int dnlstt; /* Downloading module state number */
struct module dnlmodule={"",NULL,dnlinp,dfsthn,NULL,NULL,NULL,NULL,NULL,NULL};

void EXPORT

Code Block
init__downloader(void) /* Downloader initialization */
{
stzcpy(dnlmodule.descrp,gmdnam("GALDNX.MDF"),MNMSIZ);
dnlstt=register_module(&dnlmodule);
}

STATIC int

Code Block
dnlinp(void) /* Downloader input handler */
{
int rc=1;
switch (usrptr-
>substt
>substt) {

case 0:

Code Block
prf("Name of file to download: ");
usrptr-
>substt
>substt=1;
break;

case 1:

Code Block
if (margc == 0) {
rc=0;
}
else if (ftgnew() == 0) {
ftgsbm(""); /* use warning feature of ftgsbm() */
rc=0;
}
else {
stzcpy(ftgptr-
>tagspc
>tagspc,margv[0],TSLENG);
ftgptr-
>tshndl
>tshndl=tshdnl;
ftgsbm("?");
}
}
outprf(usrnum);
return(rc);
}

```c

```c
int
tshdnl(                                 /* Handle the application-specific */
int tshcod)                             /* aspects of your downloads       */
{                                       /* (tshcod=code for each aspect)   */
     int rc=0;

     switch(tshcod) {
     case TSHVIS:                       /* Visible to this user?           */
          rc=1;
          break;
     case TSHDSC:                       /* Describe the file(s) in English */
          sprintf(tshmsg,"file %s",ftgptr-
>tagspc
>tagspc);
          break;
     case TSHBEG:                       /* Begin downloading this file     */
          sprintf(tshmsg,"DNLDIR\\%s",ftgptr-
>tagspc
>tagspc);
          strcpy(ftfscb-
>fname
>fname,ftgptr-
>tagspc
>tagspc);
          rc=1;
          break;
     case TSHFIN:                       /* End of downloading session      */
          usrptr-
>state
>state=dnlstt;
     }
     return(rc);
}
Code Block

This module lets users download files from subdirectory DNLDIR on the Worldgroup server computer. Users of

...


this service type in a filename (that they must know somehow), and choose a protocol to download it.

###### init\_\_downloader()

This routine registers the downloading module using the description in the GALDNX.MDF file.

###### dnlinp()

This routine handles text line input from the user after he selects this download service. Upon entry, the

...


user is prompted for the filename. If he presses enter, he’s returned to the parent menu page without any

...


downloading. If there is no room to download any more files because the user’s tag table is completely full,

...


then the user is notified (ftgsbm() does this) and he’s also returned to the parent menu.

Otherwise, the tagspec structure is simply the filename, and it’s copied to the tagspec in the current tag

...


table entry that ftgnew() identified for us. Neither the FTGWLD nor FTGABL flags are set, indicating that

...


these will be single-file non-taggable downloads. The call to ftgsbm() turns control over to the file transfer

...


service and a list of protocols is presented to the user.

###### tshdnl()

The TSHVIS exit point declares that all files are visible if they exist. The description for the file will be

...


file \<filename\>. In the TSHBEG exit point the path and protocol names are passed to FTF. There are no

...


TSHEND, TSHSKP, or TSHHUP exit points coded because they only need to return 0 and do nothing else. TSHFIN

...


restores the usrptr-\>state and returns 0, telling FTF to return control to the parent menu.

###### Potential Improvements to Download Example \#1

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

- 

- 

- 

- 

- 

- 

- 

- 

- 

- 

- 

Viewing the contents of compressed files, such as .ZIP filesMultiple-file downloadsChecking for conflicts

...


between the filename and DOS devicesChecking for attempts to download files like DNLLIB\\.\WG.BATFile

...


taggingConcatenated commandsAllowing X to exitTelling the user what files are available in the directorySysop-
configurable prompts an .MSG fileSysop-configurable download directoryFull module structure in source code,

...


with commentsAll of these features are included in download example \#2.

###### Downloading Example \#2

/\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*

\* \*

\* GALDNX2.C \*

\* \*

\* Copyright (C) 1995 GALACTICOMM, Inc. All Rights Reserved. \*

\* \*

\* Downloading example. \*

\* \*

\* - R. Stein 12/6/93 \*

\* \*

\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*/

\#include "gcomm.h"

\#include "majorbbs.h"

\#include "filexfer.h"

\#include "galdnx2.h"

```c

```c
STATIC int dnlinp(void);
STATIC int fllist(void);
STATIC int tshdnl(int tshcod);
STATIC void dnlfin(void);

int dnlstt;                        /* Downloading module state number      */
static FILE *dnlmb;                /* file pointer for GALDNX2.MCV         */
char *dnldir;                      /* DNLDIR download directory            */

struct module dnlmodule={          /* module interface block               */
     "",                           /*    name used to refer to this module */
     NULL,                         /*    user logon supplemental routine   */
     dnlinp,                       /*    input routine if selected         */
     dfsthn,                       /*    status-input routine if selected  */
     NULL,                         /*    "injoth" routine for this module  */
     NULL,                         /*    user logoff supplemental routine  */
     NULL,                         /*    hangup (lost carrier) routine     */
     NULL,                         /*    midnight cleanup routine          */
     NULL,                         /*    delete-account routine            */
     dnlfin                        /*    finish-up (sys shutdown) routine  */
};

void EXPORT
init__downloader(void)                  /* Downloader initialization       */
{
     stzcpy(dnlmodule.descrp,gmdnam("GALDNX2.MDF"),MNMSIZ);
     dnlstt=register_module(&dnlmodule);
     dnlmb=opnmsg("GALDNX2.MCV");
     dnldir=stgopt(DNLDIR);
}

STATIC int
dnlinp(void)                            /* Downloader input handler        */
{
     int rc=1;

     setmbk(dnlmb);
     if (margc == 1 && sameas(margv[0],"X")) {
          return(0);
     }
     do {
          bgncnc();
          switch (usrptr->substt) {
          case 0:
               cncchr();
               if (!fllist()) {
                    cncall();
                    rc=0;
               }
               prfmsg(usrptr->substt=FLNAME);
               break;
Code Block
          case FLNAME:
               cncall();
               parsin();
               if (margc == 0 || sameas(margv[0],"?")) {
                    fllist();
                    prfmsg(FLNAME);
               }
               else if (rsvnam(margv[0])
                     || strchr(margv[0],':') != NULL
                     || strchr(margv[0],'\\') != NULL
                     || strstr(margv[0],"..") != NULL) {
                    prfmsg(FLRSV);
                    prfmsg(FLNAME);
               }
               else if (ftgnew() == 0) {
                    ftgsbm("");         /* use ftgsbm() to say out-of-tags */
                    rc=0;
               }
               else {
                    stzcpy(ftgptr-
>tagspc
>tagspc,margv[0],TSLENG);
                    ftgptr-
>tshndl
>tshndl=tshdnl;
                    ftgptr-
>flags
>flags=FTGABL;
                    if (strchr(margv[0],'?') != NULL
                     || strchr(margv[0],'*') != NULL) {
                         ftgptr-
>flags
>flags|=FTGWLD;
                    }
                    rc=ftgsbm(margc > 1 ? margv[1] : "?");
               }
          }
     } while (!endcnc());
     outprf(usrnum);
     return(rc);
}

STATIC int
fllist(void)                            /* Display listing of files        */
{
     struct fndblk fb;

     if (!fnd1st(&fb,spr("%s*.*",dnldir),0)) {
          prfmsg(FLNONE);
          return(0);
     }
     prfmsg(FLHEAD);
     do {
          prfmsg(FLLINE,fb.name,l2as(fb.size),ncdate(fb.date),nctime(fb.time));
     } while (fndnxt(&fb));
     return(1);
}

Applies to: WG3.x

Header check: struct fndblk is struct ffblk in WG3.2 (FIOAPI.H:37-44; FIOAPI.H:125, FILEXFER.H:41), with different member names and widths: ff_reserved, ff_fsize, ff_attrib, ff_ftime, ff_fdate and ff_name[256]. The sample's fb.name, fb.size, fb.date, fb.time become fb.ff_name, fb.ff_fsize, fb.ff_fdate, fb.ff_ftime. GBOOL fnd1st(struct ffblk *fbptr, const CHAR *filspc, INT attr) and fndnxt(struct ffblk *fbptr) are FIOAPI.H:229-236; filspc is const. (In v10, ff_name grows to 260 and xffblk is added: analysis/deltas/SUMMARY.md.)

Applies to: v10

v10: char ff_name[260] (FIOAPI.H:44; 256 in WG3.2), so sizeof(struct ffblk) changed; findfirst(const char *filspc, struct ffblk *fbptr, UINT attr) and findnext(struct ffblk *fbptr) were added for _MSC_VER builds (FIOAPI.H:257-269), and struct xffblk (holding a HANDLE) is new (FIOAPI.H:50-55). fnd1st()/fndnxt() remain (FIOAPI.H:254).

Code Block
int
tshdnl(                                 /* Handle the application-specific */
int tshcod)                             /* aspects of your downloads       */
{                                       /* (tshcod=code for each aspect)   */
     int rc=0;
     FILE *fp;

     setmbk(dnlmb);
     switch(tshcod) {
     case TSHDSC:                       /* Describe the file(s) in English */
          sprintf(tshmsg,"file %s",ftgptr-
>tagspc
>tagspc);
          break;
     case TSHVIS:                       /* Visible to this user?           */
          if (ftgptr-
>flags
>flags&FTGWLD) {
               rc=fnd1st(&ftuptr-
>fb
>fb,ftgptr-
>tagspc
>tagspc,0);
               break;
          }
          if ((fp=fopen(spr("%s%s",dnldir,ftgptr-
>tagspc
>tagspc),FOPRB)) != NULL) {
               fread(tshmsg,1,TSHLEN,fp);
               rc=1;
          }
          break;
     case TSHSCN:                       /* Break down multiple filespec    */
          if (fnd1st(&ftuptr-
>fb
>fb,spr("%s%s",dnldir,ftgptr-
>tagspc
>tagspc),0)) {
               strcpy(tshmsg,ftuptr-
>fb
>fb.name);
               rc=1;
          }
          break;
     case TSHNXT:                       /* Next file in multi-file spec    */
          if (fndnxt(&ftuptr-
>fb
>fb)) {
               strcpy(tshmsg,ftuptr-
>fb
>fb.name);
               rc=1;
          }
          break;
     case TSHBEG:                       /* Begin downloading this file     */
          sprintf(tshmsg,"%s%s",dnldir,ftgptr-
>tagspc
>tagspc);
          strcpy(ftfscb-
>fname
>fname,ftgptr-
>tagspc
>tagspc);
          rc=1;
          break;
     case TSHFIN:                       /* End of downloading session      */
          usrptr-
>state
>state=dnlstt;
     }
     return(rc);
}

STATIC void
dnlfin(void)                            /* Finalize downloading example    */
{
     clsmsg(dnlmb);
}

Here are the CNF options for download example #2:

...

esc represents the Escape character, ASCII 27.

Code Block
        FLHEAD {esc[0;1;32m
        Files available:
        } T Download example II file listing header

        FLLINE {esc[0;1;36m%-12.12sesc[33m %10s %8s %-5.5s
        } T Download example II file listing line

        FLNONE {esc[0;1;35m
        No files are available for download.
        } T Download example II no files available

        FLNAME {esc[0;1;36m
        Name of file(s) to download: } T Download example II filename prompt

        FLRSV {esc[0;1;35m
        That's not a valid filename
        } T Download example II filename invalid

This code, plus support files, is available for download on the Galacticomm Demo system in the file GALDNX2.ZIP.

Here’s what the module would look like online:

Code Block
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): D

Files available:

LOADER.BAT         1524 11/26/93 20:00
DPATCH.ZIP        57001 12/07/93 12:26
GALCONDL.ZIP       4162 12/07/93 16:05
DINSTALL.BAT        237 12/02/93 13:31

Name of file(s) to download: *.ZIP

    L ... Listing (a screen at a time)    Z ... ZMODEM
    A ... ASCII (continuous dump)         ZR... ZMODEM (resume after abort)
    B ... YMODEM Batch                    K ... Kermit / Super Kermit
    G ... YMODEM-g
    T ... Tag file(s) for later download

(Add '!' to automatically log off when done)

Choose a download option (or 'X' to exit): Z

(Hit Ctrl-X a few times to abort)
Beginning ZMODEM download of the file *.BAT
rz
**B0000000000000

(downloading takes place)

Code Block
***  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.

...

Applies to: WG3.x

Header check: FTFXYMD.H (struct xymdat, ftpxcx; WG2 FTFXYMD.H:13,43) is not in WGDEV/INC. struct ftfpsp and the protocol flags (FTF.H) are, and their 16-bit members became ushort (byttmo, paktmo, paksiz, retrys, nbytes: analysis/deltas/SUMMARY.md struct deltas), so a hand-copied WG2 layout is wrong.

Code Block
struct ftfpsp ftpxcx={              /* XMODEM-CRC transmitting                */
     NULL,
     "C",                           /* 1-3 code letters for protocol          */
     "XMODEM-CRC",                  /* name of protocol                       */
     FTFXMT+FTFXTD,                 /* protocol capability flags              */
     sizeof(struct xymdat),         /* total length of session control block  */
     3*16,                          /* .byttmo          default byte timeout  */
     10*16,                         /* .paktmo        default packet timeout  */
     10,                            /* .retrys        default max retries     */
     
1L
1L,          /* .window   max window size (packets/bytes as appropriate) */
     128,         /* .paksiz                        packet size 0=auto-figure */
     xyxini,      /* .initze()    Initialize this protocol (recompute scblen) */
     xcxsrt,      /* .start()                                Start a transfer */
     xyxctn,      /* .contin()              Continuously call, 1=more, 0=done */
     xyxinc,      /* .hdlinc()                       Handle one incoming byte */
     NULL,        /* .hdlins()                   Handle incoming line of text */
     ftfabt,      /* .term()        Initiate graceful termination of transfer */
     ftfxca,      /* .abort()  Immediately unconditionally abort the transfer */
     ftfinbc,     /* .hdlinb()              Handle an array of incoming bytes */
     "",          /* .secur                App-specific security of some kind */
     {0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0}
};

Here are the protocol capability flags:

Code Block
/* --- File Transfer Protocol Capability and Characteristic Flags  --- */

#define FTFXMT 0x01     /* Transmit protocol (versus receive)          */
#define FTFASC 0x02     /* ASCII-session (versus binary-session)       */
                        /* where '\r' is the sole line terminator      */
                        /* note: ASCII sessions do not detect errors   */
#define FTFMUL 0x04     /* capable of multiple files?                  */
#define FTF7BT 0x08     /* capable of using 7-bit data path?           */
#define FTFASF 0x10     /* ASCII-file (versus binary-file)             */
                        /* where '\n' is the sole line terminator      */
#define FTFAFN 0x40     /* abort is final, don't ask "try again?"      */
#define FTFXTD 0x80     /* extended ftfpsp structure (flags2 & hdlinb) */

See FTF.H for more details. See FTFXYMD.C for the full implementation of XMODEM. See FTF*.C for examples of the implementation of other file transfer protocols. The F file import/export file transfer “protocol” is implemented in FILEXFER.C with lots of cheating.

Next, register the structure in your init__xxx() routine via ftplog():

Code Block
        ftplog(fptr);

where fptr is a pointer to the structure from step 1. The new protocol will appear in the appropriate lists with all the other protocols.

...

Previous: Major BBS v10: 04 User Interface  |  Contents  |  Next: Major BBS v10: 06 The Galacticomm Messaging Engine