The Galacticomm Messaging Engine

The E-mail and Forums messaging system is divided into low-level and user interface subsections. The low-level section handles the details of storing and retrieving messages, forum management, access, credit charges, importing and exporting messages, etc. It is referred to as the Galacticomm Messaging Engine or GME.

The engine provides an API for messaging functions. The purpose of this API is to isolate developers from the details of the low-level architecture, provide a standard method for using the messaging system, increase system efficiency by cycling intensive tasks, and ensure backward compatibility for future messaging system enhancements. All functions and variables in this API are declared in the file GME.H. In order to use this API, #include "gme.h" in your source files, and link to GMEIMP.LIB.

Access and Credit Charges

Most messaging access restrictions and credit charges are applied by GME. It is also possible to circumvent these restrictions in many cases, particularly when writing messages.

Backwards Compatibility

While the vast majority of the old messaging system (for The Major BBS Version 6) can no longer be supported, a small suite of backward compatible functions are provided. These functions mimic the only previously existing semblance of an API: sendmsg(), sigtpc(), saxxok(), uidxst(), and the msgbyts variable.

Fundamental Architecture

GME Requests

Simple processes can usually be handled by a single function call. However, many messaging tasks are complex processes requiring multiple function calls and/or cycles to complete. To achieve this functionality, a request system is used.

A request is a series of function calls, or multiple calls to the same function, that accomplishes a given task (e.g., writing a message). The tie that binds this series of function calls together is the GME work area. This is a fixed size memory buffer that is dedicated for use by the engine to track the state of a request. A pointer to this work area is passed to each function that is part of the request. The size of the work area is declared in GME.H:

#define GMEWRKSZ 512               /* memory required for GME work area    */

Applies to: WG3.x

Header check: GMEWRKSZ is 518 when GCDOS is defined and 1536 otherwise (GME.H:38-42; WG2 had 512). Always allocate with the macro (alczer(GMEWRKSZ)), never a literal.

Since a request may span multiple cycles, the work area must reside in a memory area that will not be accessed by other processes (usually VDA for terminal-mode modules and per-request memory for C/S-mode modules).

Note: While it is possible to determine the structure of this work area, its contents should be considered undocumented (or, at the very least, subject to change without notice) and should never be directly examined or altered by any processes outside the messaging engine.

Each request must be opened by initializing the work area. Then the series of function calls that make up the request are made. When the request is finished (either normally or due to an error), some types of requests will automatically close the request, while others require that the request be explicitly closed. If the request must be aborted before completion, it must be explicitly closed. This will free up any GME resources that have been dedicated to the request.

The functions that initialize and close (or abort) a request are:

void
inigmerq(                          /* initialize GME request               */
void *workb);                      /*   work area to be used for request   */
void
clsgmerq(                          /* close a GME request                  */
void *workb);                      /*   work area being used for request   */

It is important that the work area to be used for a request be opened once and closed once (in the same way that a file should be opened and closed). If a work area is used for one request then used for another request without being closed first, or if an uninitialized work area is used for a request, the results are undefined and possibly damaging. Before initializing a work area for the first time, it is a good idea to setmem() it to zero. After the initial setmem(), it is best to let inigmerq() and clsgmerq() do the work.

There is a function provided to determine whether a work area is in use:

BOOL
gmerqopn(                          /* is this request open?                */
void *workb);                      /*   pointer to work area               */

However, it is not 100% reliable. In general, you should track the status of your work area(s) yourself to be sure each is opened and closed properly.

The status of a request can be determined after each GME function call by the return code of the function call. A set of standard status codes are used by GME functions. These codes follow a general pattern:

code > 0 successful completion of call to this function

code < 0 error occurred during this function call

code == 0 do a cycle then call this function again

In addition to this general pattern, the status codes specify the nature of any errors or any special conditions of a successful completion. The following status codes are currently defined:

                                   /* GME request status codes             */
#define GMEAGAIN 0                 /*   GME still processing request       */
#define GMEOK    1                 /*   generic "finished OK" status       */
#define GMEAFWD  2                 /*   message was auto-forwarded         */
#define GMERRG   3                 /*   return receipt generated           */
#define GMEERR  -1                 /*   generic "error" status             */
#define GMEDUP  -2                 /*   unique name or ID exists           */
#define GME2MFR -3                 /*   too many forums error              */
#define GMENFID -4                 /*   no available forum IDs error       */
#define GMENFND -5                 /*   generic "not found" error          */
#define GMENDEL -6                 /*   generic "can't delete" error       */
#define GMENMOD -7                 /*   generic "can't modify" error       */
#define GMEFDV  -8                 /*   variable part of forum def too long*/
#define GMECRD  -9                 /*   not enough credits for operation   */
#define GMEMEM  -10                /*   not enough memory for operation    */
#define GMEIVA  -11                /*   invalid attachment to message      */
#define GMENOAT -12                /*   unable to attach file to message   */
#define GMEACC  -13                /*   user doesn't have access           */
#define GMENRGM -14                /*   couldn't re-get message            */
#define GMENCFL -15                /*   can't copy/fwd to a dist list      */
#define GMERST  -16                /*   E-mail message pointer reset       */
#define GMEUSE  -17                /*   message in use, can't modify or del*/
#define GMENAPV -18                /*   attachment not approved for dnload */
#define GME2MFL -19                /*   too many forum data files error    */
#define GMENSRC -20                /*   source not found                   */
#define GMENDST -21                /*   destination not found              */

The codes that may be returned by any given function will be discussed in later sections.

Many of the key request-oriented functions may need to be called multiple times to complete their task. This somewhat unusual mode of operation is to reduce system loading by breaking up complex tasks across multiple cycles. The GMEAGAIN status code is the key to their use: as long as the function returns the GMEAGAIN status code, you must continue calling it with the same parameters. Since the parameters to such functions must retain their contents across cycles, they must be in non-shared memory areas (such as VDA for terminal-mode modules). Any exceptions to this rule will be noted in subsequent sections.

A typical use of one of these functions might look something like this:

void
dosomething(void)                  /* process a GME request                */
{
     int status;

     switch (status=gmefunc(mywrkbuf,myparm1,myparm2,...)) {
     case GMEAGAIN:
          /* do a cycle then call dosomething() again */
          break;
     default:
          if (status > GMEAGAIN) {
               /* everything's OK */
          }
          else {
               /* an error occurred */
          }
          break;
     }
}
GME Callbacks

Many things can be occurring while a GME function is being cycled (especially when writing a message, see page 203). To allow the caller to track the progress of particularly complex requests, a callback mechanism is provided. A callback handler may be associated with each (initialized) work area using the following function call:

void
setgmecb(                          /* set handler for GME status reports   */
void *workb,                       /*   work area being used for request   */
void (*callback)(int evt,int res));/*   pointer to callback handler        */

Whenever a significant operation starts or ends, the engine will call the callback handler associated with the current request (if any), passing it an event code and a result code. The event code tells the callback handler what event has taken place. The result code is the GME status code that best describes the result of the operation.

The following event codes are currently defined:

                                   /* callback event codes                 */
#define EVTSTRT  0                 /*   starting to send a message         */
#define EVTDONE  1                 /*   done sending a message             */
#define EVTCCST  2                 /*   starting to send carbon copies     */
#define EVTDSTS  3                 /*   starting distribution              */
#define EVTDSTD  4                 /*   done with distribution             */
#define EVTCPYS  5                 /*   starting to copy a file            */
#define EVTCPYD  6                 /*   done copying a file                */
#define EVTNEWF  7                 /*   starting to scan a new forum       */
#define EVTNEWM  8                 /*   starting to scan a new message     */

Note that the event codes are generally grouped into “starting an operation” and “done with an operation” pairs. In general, the result code is only meaningful during a done event.

Within the callback handler, you may examine the contents of any buffers you passed to the engine (such as a message header buffer passed to a send-message request). You may also wish to examine the extended information string about the event that can be gotten by calling this function:

char *
gmexinf(void);                     /* get extended return information      */

The exact contents of this string depend on the request in progress and the event, and will be discussed in later sections.

Since callbacks occur while the engine is processing a request, they should do very little processing of their own — nothing more intensive than a prfmsg() and outprf() or a senddpk() should be done (be sure to do a rstmbk(), of course). In particular, you should never kick off another GME request from within a callback handler.

Addresses

Routing of messages when writing, copying, or forwarding is governed by two parameters: the forum ID and the address. For forum messages, the forum ID is the primary determining factor of where the message goes, and the address is far less important. However, for e-mail messages, the address is the determining factor of where the message goes.

Four distinct types of addresses are supported by GME:

Local Address a User-ID (e.g., Sysop). This sends an e-mail message To: the User-ID specified.

Forum Address the name of a forum preceded by / (e.g., /Hello). This sends the message To: ** ALL ** in the named forum

Exported Address an exporter prefix followed by an address in that exporter’s format (e.g., IN:TStryker@gcomm.com). This submits the message to the specified exporter which is then responsible for routing the message to the addressee.

Distribution List an @ or ! followed by the list name (e.g., @STAFF). This will send a copy of the message to each valid address in the list. An @ denotes a Sysop-defined list. Currently the only ! lists are !QUICK and !MASS

The following functions and macros are available to distinguish between different types of addresses:

#define FORIDC   '/'               /* E-mail directed to a forum prefix    */
#define isforum(s) (*(s) == FORIDC)/* is this a forum address              */
#define isdlst(s) (*(s) == '!' ¦¦ *(s) == '@')/* is this distribution list */

BOOL
islocal(                           /* is this a valid local addr (User-ID) */
char *adr);                        /*   address to check                   */
BOOL
isexpa(                            /* is this an exporter-style address    */
char *adr);                        /*   address to check                   */

Exporters and distribution lists are discussed in detail in later sections.

Forum Address Extension

Applies to: WG2+

An extension has been added to the forum address address type to allow users to write or forward messages to forums directed to a specific user (rather than ** ALL **). For the user this is quite simple, just add a space followed by the user-ID or user address to direct the message to after the forum name, like so:

/forumname directed to user address

This does, however, require slightly different capabilities on the part of any software that supports this type of address. The following functions and macro have been added for this purpose:

unsigned
getAdrForID( /* get forum ID given forum address */
const char *faddr); /* forum-style address */

char * /* returns pointer to static buffer */
extAdrForNam( /* extract forum name from address */
const char *faddr); /* forum-style address */

#define forAdrXst(foradr) (getAdrForID(foradr) != EMLID)
/* does the forum in this address exist?*/

Applies to: WG3.x

const CHAR * vs CHAR * hazard. In WG3.2 the GME read-only string results are const: getfnm, getftpc, tpcfnm, extAdrForNam, udlnam, ulname, dlname, accstr, gmexinf, exphlp, expasp return const CHAR * (GME.H:841,845,849,989,1085,1524,1528,1855,744,1926,1891) and the walkers getdefp, fiddefp, seqdefp, nxtdefp, prvdefp, tagmsg, expinf return const struct ...* (GME.H:1199-1235,1632,1922). The prototypes printed in this chapter show the WG2 char * / struct x * returns. Receive the result in a const CHAR *, or copy before editing; code that modified a returned fordef or message in place must copy it first. Every GME.H function also names its work area VOID *pWork (WG2 workb). See chapter 28.

Messages

Messages consist of a header part and a text or body part. The message header is a structure that contains all the fields necessary for proper control and routing of the message, and other fields describing the message. The header structure is as follows:

#define MAXADR   256               /* message address size                 */
#define TPCSIZ   51                /* message (and forum) topic size       */
#define HSTSIZ   57                /* message history size                 */
#define FLNSIZ   13                /* DOS filename buffer size             */

struct message {                   /* in-memory message structure          */
     unsigned forum;               /*   ID of forum message belongs to     */
     long msgid;                   /*   unique message identifier          */
     struct globid gmid;           /*   unique global message identifier   */
     long thrid;                   /*   ID of thread message is part of    */
     char from[MAXADR];            /*   originator                         */
     char to[MAXADR];              /*   recipient                          */
     char topic[TPCSIZ];           /*   main topic, editable, carried over */
     char history[HSTSIZ];         /*   history/routing (reply to #88888,  */
                                   /*     fw by Aaaaaaaaa, cc: of #99999)  */
     char attname[FLNSIZ];         /*   attached filename                  */
     unsigned crdate;              /*   message creation date              */
     unsigned crtime;              /*   message creation time of day       */
     struct globid rplto;          /*   message that this is a reply to    */
     int nrpl;                     /*   number of times replied to         */
     long flags;                   /*   message/attachment flag bits       */
};

Applies to: v10

TPCSIZ is 51 in v10 (GME.H:48) as in WG3.2; GMEWRKSZ is 518 under GCDOS and 1536 otherwise (GME.H:42-44): use the macro. MAXPARSZ (GME.H:61) now depends on pointer width (chapter 29, section 29.6).

Applies to: WG3.x

Header check: FLNSIZ (WG2 GCSP.H:254, (MAXFILE+MAXEXT-1), 13) is not defined in WGDEV/INC; struct message.attname is declared CHAR attname[GCMAXFNM] (structs-wg2-to-wg32.json) and fordsk.datfil/attpath use GCSTRPTH (FIOAPI.H:85-87). GCMAXFNM is 13 in the WG2-compatible branch (FIOAPI.H:102).

The most important control fields are the forum ID and the message ID. These two identifiers are both required to find any message on the system.

The forum ID (forum) is a number that uniquely identifies each forum on the system. It is assigned by the engine when a forum is created. The forum ID is used to specify which forum a message resides in. A special forum ID is provided for E-mail:

#define EMLID    0U                /* E-mail destination ID                */

The message ID (msgid) is a number that uniquely identifies each message on the system. It is also assigned by the engine when a message is created.

You can get the highest message ID currently present on the system by calling:

long
himsgid(void);                     /* get current highest message ID       */

Inter-system threading in forums is supported by three fields: thread ID (thrid), global ID (gmid), and reply-to ID (rplto). The thread ID uniquely identifies a thread within a forum (including all systems participating in an echo). It is assigned by the engine whenever a new message is created, and is currently implemented as a 32-bit CRC of the topic of the message that initiates the thread. Replies to messages in a thread are assigned the same thread ID as the message to which they are a reply. Reading messages in a thread is equivalent to reading messages in a forum with the same thread ID.

In addition to the thread ID, the global ID and reply-to ID are used to maintain the parent-child relationship between messages across systems. In addition to a unique message ID, each message is assigned a unique global ID when it is created. The global ID consists of the system ID (an integer representation of the 4-character C/S system ID) of the system on which the message originated and its message ID on that system:

struct globid {                    /* global message identifier            */
     long sysid;                   /*   system ID of originating system    */
     long msgid;                   /*   message ID on originating system   */
};

When an echoed forum message is imported into a system, it is assigned a message ID unique to that system, but it retains its original global ID. When a user replies to a message in a forum, the new message is assigned the same thread ID as the original message, and the global ID of the original message is used as the reply-to ID of the new message. When a thread-to-parent is requested, the system examines the reply-to ID of the current message and looks for a message with that global ID.

To see how this works, consider the following example:

System 1 System 2

Original Message

Message ID: 5
Global ID: 1,5
Reply-to ID: 0,0

Imported Message

Message ID: 23
Global ID: 1,5
Reply-to ID: 0,0

Imported Reply

Message ID: 11
Global ID: 2,27
Reply-to ID: 1,5

Reply to Message

Message ID: 27
Global ID: 2,27
Reply-to ID: 1,5

A message is written on system 1 and echoed to system 2. On system 2 a user replies to this message and the reply is echoed back to system 1. Since the imported reply references the global ID of the original message in its reply-to ID field, a user on system 1 reading the imported reply can correctly thread to its parent.

The from field is the User-ID or address of the person who sent the message. It is also the address to which e-mail replies to the message are sent.

The to field is the User-ID or address of the person to whom the message was or is to be sent.

The attname field is primarily for display purposes. If the message has an attachment, this field should contain a DOS filename by which the attachment will be known. When a user reads the message, this name will be displayed as the filename of the attachment. When a user downloads the attachment, this name will be given to the file transfer protocol as the suggested name for the file.

The history field holds text describing the history of the message (if it is a reply to another message, if it was forwarded by another user, etc.).

The flags field is used to store Boolean information about the message (e.g., is there a file attached, is a return receipt requested, etc.). It is divided into two separate sections. The high order word is used for GME-internal flags. The following flags are currently defined:

                                   /* message flag bits                    */
#define PRIMSG  0x00000001L        /*   message is "priority"              */
#define EXEMPT  0x00000002L        /*   message is exempt from auto-delete */
#define RECREQ  0x00000010L        /*   return-receipt requested when read */
#define FILIND  0x00000020L        /*   "indirect" att, direct has filespec*/
#define FILATT  0x00000040L        /*   file is attached to this message   */
#define FILAPV  0x00000080L        /*   file attached is ok to download    */
#define NODEL   0x00000100L        /*   sender can't delete                */
#define NOMOD   0x00000200L        /*   sender can't modify                */
#define ISMPTR  0x00010000L        /*   message header points to other msg */
#define ISTCPY  0x00020000L        /*   message is complete alias of other */
#define FRCLR   0x00040000L        /*   from field of message "cleared"    */
#define TOCLR   0x00080000L        /*   to field of message "cleared"      */

Finally, the maximum allowed message text length is Sysop-configurable. A global variable, TXTLEN, is initialized to the proper value when GME is initialized:

#define TXTLEN _txtlen             /* message text buffer size             */
unsigned _txtlen;                  /* use TXTLEN, not this                 */

Since other modules may be initialized before GME, a special function is provided for use in init__ routines that will safely return the proper message text length whether GME has been initialized or not:

unsigned                           /*   returns max message text length    */
txtlen(void);                      /* init__ callable get-text-length     */
Message Pointers

There is a special type of message that is used strictly within the engine. It consists of just the header; the body is replaced by a special pointer that points to another message on the system. These are referred to as message pointers.

When you read a message pointer, the engine examines the flags field of the header. If the ISMPTR flag is set, the engine then reads the message that is pointed to by the first message. There are two distinct types of message pointer, and what happens next depends on which type the first message is. If the first message is a regular message pointer, the text of the second message is used with the header of the first message to form a complete message. If the first message has the ISTCPY (true copy) flag set, the text and header of the second message are used in place of the first message. This process is usually completely transparent, but you may need to be aware of it in certain circumstances.

Forum messages directed to a user can appear in the user’s E-mail (depending on the user’s preferences). This is done by placing a true copy message pointer in the E-mail data file that points to the forum message. Thus, when a user reads a forum message to them from E-mail, they see the message exactly as it appears in the forum. Any changes made to a true copy are reflected in the original message, thus any changes made to the message from E-mail will also appear in the forum.

Distribution lists use regular message pointers. First a normal message is written in the E-mail data file, addressed to the list being used. Then a message pointer is written to each address on the list, pointing to the original message.

Regular message pointers cannot be modified (no error code is returned, but the changes do not take effect), so the sender cannot change the individual messages sent to a distribution list. However, the original message can be modified, and any changes to the text will be reflected in all the individual messages.

Error Notification Messages

Applies to: WG2+

If it is necessary to deliver a message that receives no special processing (usually an error message of some kind), you can set the following flag in the message header flags:

#define GMFERR 0x00000400L /* message is an error-notification */

Right now, this flag only disables auto-forwarding. There may be other special processing added later that it disables.

Application-Defined Information

Applies to: WG2+

It is now possible to store and retrieve application-defined information associated with individual messages. This information is:

The contents of the application-defined information is largely up to the application. However, certain minimum formatting requirements must be followed to allow multiple applictions to share the single application-defined information area associated with each message. The maximum size of this area is the same as the maximum message text size: TXTLEN.

The information is stored as a single NUL-terminated ASCII string. Any binary data (in particular, any binary data that may contain zeros) must be encoded somehow. All end-of-line characters must be newline characters ('\n').

This string is subdivided into named sections. Each application can create and manage one or more sections. Sections are divided using a mechanism similar to that used by Windows .ini files. Each section begins with a line with the following format:

[section name]

This must be on a line by itself, with no spaces or other characters before or after it. The section ends when the next section separator or the end of the information string is found.

Section names are defined by the applications with one exception: the first three characters of the section name must be the developer ID of the application that owns the section. This prevents section name conflicts. It is also important to note that section names are case sensitive.

The contents of a section are completely up to the application, with the exceptions noted above. To ease the task of managing sections, the following functions are provided:

char * /* returns pointer to destination */
gmeGetAppSect( /* extract an app-defined info section */
char *dst, /* destination buffer */
const char *src, /* source buffer */
const char *sect); /* section name */

BOOL /* returns TRUE if update successful */
gmeSetAppSect( /* set contents of app info section */
char *dst, /* destination buffer */
const char *src, /* new contents ("" to remove) */
const char *sect); /* section name */

The gmeGetAppSect() function extracts a named section from a buffer containing the entire application-defined information string. The section name passed to this function should not include the enclosing [] characters, and the section separator is not copied into the destination buffer — only the contents of the section.

The gmeSetAppSect() function inserts a named section into an application-defined information string, overwriting (not adding to) any previous contents of that section. Again, the section name should not include the enclosing [] characters, and the contents should not include the section separator. If the new contents passed to this function are an empty string, the entire section, including the separator, will be removed. This function returns FALSE if the new contents are too long to be added. The destination buffer is assumed to be at least TXTLEN in size.

It is important to note when using these functions that the application-defined information string may well contain information from other applications. It is thus imperative that you be careful not to damage the information owned by other applications. By using the above two functions, you can safely extract the information belonging to you, manipulate it in a separate buffer, and then re-insert into the application-defined information string.

To associate information with a message when sending (or importing), initialize the work area as usual, create a buffer containing properly formatted application-defined information (you can use gmeSetAppSect()), then call the following function before calling the send-message function:

void
gmeSetAppInfo( /* set app-defined info (when sending) */
void *workb, /* for this work area */
const char *appinf); /* to this buffer */

This associates the given application-defined information buffer with the given work area. So long as this buffer will remain fixed in memory, it is only necessary to call this function once, before starting the send- message process. However, if there is a chance that the buffer may move in memory between cycles (such as when using pool buffers), you must call this function with the new buffer location before each call to the send-message function.

If multiple messages are being sent at once (using a cc: list or a distribution list), the same application-defined information will be associated with each one. It is possible to use callbacks to associate different information with each message (a maximum of one message will be sent per call to a send-message function), a discussion of the exact process is outside the scope of this document.

To retrieve the application-defined information associated with a given message, you must first read the message. Once the read-message function has returned GMEOK, you can call the following function to retrieve any application-defined information associated with the message:

const char * /* returns pointer to temp buffer */
gmeGetAppInfo(void); /* get app-defined info (after reading) */

This function returns a pointer to a GME-internal buffer containing the application-defined information string. If no application-defined information is associated with the last message read, this function will return an empty string (““).

The contents of this buffer are only valid immediately after the read- message function returns GMEOK — until you cycle or call another GME read- or write-message function. This buffer should also be considered read-only, and you should copy it into your own buffer before modifying it.

Once you have retrieved and modified the application-defined information, you can update it using the following function:

int /* returns standard GME status codes */
gmeModAppInfo( /* modify app-defined info (after read) */
void *workb, /* work area in use */
const char *appinf); /* app-defined info buffer */

Like other after-reading functions (e.g., modmsg(), delmsg(), copymsg()), you must open the work area and initialize the read context. Actually reading the message is technically optional, but you should read the message and retrieve any existing application-defined information before adding yours. Otherwise, the contents of the appinf argument to this function will overwrite any existing application-defined information.

Like write-message functions, this function may require cycling, so the buffers used must maintain their contents across cycles.

The following status codes may be returned:

Forums

The configuration information for forums is stored in a forum definition structure. This structure exists in two distinct forms: an on-disk format and an in-memory format. In addition to the obvious distinction, the two formats are used for different purposes. The on-disk format is used when creating a forum or getting “all info” about the forum. The in-memory format is used in all other contexts.

These two definition formats are as follows:

#define FORNSZ   16                /* forum name size                      */
#define MAXDIR   66                /* maximum DOS directory spec length    */
#define MAXPATH  80                /* maximum DOS path+filename length     */

struct fordef {                    /* in-memory forum definition struct    */
     unsigned forum;               /*   unique forum identifier            */
     char name[FORNSZ];            /*   forum name                         */
     char topic[TPCSIZ];           /*   short description/topic            */
     char forop[UIDSIZ];           /*   User-ID of Forum-Op                */
     int dfnum;                    /*   index of forum's data file in array*/
     char *attpath;                /*   path where attachments are stored  */
     unsigned nthrs;               /*   number of threads in forum         */
     unsigned nmsgs;               /*   number of messages in forum        */
     unsigned nfiles;              /*   number of files in forum           */
     unsigned nw4app;              /*   number of files waiting for apprvl */
     char forlok[KEYSIZ];          /*   key required for privileged access */
     unsigned char dfnpv;          /*   default non-priv access setting    */
     unsigned char dfprv;          /*   default priviledged access setting */
     unsigned char mxnpv;          /*   maximum non-priv access setting    */
     int msglif;                   /*   message lifetime (days)            */
     int chgmsg;                   /*   charge per message posted          */
     int chgrdm;                   /*   charge per message read            */
     int chgatt;                   /*   charge per file attachment uploaded*/
     int chgadl;                   /*   charge per file attachment download*/
     int chgupk;                   /*   charge per-kbyte for upload        */
     int chgdpk;                   /*   charge per-kbyte for download      */
     int ccr;                      /*   credit consumption rate            */
     unsigned char pfnlvl;         /*   profanity suppression level        */
     unsigned crdate;              /*   forum creation date                */
     unsigned crtime;              /*   forum creation time of day         */
     unsigned seqid;               /*   number of forum in list of forums  */
     int necho;                    /*   number of echo addresses           */
     char *echoes;                 /*   pointer to echo address array      */
};
struct fordsk {                    /* on-disk forum definition structure   */
     unsigned forum;               /*   unique forum identifier            */
     char name[FORNSZ];            /*   forum name                         */
     char topic[TPCSIZ];           /*   short description/topic            */
     char forop[UIDSIZ];           /*   forum-op                           */
     char datfil[MAXPATH];         /*   path+filename of forum data file   */
     char attpath[MAXDIR];         /*   path where attachments are stored  */
     unsigned nthrs;               /*   number of threads in forum         */
     unsigned nmsgs;               /*   number of messages in forum        */
     unsigned nfiles;              /*   number of files in forum           */
     unsigned nw4app;              /*   number of files waiting for apprvl */
     char forlok[KEYSIZ];          /*   key required for privileged access */
     int dfnpv;                    /*   default non-privileged access      */
     int dfprv;                    /*   default privileged access setting  */
     int mxnpv;                    /*   maximum non-privileged access      */
     int msglif;                   /*   message lifetime (days)            */
     int chgmsg;                   /*   charge per message posted          */
     int chgrdm;                   /*   charge per message read            */
     int chgatt;                   /*   charge per file attachment uploaded*/
     int chgadl;                   /*   charge per file attachment download*/
     int chgupk;                   /*   charge per-kbyte for upload        */
     int chgdpk;                   /*   charge per-kbyte for download      */
     int ccr;                      /*   credit consumption rate            */
     int pfnlvl;                   /*   profanity suppression level        */
     unsigned crdate;              /*   forum creation date                */
     unsigned crtime;              /*   forum creation time of day         */
     int necho;                    /*   number of echo addresses           */
     unsigned seqid;               /*   number of forum in list of forums  */
     char spare[8];                /*   spare space, decrease when adding  */
     char info[1];                 /*   variable-length forum info         */
                                   /*   echo addresses (if any)            */
                                   /*   description/help message           */
};

#define DFTPFN 4                   /* use pfceil for profanity check       */
#define MAXFDV (16384-sizeof(struct fordsk)-1)
                                   /* max variable part of forum definition*/

The forum field is a unique number assigned to each forum when it is created (see page 196).

The name field is a short, memorable name for the forum. It is used by users when selecting the forum, and is typically displayed when reading messages. It can be up to 15 displayable ASCII characters long, excluding spaces, @ and ;

Forum messages can be stored in a single file, or distributed across many files. There is one restriction in this regard: all the messages in a single forum must be stored in the same file. The complete path and filename of the data file in which messages in this forum are stored is in the datfil field. Likewise, attachments to forum messages can be stored wherever you like, but all attachments in a single forum will reside in the same directory. The directory in which attachments to messages in this forum are stored is in the attpath field.

The system-wide profanity suppression level can be overridden on a forum-by-forum basis. The pfnlvl field may be set to one of the standard (0-3) profanity levels, or DFTPFN to use the system-wide profanity level.

Since forums are not stored with a set order, the seqid field is provided as the means to create a custom sequence of forums (the order in which they appear in a list of forums for terminal-mode users — C/S users always see them in alphabetical order). The sequence IDs are always continuous from zero up to the number of forums minus one.

Each forum may have multiple echo addresses. The number of echo addresses is stored in the necho field. The addresses themselves are stored in an array of fixed-length strings — each one MAXADR long. This array is stored in the first necho*MAXADR bytes of the info field when stored on disk. When in memory the echo addresses are stored in a separate buffer pointed to by the echoes field of the fordef structure. The number of echoes per forum is limited by the maximum record size.

The rest of the info field is used for a long description/help message. This is a nul-terminated string for Sysops to provide additional information on a forum that they think would be useful to their users. This text is displayed when a C/S user requests details on a forum and when a terminal-mode user requests help from the main Forums menu. The length of this text is limited to MAXFDV-necho*MAXADR.

GME Initialization

Most initialization of GME is handled internally. However, there is some per-user information maintained by GME that must be initialized when a user logs on and closed when the user hangs up. These functions are as follows:

int                                /*   returns GME status code            */
inigmeu(void);                     /* initialize GME/user stuff at logon   */
                                   /*   (must be called by user interface) */
void                               /* (must be called by user interface)   */
clsgmeu(void);                     /* close GME/user stuff at logoff       */

The function inigmeu() returns the status code GMERST if the user’s E-mail high message pointer has been corrupted (and resets said pointer to zero). Otherwise it returns GMEOK.

To see if a user’s quickscan record has been loaded yet, you can use the following function or macro:

#define qsonsys(uid) (onsqsp(uid) != NULL)
struct qscfg *                     /*   returns NULL if not found          */
onsqsp(                            /* get online user's quickscan          */
char *uid);                        /*   given User-ID                      */

Note: If the standard E-mail/Forums user interface module (GALMSG.DLL) is being used, you should not call inigmeu() or clsgmeu() as the standard E-mail/Forums module will do so.

Applies to: WG2+

If you need to access GME functions or configurable parameters during initialization, you can call the following function to ensure that the GME has been properly initialized before accessing it:

void
init__galme(void); /* GME initialization function */

Applies to: WG2+

Header check (GME.H, GMEOFF.H): init__galme() is declared in GME.H. In WG1 GMEOFF.H the offline initializer was the function iniogme(); in WG2 GMEOFF.H it is #define iniogme init__galme, so existing offline code that calls iniogme() still compiles. clsogme(BOOL updfors) is unchanged.

System ID

Applies to: WG2+

The following function can be used to get the GME system ID:

long
gmeSysID(void); /* get current GME System-ID */

Sending Messages

Sending of messages is divided into two fundamentally different types:

messages sent on behalf of a user (e.g., Joe writes a message to Sysop)messages sent by processes (e.g., a Shopping Mall product sending a “Thank you for buying something” message) Sending a message is a multi-step process involving access and credit checks (when sending from a user), preparation of the message packet itself, and cycling the sending of the message. Both e-mail and forum messages use the same send-message functions.

Validation

To send a message on behalf of a user, you must first initialize a work area that will be used throughout the send-message request. Next, the address to which the message is to be sent and any features (e.g., attachments, return receipts, etc.) must be validated. The validation process checks whether the address to send to exists (or a given feature is available) and whether the user sending the message has enough access and credits to send the message (or use a particular feature).

The functions used to do this validation are:

int                                /*   returns VAL code                   */
valadr(                            /* validate address                     */
void *workb,                       /*   GME work space                     */
char *from,                        /*   User-ID writing the message        */
char *to,                          /*   to address                         */
unsigned forum);                   /*   forum message being written in     */
int                                /*   returns VAL code                   */
valatt(                            /* validate file attachments            */
void *workb,                       /*   GME work space                     */
char *from,                        /*   User-ID writing the message        */
char *to,                          /*   to address                         */
unsigned forum);                   /*   forum message being written in     */
int                                /*   returns VAL code                   */
valrrr(                            /* validate return receipt request      */
void *workb,                       /*   GME work space                     */
char *from,                        /*   User-ID writing the message        */
char *to,                          /*   to address                         */
unsigned forum);                   /*   forum message being written in     */
int                                /*   returns VAL code                   */
valpri(                            /* validate priority messaging          */
void *workb,                       /*   GME work space                     */
char *from,                        /*   User-ID writing the message        */
char *to,                          /*   to address                         */
unsigned forum);                   /*   forum message being written in     */

The from parameter to these functions is the User-ID of the person sending the message (and it must be a valid User-ID), the to parameter is the address the message will be sent to, and the forum parameter is the forum ID of the destination forum (or EMLID for E-mail).

These functions return special feature validation codes which are defined as follows:

                                   /* feature validation codes             */
#define VALYES   1                 /*   feature is available               */
#define VALNO   -1                 /*   feature is not available           */
#define VALACC  -2                 /*   user doesn't have access           */
#define VALCRD  -3                 /*   user doesn't have enough credits   */

You must validate each feature used, but it will not hurt anything to validate a feature and not use it. The return value from any given function applies only to the feature it checks. So if valatt() returns VALCRD, valrrr() will not necessarily return VALCRD.

A few things to note when using the valxxx() functions: access is always checked before credits. So if one of the functions returns VALCRD, the user does have access. The VALNO return code means that the address does not exist or the feature is not available for the given destination (e.g., valrrr() when writing to a forum always returns VALNO since forum messages can’t have return receipts).

The valadr() function is a special case among these functions. If valadr() does not return VALYES, the message cannot be sent at all. You should always call valadr() first. Also, the to parameter passed to valadr() must be a writeable buffer at least MAXADR bytes long. This is because valadr() will fix up the to address by, for example, applying proper case to User-IDs. It will also try to auto-sense the appropriate exporter for an address (and add the appropriate prefix) if the address is clearly not a User-ID, forum, or distribution list.

Note: You must use the same parameters for each of these functions, and you must use the same values when forming the message packet. In other words, the same from, to, and forum must be used throughout. If you need to change one of these after validation, you must re-validate.

The return codes from the valxxx() functions can be converted into standard GME status codes using the following function:

int                                /*   returns standard GME status code   */
val2gme(                           /* convert a VAL code to status code    */
int valcode);                      /*   VAL code to convert                */

which returns the following correspondences:

     VALYES == GMEOK
     VALNO  == GMEERR
     VALACC == GMEACC
     VALCRD == GMECRD

To quickly check the current user’s access and credits when writing e-mail, you can use:

int                                /*   returns VAL code                   */
wrtany(void);                      /* can current user E-mail anyone       */
                                   /*   (other than Sysop)                 */

This function will return VALYES if the user has access and enough credits to write e-mail, VALACC if the user doesn’t have access to write e-mail, or VALCRD if the user doesn’t have enough credits. As with the valxxx() functions, if the return code is VALCRD, the user does have access.

Forming the Message Packet

The message packet consists of the filled-out message header, message body text, file attachment (if any), and cc: address list (if any). This entire packet must be completed before the message can be sent.

The following fields of the message header must be initialized before sending the message: forum, from, to, topic, attname, and flags.

The forum, from, and to fields should be initialized with those values passed to the validation functions (remember that valadr() fixes up the to address, so you should copy the message header to field directly from the buffer passed to valadr()). The topic will typically be supplied by the user, and the attname field should be filled in with a valid DOS filename if there is an attachment. The flags that must be initialized are: PRIMSG, RECREQ, FILATT, and FILIND. All other flags and fields will be filled in by the engine.

Requesting return receipts and priority messages is fairly straightforward — just set the appropriate flag. Attaching a file is a bit more involved. Indirect file attachments (where the files are already on a drive available to the server) are fairly simple: set the FILATT and FILIND flags, then pass the path and filename of the file to be attached to the send-message function (discussed below). For a direct attachment (where the files are on a user's PC and must be uploaded to the server), you must first fill in all the message header fields discussed above (except attname), set the FILATT flag, clear the FILIND flag, then call:

char *                             /*   path & filename to place file in   */
ulname(                            /* path & filename to upload att to     */
struct message *msg);              /*   header of message to attach to     */

passing it your filled-out message header. This will return a pointer to a temporary buffer containing the path and filename into which you must upload (or copy) the direct attachment. You must also copy this path and filename into your own buffer so that you can pass it to the send-message function. When you upload the attachment, you can fill in the attname field with the filename reported by the upload protocol (if the protocol supports this) and/or prompt the user for the filename.

With a filled-out message header, you can use the following function to determine what the total cost to send the message will be:

long
sendchg(                           /* total charges to send a message      */
void *workb,                       /*   work area in use                   */
struct message *msg,               /*   new message structure              */
long attsiz);                      /*   attachment size                    */

The address and any features specified in the message header must have been validated before calling sendchg().

Carbon copies are sent as part of a send-message request. This is done by providing a carbon copy list to the send-message function. This list is just a series of addresses separated by semi**;**colons. These addresses can be any of the four types of addresses supported by GME (User-IDs, forums, exported addresses, and distribution lists).

Individual addresses can be parsed out of this list using the function:

char *                             /*   ptr to next entry (NULL if done)   */
parscc(                            /* parse next cc: from list             */
char *addr,                        /*   buffer to put cc: address into     */
char *list);                       /*   ';'-delimited cc: list             */

This function is designed for sequential parsing of the cc: list. It takes a pointer to the start of the list (or the beginning of an address), copies the first address into the supplied buffer, and returns a pointer to the start of the next address in the list.

The carbon copy addresses need not be validated — the engine will check each address before sending a copy. It will strip off any unsupported features (e.g., return receipt to a forum). The engine will not send the copy if the address is invalid or the user doesn’t have enough access or credits to send the copy.

You may use the above validation functions to check the cc: addresses but, if you do, you must not use the same work area to check a cc: address as you are using for the message itself.

Sending the Message

Once the message packet is complete, the message is sent by calling:

int                                /*   returns standard GME status codes  */
sendmsg(                           /* send a new message from a user       */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   new message structure              */
char *text,                        /*   message body text                  */
char *filatt,                      /*   path+filename of att (if any)      */
char *cclist);                     /*   list of cc: addresses (if any)     */

Applies to: WG3.x

Header check: sendmsg() is not declared in WGDEV/INC. The same call (work area, message packet, text, attachment, cc list) is gmeSendMsg(VOID *pWork, struct message *msg, const CHAR *text, const CHAR *filatt, const CHAR *cclist) (GME.H:1551). The non-user-specific senders are simpsnd() and gsndmsg() (GME.H:1537,1544). The text states that sendmsg() closes the work area; the status codes (GMEAGAIN etc.) are unchanged.

This function sends the primary message (including forum echoes, if any), then starts sending the carbon copies. To indicate no carbon copies, either pass NULL for the cclist parameter or pass an empty string for cclist (i.e., cclist[0] == '\0'). Since this function may require cycling (definitely if the message is to a distribution list or has carbon copies), all parameters must retain their contents across cycles (i.e., don’t use vdatmp). The text, filatt, and cclist parameters are considered read-only by the engine, but the work area and the message header buffer must be writeable by the engine.

Upon completion sendmsg() will automatically close the work area passed to it. The following status codes may be returned:

GMEAGAIN Cycle, then call sendmsg() again.

GMEOK The message has been sent successfully.

GMEAFWD The message has been sent successfully and has been auto-forwarded. The original addressee is in the to field of the message header, and the address to which the message was forwarded can be gotten by calling gmexinf().

GMEERR The message packet was not properly formed or not all the features used were validated.

GMECRD The user does not have enough credits to send the message.

GMEIVA The file attachment specified in the filatt parameter could not be found or was not in the right place (if direct).

GMENOAT The file attachment could not be attached to the message for some reason.

GMEMEM There was not enough free memory to process a !QUICK list.

Other error status codes may be added in later versions or returned by exporters, so you should always have a default case when handling error codes.

If an error does occur, you cannot just correct it and try again. You will have to start over from scratch — reinitialize the work area, form and validate the message header again, and try uploading the file again.

This function will generate the following callback events (page 194) as appropriate:

EVTSTRT Starting to send message to primary addressee. If the primary addressee is a distribution list, the EVTDSTS event will precede this event, and this event will be generated for each address in the list. gmexinf() returns the address to which the message is to be sent.

EVTDONE Done sending message to primary addressee. This event will not be generated if the primary addressee is not a distribution list and there are no carbon copies to be sent. Otherwise, it will be generated for each message sent (the primary message, and each address in a cc: list or distribution list). gmexinf() returns the address to which the message was sent. This would be the forwardee if the message was auto-forwarded and the forum address (the forum name preceded by a /) if the message was sent to a forum. When this callback event occurs, the status code passed to your callback handler may be any of the ones listed on page 209.

EVTCCST Starting to send carbon copies.

EVTDSTS Starting to process a distribution list. This may be the primary addressee or one of the cc: addresses. gmexinf() returns the list name.

EVTDSTD Finished processing a distribution list.

EVTCPYS Starting to copy file attachment. This may occur due to the message being sent to an exported address or to a cc: address. gmexinf() returns the path and filename being copied to.

EVTCPYD Finished copying file attachment. gmexinf() returns the path and filename copied to.

Sending a Message From a Process

If you need to send a message that is not from a specific user (for example, a game module that sends a “Congratulations! You won last week’s lotto drawing...” message), you can use the following function:

int                                /*   returns standard GME status codes  */
gsndmsg(                           /* send message (non-user specific)     */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   new message structure              */
char *text,                        /*   message body text                  */
char *filatt);                     /*   path+filename of att (if any)      */

Using this function is very similar to using sendmsg() — you must form the message packet, initialize a work area, cycle the function until it finishes, and it closes the work area when done. The primary difference is that you do not need to validate the message before sending it.

You must fill in the same message header fields when forming the message packet. However, since the message is not validated, you must make sure that the message header fields are correctly filled in and all necessary flags are set. In general, it is best to setmem() the message header to all-zero first, then fill in the required fields.

Note that you can set any of the non-system message flags. In particular, if you are sending an e-mail message with an attachment (or a forum message for which you want the attachment pre-approved), you must set the FILAPV flag in addition to the FILATT flag.

You must also be sure that you do not include any unsupported features with your message (e.g., don’t set the PRIMSG flag for a forum message, or try to send an attachment to an exporter that doesn’t support attachments). Finally, this function can not be used to send a message to a distribution list — only User-IDs, forums, or exported addresses are supported.

The following status codes (other than GMEAGAIN) may be returned by gsndmsg():

GMEAGAIN Cycle, then call gsndmsg() again.

GMEOK The message has been sent successfully.

GMEERR The message packet was not properly formed.

GMENOAT The file attachment could not be attached to the message for some reason.

Other error codes may be added later or returned by exporters.

To determine whether the address you want to send the message to is valid or not, you can use one of the following functions:

BOOL
adrxst(                            /* does this address exist?             */
char *adr);                        /*   address to check                   */
BOOL                               /*   returns TRUE if address exists     */
fixadr(                            /* fix up an address                    */
char *from,                        /*   User-ID of sender (NULL for any)   */
char *adr);                        /*   address to fix up                  */

The function adrxst() will return TRUE or FALSE depending on whether the address exists or not. The function fixadr() will fix up the address as well (e.g., apply correct capitalization to a User-ID). The from parameter to fixadr() is used for auto-sensing the correct exporter (if a prefix is not supplied) based on the user’s access to the exporters. To include all exporters in the auto-sensing, pass NULL for the from parameter.

If for some reason you absolutely cannot cycle the message-sending process, you can use the following function to send a message:

int                                /*   returns standard GME status codes  */
simpsnd(                           /* simple send msg (non-user specific)  */
struct message *msg,               /*   message header structure           */
char *text,                        /*   message body text                  */
char *filatt);                     /*   path+filename of att (if any)      */

This function requires the same message preparation as gsndmsg(), but it does not require a work area or cycling. The return code may be any of the codes returned by gsndmsg(), including GMEAGAIN. If simpsnd() returns GMEAGAIN you do not need to call it again, it just means that the message has been added to a queue and will be sent by a background task.

You should avoid using simpsnd() whenever possible because it is much less efficient than gsndmsg() and there is a greater possibility that messages sent using simpsnd() will get “lost in transit” due to a system crash.

Reading Messages

Reading messages is done as an ongoing request. You set up a context in which you will read messages, then you can read multiple messages within that context. The work area is initialized once, and does not have to be closed or re-initialized when changing contexts. Both E-mail and Forums use the same function calls to read messages.

Setting the Context

The read context consists of the User-ID for whom the messages are being read, the current forum ID, message ID, thread ID, and message sequence.

The User-ID part of the context is used for access and credit checks, so that the user need not be online while the messages are being read.

The message sequence specifies what type of messages you want to read (e.g., e-mail messages to you, forum messages in a thread, etc.). The following sequence codes are supported:

                                   /* message reading sequence codes       */
#define ESQTOU 1                   /*   E-mail to user sequence            */
#define ESQFRU 2                   /*   E-mail from user sequence          */
#define ESQTHR 3                   /*   E-mail thread sequence             */
#define FSQFOR 4                   /*   Forum normal sequence              */
#define FSQTHR 5                   /*   Forum thread sequence              */
#define FSQSCN 6                   /*   Forum one-time scan sequence       */

Note that separate sequence codes are used for E-mail and Forums.

After initializing a work area to be used for reading, and before starting to read messages, the context must be initialized. This can be done with one of the following functions calls:

void
inictx(                            /* initialize read context              */
void *workb,                       /*   work area to initialize            */
char *userid,                      /*   user ID doing reading              */
int sequence,                      /*   sequence to use                    */
unsigned forum,                    /*   forum to read from                 */
long msgid,                        /*   message to start at                */
long thrid);                       /*   thread to use (if any)             */
void
inormrd(                           /* initialize "normal" read context     */
void *workb,                       /*   work area to initialize            */
char *userid,                      /*   user ID doing reading              */
unsigned forum,                    /*   forum to read from                 */
long msgid);                       /*   message to start at                */

The function inictx() gives complete control over what goes into the read context. The function inormrd() is simpler to use, and initializes the sequence based on the forum ID given. For E-mail the sequence is initialized to ESQTOU (messages to the user); for Forums the sequence used is FSQFOR (all messages in the forum).

To read new messages, the message ID part of the read context can be initialized using the following function:

long
firstnew(                          /* get first new message #              */
char *userid,                      /*   for this user ID                   */
unsigned forum);                   /*   in this forum                      */

This function actually returns the highest message number read in the given forum (which can be EMLID). You can then read the next message to get new messages.

Two constants are also defined to indicated the first message and the last message when setting the read context:

#define FIRSTM   0L                /* "first message" code, for searches   */
#define LASTM    0x7FFFFFFFL       /* "last message" code, for searches    */

The read context can be altered without closing the work area. This can be done using the above two functions, or a single element of the read context can be altered using one of the following functions:

void
seqctx(                            /* change sequence of read context      */
void *workb,                       /*   work area in use                   */
int sequence);                     /*   sequence to change to              */
void
forctx(                            /* change forum of read context         */
void *workb,                       /*   work area in use                   */
unsigned forum,                    /*   forum to change to                 */
int sequence);                     /*   new sequence to establish          */
void
msgctx(                            /* change cur message of read context   */
void *workb,                       /*   work area in use                   */
long msgid);                       /*   message ID to change to            */
void
thrctx(                            /* change thread of read context        */
void *workb,                       /*   work area in use                   */
long thrid);                       /*   thread ID to change to             */
Reading Messages

Once the read context has been initialized, messages can be read using several different functions. All of these functions return GME status codes and may require cycling. A special property of these functions is that the buffer the message is read into is only required on the last cycle. So a temporary buffer (like vdatmp) can be used.

The following functions are the normal message reading functions:

int                                /*   returns standard GME status codes  */
readmsg(                           /* read current message in context      */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure buffer    */
char *text);                       /*   message body text buffer           */
int                                /*   returns standard GME status codes  */
nextmsg(                           /* read next message in context         */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure buffer    */
char *text);                       /*   message body text buffer           */
int                                /*   returns standard GME status codes  */
prevmsg(                           /* read previous message in context     */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure buffer    */
char *text);                       /*   message body text buffer           */

To read the message nearest the current message in context, the following function can be used:

int                                /*   returns standard GME status codes  */
nearmsg(                           /* read nearest to cur msg in context   */
void *workb,                       /*   GME work space (provided by caller)*/
int nearop,                        /*   get near "style" to use            */
struct message *msg,               /*   message header structure buffer    */
char *text);                       /*   message body text buffer           */

where the nearop argument can have one of the following values:

                                   /* read nearest message "style" codes   */
#define LEGT 0                     /*   try less/equal then greater        */
#define LTGE 1                     /*   try less then greater/equal        */
#define GELT 2                     /*   try greater/equal then less        */
#define GTLE 3                     /*   try greater then less/equal        */

These codes specify how nearmsg() should determine what is the nearest message. For example, if LEGT is used, the engine will first try to find a message less than or equal to the current message in the read context. If it can’t find one less than or equal, it will then try to find one that is greater than the current message. Note that less than and greater than are within the current sequence context.

Note: nearmsg() cannot be used if the sequence is FSQSCN.

To read the next or previous message in a given sequence without changing the current sequence context, use the following functions:

int                                /*   returns standard GME status codes  */
nextseq(                           /* read next message a sequence         */
void *workb,                       /*   GME work space (provided by caller)*/
int sequence,                      /*   sequence to use                    */
struct message *msg,               /*   message header structure buffer    */
char *text);                       /*   message body text buffer           */
int                                /*   returns standard GME status codes  */
prevseq(                           /* read previous message in a sequence  */
void *workb,                       /*   GME work space (provided by caller)*/
int sequence,                      /*   sequence to use                    */
struct message *msg,               /*   message header structure buffer    */
char *text);                       /*   message body text buffer           */

To read the parent of the current message (the message to which the current message is a reply), use this function:

int                                /*   returns standard GME status codes  */
readpar(                           /* read parent of message               */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure buffer    */
char *text);                       /*   message body text buffer           */

You do not actually have to read the current message before reading its parent. Just setting the context is sufficient.

These read-message functions may return one of the following status codes:

GMEAGAIN Cycle, then call the read-message function again.

GMEOK Found the requested message.

GMEERR The read context was not correctly initialized, or the current message was not found when calling readpar(), or nearmsg() was called with the FSQSCN sequence (searching for messages and the FSQSCN sequence are discussed in the section on One-Time Search, below).

GMENFND Requested message could not be found.

GMEACC User does not have access to read requested message.

GMECRD User does not have enough credits to read requested message.

Note: the msg and text buffers are not altered by the read-message functions unless a message is found. And as always, other error codes may be added later.

Formatted Text Messages

Applies to: WG2+

One of the major new features of the Major BBS mail system is the ability to send messages with formatting in the body text (fonts, colors, variable margins and tabs, etc.).

An extensible API is available (through the GALTEXT module) to convert formatted text to plain ASCII text. At this time, however, only Microsoft’s Rich Text Format (see Microsoft Product Support Services Application Note GC0165 for a complete specification) is supported by the Galacticomm mail client, so no other format should be used for messages that may possibly be accessed by Client/Server users.

In order to maintain compatibility with existing code, all previously existing functions that returned message body text will automatically remove any formatting from the text and return plain ASCII text.

Consequently, a new suite of functions have been introduced to allow the retrieval of formatted text. The primary one is:

int                     /*   returns standard GME status codes  */
frdmsg(                 /* read message in context (keep format)*/
void *workb,            /*   GME work space (provided by caller)*/
int direct,             /*   read direction code                */
struct message *msg,    /*   message header structure buffer    */
char *text);            /*   message body text buffer           */

This function returns the same status codes as previous read-message functions. It takes one of the following read direction codes:

                        /* message read direction codes         */
#define RDLEGT 0        /*   get near, less/equal then greater  */
#define RDLTGE 1        /*   get near, less then greater/equal  */
#define RDGELT 2        /*   get near, greater/equal then less  */
#define RDGTLE 3        /*   get near, greater then less/equal  */
#define RDNEXT 4        /*   get next message                   */
#define RDPREV 5        /*   get previous message               */
#define RDEXCT 6        /*   get exact message number           */

A set of macros that mimic the syntax of the original read-message functions are defined to simplify the use of this function:

#define readmsgf(wrk,msg,txt) frdmsg((wrk),RDEXCT,(msg),(txt))
#define nextmsgf(wrk,msg,txt) frdmsg((wrk),RDNEXT,(msg),(txt))
#define prevmsgf(wrk,msg,txt) frdmsg((wrk),RDPREV,(msg),(txt))
#define nearmsgf frdmsg

The following functions and macros are also new and mimic the functionality of previously existing functions. These should be used when dealing with formatted text:

int                     /*   returns standard GME status codes  */
frdseq(                 /* read message in a sequence           */
void *workb,            /*   GME work space (provided by caller)*/
int direct,             /*   read direction code                */
int sequence,           /*   sequence to use                    */
struct message *msg,    /*   message header structure buffer    */
char *text);            /*   message body text buffer           */
#define nextseqf(wrk,seq,msg,txt) frdseq((wrk),RDNEXT,(seq),(msg),(txt))
#define prevseqf(wrk,seq,msg,txt) frdseq((wrk),RDPREV,(seq),(msg),(txt))
int                     /*   returns standard GME status codes  */
readparf(               /* read parent of message (keep format) */
void *workb,            /*   GME work space (provided by caller)*/
struct message *msg,    /*   message header structure buffer    */
char *text);            /*   message body text buffer           */
int                     /*   returns standard GME status codes  */
markreadf(              /* mark a message as read (keep format) */
void *workb,            /*   GME work space (provided by caller)*/
struct message *msg,    /*   message header structure buffer    */
char *text);            /*   message body text buffer           */

All new functions (such as the generic functions discussed below) that return message body text will return formatted text. It is up to the caller to convert that text to plain ASCII if necessary.

Applies to: WG2+

Header check (GME.H, GMELOC.H): the read direction codes RDLEGT, RDLTGE, RDGELT, RDGTLE, RDNEXT, RDPREV and RDEXCT now live in GME.H. The nearmsg() "style" codes shown above (LEGT, LTGE, GELT, GTLE) are still defined, but as aliases: #define LEGT RDLEGT etc., with the same values 0-3. The RD* values were renumbered in WG2: RDLEGT 3->0, RDLTGE 4->1, RDGELT 5->2, RDGTLE 6->3, RDNEXT 1->4, RDPREV 2->5, RDEXCT 0->6. Code that hard-coded the old numbers, or was compiled against the WG1 headers, must be rebuilt.

Reading by Global ID

Applies to: WG2+

The following function can be used to read a message given its global ID:

int /* returns standard GME status codes */
gmeGReadGlob( /* read forum msg given global ID */
void *workb, /* GME work space (provided by caller)*/
struct globid *globid, /* global ID to read */
struct message *msg, /* message header structure buffer */
char *text); /* message body text buffer */

This function is similar to other read-message functions. You must initialize the work area and the read context before calling it. Note that this can only be used to read forum messages (not e-mail messages).

The following status codes may be returned:

After Reading a Message

After the user has read a message, the message should be marked as having been read. When a message is marked read, any per-message read charges are deducted from the user’s account, the highest message read in the current forum is updated if necessary, and return receipts are generated if necessary.

This is all done by the following function:

int                                /*   returns standard GME status codes  */
markread(                          /* mark a message as read               */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure buffer    */
char *text);                       /*   message body text buffer           */

There are a couple things you must do to use this function correctly. First, the message must have been read before calling this function, and the msg parameter passed to markread() without being altered. Some functions which rely on the read context (see While Reading Messages on page 218) will work properly with only the read context, this one will not. Second, this function may require cycling, so the buffers passed to it must retain their contents across cycles.

The following status codes may be returned by this function:

GMEAGAIN Cycle, then call markread() again.

GMEOK The message has been marked read.

GMERRG A return receipt was generated.

GMEAFWD A return receipt was generated and it was auto-forwarded. The address to which it was forwarded can be gotten from gmexinf().

GMEERR The read context was not correctly initialized or the from address specified an exporter that is not available (and a return receipt was to be generated).

GMENRGM The engine was unable to re-read the message after generating a return receipt, so the contents of the msg and text buffers are invalid.

Other error codes may be added later or returned by exporters. In any event, if an error code is returned, the contents of the msg and text buffers should be considered invalid.

The meaning of “the user has read a message” can vary depending on the implementation.

In terminal-mode E-mail/Forums, a message is marked read only after the body text of the message is displayed to the user.

In C/S E-mail, the messages must be delivered to the client before they can be read by the user. In this case, the messages are marked read on the server as they are delivered to the client, before the user has actually seen them displayed on his screen.

Applies to: v10

Not in v10. The Client/Server (Visual Basic client app) mode was removed in v10 (MBBS10.txt section 2; the v10 history has the commit "Initial port of GALTELE including removal of AHTML and CS related code"). Read this passage as WG1-3.x history only. Only the terminal-mode read-marking applies.

In C/S Forums, there are two types of dynapak for reading messages. One type returns only the header information while the other returns the whole message (header and body). In this case, the whole-message dynapak calls markread() while the header-only dynapak does not.

One thing to note is that this function will clear the return-receipt-requested flag (RECREQ) of the message after generating a return receipt. So if you need to know whether a return receipt was requested after calling markread(), you will need to save that information in your own format and not rely on the flags field of the message header.

While Reading Messages

Download Attachment

Since access restrictions and credit charges apply when downloading attachments, GME provides a set of functions to manage access, credit charges, and auditing attachment downloads. These functions can be used to tag an attachment then download it later. The actual transfer is not handled by GME: if terminal mode, download it via the File Transfer Service (page 169); if C/S mode, download it as a file dynapak (Agent Developer’s Guide).

First initialize the read context and read the message. Then tag the attachment, using the following function:

int                                /*   returns standard GME result codes  */
tagatt(                            /* create tag for message attachment    */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure           */
char *tag);                        /*   file tag buffer to use             */

It will generate a GME-specific tag structure and put it in the tag argument. The buffer used for the tag should be at least TSLENG bytes long. This tag is then used for all subsequent operations.

The tagatt() function does not require cycling and may return one of the following status codes:

GMEOK The attachment has been tagged and the GME-specific tag information stored in the tag argument.

GMEACC The user does not have access to download the attachment.

GMECRD The user does not have enough credits to download the attachment.

GMENAPV The attachment has not been approved for download.

GMENFND The attachment file could not be found.

To get the path and filename to download from, call:

char *                             /*   path & filename of attachment      */
dlname(                            /* path & filename to dnload att from   */
struct message *msg);              /*   header of message with attachment  */

This returns a pointer to a temporary buffer.

When the download is to begin, call this function:

BOOL                               /*   ok to start download?              */
dlstart(                           /* starting to dnload tagged attachment */
char *tag);                        /*   file tag structure in use          */

It will return FALSE if the user has run out of credits since tagging the attachment.

If the download is aborted, call this function:

void
dlabt(                             /* attachment download aborted          */
char *tag);                        /*   file tag structure in use          */

And when the download successfully completes, call this function:

void
dldone(                            /* attachment download finished         */
char *tag);                        /*   file tag structure in use          */

These three functions require that the user doing the downloading be online and be the current user.

If your application operates in the background or does not have to worry about the download possibly being aborted, you can use the following function instead:

BOOL                               /*   ok to download?                    */
gdlatt(                            /* tagged attachment downloaded for user*/
char *userid,                      /*   User-ID attachment downloaded for  */
char *tag);                        /*   file tag structure in use          */

Call this function before you start your transfer, to be sure it’s still ok for the user to download the file.

To get various information about a tagged attachment, the following functions are provided:

struct message *                   /*   pointer to temporary msg struct    */
tagmsg(                            /* get tagged message                   */
char *tag);                        /*   file tag structure in use          */
long
msgintg(                           /* what's the message ID associated     */
char *tag);                        /*   with this tag?                     */
unsigned
forintg(                           /* what's the forum ID associated       */
char *tag);                        /*   with this tag?                     */
Reply to Message

To reply to a message, the read context must be initialized and the message must be read. After reading the message, the process is very similar to writing a new message. The message packet must be formed and validated using the same functions, and the same fields in the message header must be filled in.

The difference is that you must start with the header from the message you just read, and only change the following fields: from, to, topic, attname, and flags (PRIMSG, RECREQ, FILATT, and FILIND may be set, all others should be cleared). The from field of the original message should be copied into the to field, and the current user’s User-ID copied into the from field. The forum field usually will not need to be changed unless it is an E-mail reply to a forum message, in which case the forum should be changed to EMLID. No other fields should be changed.

The function to call to send the reply is:

int                                /*   returns standard GME status codes  */
reply(                             /* reply to current message in context  */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure           */
char *text,                        /*   new message text                   */
char *filatt,                      /*   path+filename of att (if any)      */
char *cclist);                     /*   list of cc: addresses (if any)     */

The arguments to this function have the same meaning and requirements as the arguments to sendmsg(). The status codes returned are the same as those returned by sendmsg(). When reply() finishes, it closes the work area, so you must re-initialize the work area and the read context before reading more messages.

Copy Message

To copy a message, you must initialize the read context and read the message. Then the address to which the message is to be copied (and any features associated with the message, e.g. file attachments) must be validated.

To validate the destination, use the standard validation functions (valadr(), valatt(), and valpri()), but pass the address to which the message is to be copied as the to argument to these functions (see page 204). Note that valrrr() need not be called: you should markread() the message before copying it so that the “return receipt requested” flag will be clear before you copy the message.

Once the message has been validated, the destination fields of the header (forum and to) must be filled in with the same values passed to the validation functions, and the following function called:

int                                /*   returns standard GME status codes  */
copymsg(                           /* send copy of current msg in context  */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure           */
char *text);                       /*   message text                       */

This function requires cycling, like reply(). Unlike reply(), this function does not close the work area when it finishes. However, the msg and text buffers will no longer contain the current message.

The following status codes may be returned by copymsg():

GMEAGAIN Cycle, then call copymsg() again.

GMEOK The message was copied successfully.

GMEAFWD The message was copied and auto-forwarded. The address to which it was forwarded can be gotten from gmexinf().

GMEERR The current message could not be re-read or the destination was not validated properly.

GMECRD The user doesn’t have enough credits to copy the message.

GMENOAT The attachment to the message could not be copied (so the message was not copied either).

GMENCFL The address specified was a distribution list. Messages can not be copied to a distribution list.

Forward Message

Forwarding a message is very similar to copying a message. You first initialize the read context and read the message. Then validate the destination and call the forward-message function. The main difference is that special validation routines are provided for forwarding:

int                                /*   returns VAL code                   */
vfwdadr(                           /* validate address for forwarding      */
void *workb,                       /*   GME work space                     */
char *from,                        /*   User-ID doing the forwarding       */
char *to,                          /*   to address                         */
unsigned forum);                   /*   forum message being written in     */
int                                /*   returns VAL code                   */
vfwdatt(                           /* validate attachment for forwarding   */
void *workb,                       /*   GME work space                     */
char *from,                        /*   User-ID doing the forwarding       */
char *to,                          /*   to address                         */
unsigned forum);                   /*   forum message being written in     */
int                                /*   returns VAL code                   */
vfwdpri(                           /* validate priority message for fwding */
void *workb,                       /*   GME work space                     */
char *from,                        /*   User-ID doing the forwarding       */
char *to,                          /*   to address                         */
unsigned forum);                   /*   forum message being written in     */

These functions return the same codes as the normal validation functions.

Once the destination has been validated, the destination fields of the header (forum and to) must be filled in with the same values passed to the validation functions, and the following function called:

int                                /*   returns standard GME status codes  */
fwdmsg(                            /* forward current message in context   */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure           */
char *text);                       /*   message text                       */

Like copymsg(), this function requires cycling, does not close the work area when finished, the msg and text buffers no longer contain the original message, and the same status codes are returned.

Delete Message

To delete a message, initialize the read context then call:

int                                /*   returns standard GME status codes  */
delmsg(                            /* delete current message in context    */
void *workb);                      /*   GME work space (provided by caller)*/

The message to be deleted need not be read beforehand. This function currently does not require cycling, but it very likely will in the future. It does not close the work area.

The following status codes may be returned:

GMEAGAIN Cycle, then call delmsg() again.

GMEOK The message was successfully deleted.

GMENFND The message specified in the read context was not found.

GMEACC The user does not have access to delete the message.

GMEUSE The message could not be deleted because someone else is using it.

GMENDEL The message cannot be deleted (the NODEL flag is set).

Modify Message

To modify a message, initialize the read context, fill in the new topic (in the message header) and text, then call:

int                                /*   returns standard GME status codes  */
modmsg(                            /* modify current message in context    */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure buffer    */
char *text);                       /*   message body text buffer           */

The message need not be read before modifying. Only the topic and text are modified.

The following status codes may be returned:

GMEAGAIN Cycle, then call modmsg() again.

GMEOK The message was successfully modified.

GMENFND The message specified in the read context was not found.

GMEACC The user does not have access to modify the message.

GMEUSE The message could not be modified because someone else was using it.

GMENMOD The message cannot be modified (the NOMOD flag is set).

This function currently does not require cycling, but it very likely will in the future.

Note: message pointers that are not true copies of another message (see page 199) cannot be modified. The modmsg() function will return GMEOK, but the changes will not take effect.

Approve Attachment

To approve an attachment to a forum message, you must first read the message, then call:

int                                /*   returns standard GME status codes  */
aprvmsg(                           /* approve/unapprove current message    */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure buffer    */
char *text,                        /*   message body text buffer           */
BOOL approve);                     /*   TRUE=approve, FALSE=unapprove      */

The following status codes may be returned:

GMEAGAIN Cycle, then call aprvmsg() again.

GMEOK The message was successfully approved.

GMEERR The message is an e-mail message.

GMEACC The user does not have access to approve attachments.

GMENOAT The message does not have an attachment.

This function currently does not require cycling, but may in the future.

Exempt Message

To exempt a forum message from auto-delete, first read the message, then call:

int                                /*   returns standard GME status codes  */
exmtmsg(                           /* exempt/unexempt current message      */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   message header structure buffer    */
char *text,                        /*   message body text buffer           */
BOOL exempt);                      /*   TRUE=exempt, FALSE=unexempt        */

The following status codes may be returned:

GMEAGAIN Cycle, then call exmtmsg() again.

GMEOK The message was successfully exempted.

GMEERR The message is an e-mail message.

GMEACC The user does not have access to exempt messages.

This function currently does not require cycling, but may in the future.

Thread Information

To get information about the thread a message belongs to, initialize the read context (be sure to initialize the thread ID context either explicitly by using inictx() or by reading a message) then call:

int                                /*   returns standard GME status codes  */
thrinfo(                           /* read info on a thread (orig message) */
void *workb,                       /*   GME work space (provided by caller)*/
int direct,                        /*   direction (0=same, 1=next, -1=prev)*/
unsigned *nmsgs,                   /*   number of messages in thread       */
struct message *msg,               /*   message header structure buffer    */
char *text);                       /*   message body text buffer           */

This function will read the first message in the thread and the number of messages in the thread. The direct parameter allows you to generate lists of threads in a forum. Passing 1 in the direct parameter will return the first message in the next thread in the forum (based on thread ID). Likewise, passing -1 in direct will return the first message in the previous thread.

The following status codes may be returned:

GMEAGAIN Cycle, then call thrinfo() again.

GMEOK Thread information read successfully.

GMENFND The current thread (if direct == 0) or the next or previous thread (for direct == 1 or -1) could not be found.

GMEACC The user does not have access to read messages in this forum.

This function may require cycling.

Forum Information

A wide variety of information about forums is available. You can retrieve this information all at once, or just the bits you are most interested in.

General Information

One of the most basic pieces of information about Forums is:

unsigned
numforums(void);                   /* get number of forums                 */

Most of the information about a forum is stored in the forum definition structure (see page 200). There are three ways to get the definition for a given forum: by forum ID, by name, and by sequence ID.

To determine whether a given forum ID even exists, you can use the following macro:

#define fidxst(fid) (fid != EMLID && fididx(fid) != NOIDX)
#define NOIDX    -1                /* valid index not found return value   */

int                                /*   (returns NOIDX if not found)       */
fididx(                            /* get index of forum ID in def array   */
unsigned fid);                     /*   forum ID                           */

Note: the index returned by fididx() cannot be used directly.

To get the in-memory definition for a forum given the forum ID, you can use one of the following functions:

struct fordef *                    /*   pointer to temporary buffer        */
getdefp(                           /* get pointer to forum definition      */
unsigned forum);                   /*   forum ID of def to get             */
struct fordef *                    /*   pointer to destination buffer      */
getdefb(                           /* copy forum def into a work buffer    */
unsigned forum,                    /*   forum ID of def to get             */
struct fordef *workdef);           /*   pointer to work buffer             */

The function getdefp() will return a pointer to a temporary buffer containing a copy of the forum definition you requested, while getdefb() will copy the definition into a buffer you supply. If you pass an invalid forum ID to either of these functions, NULL will be returned.

Note: for GME information functions that return a pointer, assume that the pointer is to a single, temporary buffer. So if you need to compare the same piece of information from different sources, you must copy the first piece of information into your own buffer before getting the second.

To get forum information in forum ID order, skipping over unused forum IDs, you can use the following functions:

struct fordef *                    /*   pointer to temporary buffer        */
fiddefp(                           /* ptr to forum def in forum ID order   */
unsigned idx);                     /*   index of forum ID                  */
struct fordef *                    /*   pointer to destination buffer      */
fiddefb(                           /* get forum def in forum ID order      */
unsigned idx,                      /*   index of forum ID                  */
struct fordef *workdef);           /*   pointer to work buffer             */

The idx parameter passed to these functions is continuous from 0 to numforums()-1. If you pass an invalid index, these functions will return NULL.

To get forum information in sequence, you can use the following functions:

struct fordef *                    /*   pointer to temporary buffer        */
seqdefp(                           /* get pointer to forum def in sequence */
unsigned seqid);                   /*   sequence ID of forum               */
struct fordef *                    /*   pointer to destination buffer      */
seqdefb(                           /* get forum def into buffer in sequence*/
unsigned seqid,                    /*   sequence ID of forum               */
struct fordef *workdef);           /*   pointer to work buffer             */

These functions are useful for listing forums in their Sysop-defined sequence. Sequence IDs are also continuous, so you can list forums by getting sequence IDs from 0 to numforums()-1. If you pass an invalid sequence ID, these functions will return NULL.

To get forum information in alphabetical order by name, the following suite of functions is provided:

struct fordef *                    /*   pointer to temporary buffer        */
nxtdefp(                           /* get ptr to next forum definition     */
char *name);                       /*   given name to start with           */
struct fordef *                    /*   pointer to destination buffer      */
nxtdefb(                           /* copy next forum def into a work buf  */
char *name,                        /*   given name to start with           */
struct fordef *workdef);           /*   pointer to work buffer             */
struct fordef *                    /*   pointer to temporary buffer        */
prvdefp(                           /* get ptr to prev forum definition     */
char *name);                       /*   given name to start with           */
struct fordef *                    /*   pointer to destination buffer      */
prvdefb(                           /* copy prev forum def into a work buf  */
char *name,                        /*   given name to start with           */
struct fordef *workdef);           /*   pointer to work buffer             */

Say you have forums named Hello, Hola, and Shalom:

prvdefp("Hello") will return NULL because Hello is the first forum.

nxtdefp("Hello") will return the definition for Hola.

nxtdefp("Junk") will return the definition for Shalom because it is the first existing forum name farther down the alphabet than the string "Junk". It is irrelevant that Junk is not the name of an existing forum.

nxtdefp("Shalom") will return NULL because Shalom is the last forum.

If you know the exact name of the forum and just want the definition for that forum, you can call:

unsigned                           /*   returns EMLID if doesn't exist     */
getfid(                            /* get forum ID                         */
char *name);                       /*   given forum name                   */

Then use the return value in a call to getdefp() or getdefb() to get the forum definition.

If you just want to find out if a forum with a given name exists, you can use the following macro:

#define fnmxst(name) (fnmidx(name) != NOIDX)

int                                /*   (returns NOIDX if not found)       */
fnmidx(                            /* get index of named forum in def array*/
char *name);                       /*   forum name                         */

Again, the index returned by fnmidx() cannot be used directly.

To get everything there is to know about a forum, use:

void
getallf(                           /* get all info about a forum           */
unsigned forum,                    /*   forum ID to get                    */
struct fordsk *workdef,            /*   on-disk forum definition format    */
char *desc,                        /*   buffer for description             */
char *echoes);                     /*   buffer for echoes                  */

But if you just want specific pieces of information about a forum, you may be able to use one of the following functions:

char *                             /*   returns NULL if doesn't exist      */
getfnm(                            /* get forum name                       */
unsigned fid);                     /*   given forum ID                     */
char *                             /*   returns NULL if doesn't exist      */
getftpc(                           /* get forum topic                      */
unsigned fid);                     /*   given forum ID                     */
void
getecho(                           /* copy forum's echoes into work buffer */
unsigned forum,                    /*   forum ID to get                    */
char *echoes);                     /*   pointer to work buffer             */
void
getdesc(                           /* copy forum's desc into work buffer   */
unsigned forum,                    /*   forum ID to get                    */
char *desc);                       /*   pointer to work buffer             */
Access Information

An important subset of forum information is user access. This information is stored both in the forum definition (page 200) and in each user’s quickscan record (page 238).

To see if a user is even allowed to know a forum exists, you can use:

BOOL                               /*   TRUE if access > NOAXES            */
faccok(                            /* current user has access to Forum?    */
unsigned forum);                   /*   forum ID to check access for       */

Typically, you will want to know a user’s forum access level. The forum access level determines what operations a user may perform in a given forum.

The following access level codes are currently defined:

                                   /* forum access codes                   */
#define NOAXES 0                   /*   no access                          */
#define RDAXES 2                   /*   read access                        */
#define DLAXES 4                   /*   download access                    */
#define WRAXES 6                   /*   write access                       */
#define ULAXES 8                   /*   upload access                      */
#define COAXES 10                  /*   Co-Op access                       */
#define OPAXES 12                  /*   (ret from foracc() when Forum-Op)  */
#define SYAXES 14                  /*   (ret from foracc() when Sysop)     */
#define NOTSET 15                  /*   not set yet (use default)          */

Access levels correspond to an increasing number of operations that can be performed. A user with a given access level can perform all operations that a user with a lower access level can, plus additional operations.

The various access levels indicate access to the following operations:

NOAXES no access, cannot see forum at all

RDAXES read messages, but not download attachments

DLAXES download attachments, but not write messages

WRAXES write messages, but not upload attachments

ULAXES upload attachments, but they require Forum-Op approval

COAXES uploads “pre-approved”, no Forum-Op approval required

OPAXES approve uploads, maintain messages, set user access

SYAXES create/delete forums, assign Forum-Ops

The last code (NOTSET) is not actually used as an access level code. Instead, it is used by the engine to indicate that the user has default access in the forum. Its use is discussed in more detail on page 238.

There are several functions to get the access level for a given user:

int                                /*   returns standard access level code */
foracc(                            /* get current user's forum access level*/
unsigned fid);                     /*   given forum ID                     */
int                                /*   returns standard access level code */
gforac(                            /* get a user's forum access level      */
char *uid,                         /*   given any User-ID                  */
unsigned fid);                     /*   and forum ID                       */
int                                /*   returns standard access level code */
qforac(                            /* get a user's forum access level      */
struct qscfg *qsc,                 /*   given quickscan                    */
unsigned fid);                     /*   and forum ID                       */

The function foracc() is for the current (online) user; gforac() is for any user, online or offline; and qforac() is for any user, but you must supply a pointer to their quickscan record (e.g., using uqsptr(), see page 241).

When listing access levels, you may find it convenient to use the following function:

char *
accstr(                            /* string describing forum access level */
int acclvl);                       /*   access level to describe           */

It returns a string containing the English name of each access level: "Zero", "Read", "Download", "Write", "Upload", "Co-Op", "Forum-Op", "Sysop", or "<unassigned>" for NOTSET.

Forum Management

Forum management operations are performed by the Forum-Op or Sysop. These operations include creating, editing and deleting forums, and setting user access. Forum management also includes copying, forwarding, modifying, deleting and exempting messages, and approving attachments, but these operations are discussed in the “While Reading Messages” section, above.

Forum Definition Management

To create a forum, you must first fill in all of the fields of an on-disk format forum definition structure. The default values for most of the forum definition fields, as configured by the Sysop, are declared in GME.H:

int forccr,                   /* default forum credit consumption rate     */
    forlif,                   /* default lifetime of a forum message (days)*/
    fmschg,                   /* default credit charge to write forum msg  */
    fmrchg,                   /* default credit charge to read forum msg   */
    fulchg,                   /* default credit charge per file upload     */
    fkuchg,                   /* default per-kbyte charge per file upload  */
    fdlchg,                   /* default credit charge per file download   */
    fkdchg;                   /* default per-kbyte charge per file download*/
char *forprv;                 /* privileged forum usage key                */

To initialize the definition structure with the various default values for access, credit charges, etc., you can use:

int                                /*   returns standard GME status codes  */
inifdef(                           /* initialize forum def w/defaults      */
void *workb,                       /*   GME work space (provided by caller)*/
struct fordsk *newdef);            /*   memory area to initialize          */

This function initializes the access and credit charges to the default values set in the GALME.MSG file, initializes the Forum-Op field to the current user, and the attachment directory to a fixed default value. It then searches through all the forum data files and counts the number of messages in each. It then initializes the data file field to the file with the fewest messages. This default may be replaced by any valid path and filename. In addition, the data file and attachment path need not exist already — the engine will create them if necessary.

Determining the number of messages in each file does not take very long, but there may be many files, so this function may require cycling. In addition to GMEAGAIN, inifdef() will only return GMEOK, or GMEACC if the current user does not have Sysop access to the forums.

Note that inifdef() requires a work area, so the work area must be initialized before calling it; inifdef() will close the work area when it finishes.

Once the definition structure has been initialized, you can allow the user to edit it. Note that the forum name field is left blank by inifdef(). This field must be filled with a unique name before creating the forum. When the user enters a name for the forum, check it for validity using:

BOOL
valfornm(                          /* is this a valid forum name?          */
char *name);                       /*   name to check                      */

This function requires that the forum name be at least one but no more than FORNSZ-1 characters long, and contain no space, @, or ; characters.

The topic, description, and echo fields are also left blank by inifdef() and should be filled in before creating the forum. The forum, seqid, nthrs, nmsgs, nfiles, and nw4app fields will be initialized by the engine when the forum is created.

The topic and description are simple text fields that can be edited as one would edit the topic and text of a message.

The echo fields (necho and the echo address array) are a bit more difficult to manipulate. Thus you may want to use the following functions when adding or deleting addresses in the echo array:

int                                /*   returns new number of echoes       */
addecho(                           /* add an echo to list                  */
char *echoes,                      /*   echo list buffer                   */
char *newadr,                      /*   echo address to add                */
int necho);                        /*   current number of echoes           */
int                                /*   returns new number of echoes       */
delecho(                           /* delete an echo from list             */
char *echoes,                      /*   echo list buffer                   */
int echonum,                       /*   index of echo address to delete    */
int necho);                        /*   current number of echoes           */

These functions do not check for size, so you must make sure the echoes buffer you pass to addecho() is at least (necho+1)*MAXADR bytes long.

Once the definition structure has been filled in, create the forum by calling:

int                                /*   returns standard GME status codes  */
creatfor(                          /* create a new forum                   */
void *workb,                       /*   GME work space (provided by caller)*/
struct fordsk *newdef,             /*   new forum definition structure     */
char *desc,                        /*   descriptive text                   */
char *echoes);                     /*   pointer to array of echo addresses */
                                   /*   (may be NULL if no echoes)         */

This function requires a work area (automatically closed at completion) and cycling. One of these status codes may be returned on completion:

GMEAGAIN Cycle, then call creatfor() again.

GMEOK The forum was successfully created.

GMEERR The current user does not have access to create forums, or the engine could not create either the data file or the attachment directory.

GMEDUP A forum with the specified name already exists.

GMENFND The User-ID specified in the forop field does not exist.

GME2MFR The maximum number of forums that can be supported by the system has been reached.

GME2MFL The data file specified is not currently in use and the maximum number of data files allowed by the “Dynamic Btrieve files” line in GALME.MDF is already in use.

GMENFID There are no available forum IDs — deleted forums must be cleaned up to free up some forum IDs.

GMEMEM There is not enough memory to add another forum.

A couple things to note about creatfor(): no validity checks (other than duplicate names or non-existent Forum-Ops) are done by the engine, thus you must be sure to initialize the definition with valid values; the echoes parameter may be NULL if necho == 0, otherwise, the buffer pointed to by echoes must be at least necho*MAXADR in size; the desc parameter may be any size, but it must not be NULL and it will be truncated if strlen(desc) > MAXFDV-necho*MAXADR.

Once a forum has been created, it can be modified using:

int                                /*   returns standard GME status codes  */
modfor(                            /* modify a forum                       */
void *workb,                       /*   GME work space (provided by caller)*/
struct fordef *newdef,             /*   modified forum description         */
char *desc,                        /*   descriptive text                   */
char *echoes);                     /*   pointer to array of echo addresses */
                                   /*(desc & echoes may be NULL if no chng)*/

This function is similar to creatfor(), but it takes an in-memory forum definition structure rather than an on-disk structure. The work area is automatically closed upon completion. Only the following fields can be modified using this function: name, topic, forop, forlok, dfnpv, dfprv, mxnpv, msglif, chgmsg, chgrdm, chgatt, chgadl, chgupk, chgdpk, ccr, pfnlvl, and necho. Note that the desc and echoes parameters may be NULL if they are to remain unaltered.

The following status codes may be returned by modfor():

GMEAGAIN Cycle, then call modfor() again.

GMEOK The forum was successfully updated.

GMEACC The current user does not have access to modify forums.

GMEUSE The forum is being used by someone and cannot be modified right now.

GMENFND The User-ID specified in the forop field does not exist or the forum ID does not exist.

GMEDUP A forum with the specified name already exists.

GMEERR The number of echoes has been altered, but the echoes parameter is NULL.

GMEFDV The number of echoes has been increased so that there is no longer enough room for both the echo address list and the forum description.

This function currently does not require cycling, but may in the future.

Normally both Sysops and Forum-Ops can use modfor(). However, the Sysop may change the following configuration option (declared in GME.H) so that Forum-Ops no longer have access to edit the whole forum definition:

BOOL fopmfd;                       /* allow forum-ops to modify forum defs?*/

If this is the case, Forum-Ops can still configure the default access parameters for the forum using:

int                                /*   returns standard GME status codes  */
cfgfacc(                           /* configure default access             */
unsigned forum,                    /*   for this forum                     */
struct foracc *acc);               /*   forum access structure             */

This function takes the following structure as its primary parameter:

struct foracc {                    /* forum access info structure          */
     int dfnpv;                    /*   default non-privileged access      */
     int dfprv;                    /*   default privileged access setting  */
     int mxnpv;                    /*   maximum non-privileged access      */
     char forlok[KEYSIZ];          /*   key required for privileged access */
};

The forum definition fields that correspond to the foracc fields are updated by cfgfacc(). Either GMEOK or GMEACC (if the user doesn’t have at least OPAXES in the specified forum) will be returned. No cycling is required.

To delete a forum, the following function is used:

int                                /*   returns standard GME status codes  */
delfor(                            /* delete a forum                       */
void *workb,                       /*   GME work space (provided by caller)*/
unsigned forum);                   /*   forum ID to delete                 */

This functions requires a work area, but no other setup (the work area is automatically closed when delfor() finishes). It currently does not require cycling, but may in the future.

The following status codes may be returned:

GMEAGAIN Cycle, then call delfor() again.

GMEOK The forum has been deleted.

GMEACC The current user does not have access to delete forums.

GMENDEL The forum cannot be deleted because it is the default forum specified by the Sysop in GALME.MSG CNF option DFTFOR.

GMENFND The specified forum does not exist.

GMEUSE The forum is being used by someone and cannot be deleted now.

One thing to note about deleting forums is that the forum definition and messages are not actually deleted when you call this function. The forum definition is removed from memory (so the messages can no longer be accessed either) and marked “deleted” on disk, but the definition record and messages are not actually deleted from disk until the next “deleted forum cleanup” occurs.

User Access Management

Two utilities are provided to manage a user’s forum access levels.

To set a user’s access level in a single forum, you should use:

int                                /*   returns standard GME status codes  */
setaxes(                           /* set access for a user                */
unsigned fid,                      /*   forum to set access for            */
char *uid,                         /*   user to set access for             */
int acc);                          /*   access to set to                   */

This function will handle all the complexity involved in setting a Forum-Op and dealing with online vs. offline users. The following status codes may be returned:

GMEOK User’s access updated successfully.

GMEACC The current user does not have access to set access in the specified forum. This code will also be returned if a Forum-Op tries to give another user Forum-Op access.

GMEMEM The specified forum is not already in the specified user’s quickscan record, and there is not enough room to add another forum.

The acc parameter should be a valid access level, including NOTSET, which will give the user default access in the specified forum.

To set a user’s access in many forums at once, the following function can be used:

int                                /*   returns standard GME status codes  */
cpyaxes(                           /* copy forum access                    */
char *dstusr,                      /*   to this User-ID                    */
char *srcusr);                     /*   from this User-ID                  */

This function copies all of the non-default access levels from the srcusr to the dstusr. It will work regardless of whether or not the user(s) are online or not. The following status codes may be returned:

GMEOK Access levels were copied successfully.

GMEACC The current user does not have access to copy access levels.

GMENSRC The User-ID specified in the srcusr parameter does not have a quickscan record.

GMENDST The User-ID specified in the dstusr parameter does not exist.

If there is not enough room in the destination user’s quickscan record to add all the new forums, no error code is returned, but not all the access levels will be copied.

Generic Functions

Applies to: WG2+

In Worldgroup 1.0x, there were many functions (such as creating or editing forums) that required a current user and/or applied access and credit checks. There are now generic versions of most of these functions, that do not require a current user and do no access or credit checks. In general, these functions take the same input parameters and return the same status codes (with the exception of GMEACC and GMECRD).

The following two functions are equivalent to inifdef():

void
gmeGetForDft(           /* get default forum configuration      */
struct fordsk *newdef,  /*   new forum definition structure     */
const char *forop);     /*   Forum-Op to initialize with        */

Fills in all fields of a struct fordsk buffer except for the data file with the default values.

int                     /*   returns standard GME status codes  */
gmeRecommend(           /* recommend a forum data file          */
void *workb,            /*   GME work space (provided by caller)*/
char *datfil);          /*   data file path+file name buffer    */

Finds the data file that currently contains the fewest messages. Like inifdef(), this function requires a work area and cycling. It closes the work area when done.

The following functions are equivalent to creatfor(), modfor(), and delfor().

int                     /*   returns standard GME status codes  */
gmeGCreateFor(          /* create a new forum (no access check) */
void *workb,            /*   GME work space (provided by caller)*/
struct fordsk *newdef,  /*   new forum definition structure     */
char *desc,             /*   descriptive text                   */
char *echoes);          /*   pointer to array of echo addresses */
                        /*   (may be NULL if no echoes)         */
int                     /*   returns standard GME status codes  */
gmeGModifyFor(          /* modify a forum (no access check)     */
void *workb,            /*   GME work space (provided by caller)*/
struct fordef *newdef,  /*   modified forum description         */
char *desc,             /*   descriptive text                   */
char *echoes);          /*   pointer to array of echo addresses */
                        /*(desc & echoes may be NULL if no chng)*/
int                     /*   returns standard GME status codes  */
gmeGDeleteFor(          /* delete a forum (no access check)     */
void *workb,            /*   GME work space (provided by caller)*/
unsigned forum);        /*   forum ID to delete                 */

The following function is equivalent to frdmsg():

int                     /*   returns standard GME status codes  */
grdmsg(                 /* generic read message in context      */
void *workb,            /*   GME work space (provided by caller)*/
int direct,             /*   read direction code                */
struct message *msg,    /*   message header structure buffer    */
char *text);            /*   message body text buffer           */

The following function is equivalent to thrinfo():

int                     /*   returns standard GME status codes  */
gmeGThreadInfo(         /* read thread info (not user-specific) */
void *workb,            /*   GME work space (provided by caller)*/
int direct,             /*   direction (0=same, 1=next, -1=prev)*/
unsigned *nmsgs,        /*   number of messages in thread       */
struct message *msg,    /*   message header structure buffer    */
char *text);            /*   message body text buffer           */

The following functions are equivalent to delmsg(), modmsg(), aprvmsg() and exmtmsg():

int                     /*   returns standard GME status codes  */
gmeGDeleteMsg(          /* delete current msg (non-user spec)   */
void *workb);           /*   GME work space (provided by caller)*/
int                     /*   returns standard GME status codes  */
gmeGModifyMsg(          /* modify current msg (not user-spec)   */
void *workb,            /*   GME work space (provided by caller)*/
struct message *msg,    /*   message header structure buffer    */
char *text);            /*   message body text buffer           */
int                     /*   returns standard GME status codes  */
gmeGApprove(            /* approve/unapprove msg (not user-spec)*/
void *workb,            /*   GME work space (provided by caller)*/
struct message *msg,    /*   message header structure buffer    */
BOOL approve);          /*   TRUE=approve, FALSE=unapprove      */
int                     /*   returns standard GME status codes  */
gmeGExempt(             /* exempt/unexempt msg (not user-spec)  */
void *workb,            /*   GME work space (provided by caller)*/
struct message *msg,    /*   message header structure buffer    */
BOOL exempt);           /*   TRUE=exempt, FALSE=unexempt        */

The following function is equivalent to the copymsg() and fwdmsg() functions. It has basically the same requirements, but takes one extra parameter: delorig. This is a flag parameter that discriminates between copy (delorig == FALSE) and forward (delorig == TRUE).

int                     /*   returns standard GME status codes  */
gmeGForward(            /* forward a message (not user-specific)*/
void *workb,            /*   GME work space (provided by caller)*/
BOOL delorig,           /*   delete original (forward vs. copy) */
struct message *msg,    /*   message header buffer              */
char *text);            /*   message text buffer                */

Quickscan

The quickscan configuration record (henceforth referred to as the qscfg) is the repository for most per-user information in E-mail and Forums. Its structure is as follows:

#define MAXSKWD  80                /* size of scan keyword string          */

struct qscfg {                     /* quickscan/config per-user data       */
     char userid[UIDSIZ];          /*   master key for lookups             */
     char fwdee[MAXADR];           /*   auto-forwardee for E-mail (if any) */
     unsigned fwdate;              /*   date that forwardee was chosen     */
     char kwds[MAXSKWD];           /*   quickscan keywords                 */
     unsigned curfor;              /*   current forum ID                   */
     int nforums;                  /*   number of forums in quickscan      */
     int flags;                    /*   preference and quickscan flags     */
     long stmsg;                   /*   quickscan starting message ID      */
     char spare[26];               /*   spare space                        */
     char accmsg[1];               /*   start of variable-len accmsg stuff */
};                                 /*   2 arrays: forumID+msgID, acclvl    */
                                   /*   msgID > 0 == "real" quickscan forum*/
User Preferences

One of the many bits of per-user information stored in the qscfg is the user’s personal preferences. These preferences primarily affect the user interface (and the terminal-mode user interface at that), but are stored and maintained by GME. The individual preferences are stored in the flags field of the qscfg as follows:

                                   /* preference-related flag definitions  */
#define CLARPL  0x0001             /*   clear messages after replied to?   */
#define P4NEWM  0x0002             /*   pause at logon for new mail?       */
#define GORTIN  0x0004             /*   if pause, go right into E-mail?    */
#define FORUM2  0x0008             /*   consider forum mail E-mail "to"?   */
#define MSGQUO  0x0010             /*   use message quoting at all?        */
#define ALWQUO  0x0020             /*   always use message message quoting?*/
#define USRSET  0x0040             /*   user has set preferences           */
#define QWKATT  0x0080             /*   include attachments in QWK-Mail?   */
#define CMBHDR  0x0100             /*   combine header and body of messages*/
#define NEWMSG  0x0200             /*   new messages only in quickscan?    */
#define WATONL  0x0400             /*   msgs w/atts only in quickscan?     */
#define TOMEONL 0x0800             /*   msgs to me only in quickscan?      */
#define FRMEONL 0x1000             /*   msgs from me only in quickscan?    */
#define CFWCMT  0x2000             /*   comment when copy/fwding at all?   */
#define ALWCMT  0x4000             /*   always comment when copy/fwding    */

The preferences may be set by directly manipulating a user’s qscfg, but one general rule should be followed: when setting the “always” flag of an “ever/always” pair (e.g., P4NEWM/GORTIN, MSGQUO/ALWQUO, and CFWCMT/ALWCMT), be sure to set the “ever” flag as well.

Auto-Forwardee

The fwdee field of the qscfg specifies an address to which any e-mail addressed to the user will be forwarded. You should use the following function to set the auto-forwardee:

int                                /*   returns VAL code                   */
setafwd(                           /* set auto-forwardee for current user  */
char *newfwde);                    /*   new auto-forwardee                 */

This function sets both the fwdee and fwdate fields of the qscfg. It will return VALYES if the specified forwardee is ok, VALNO if the auto-forward address is too long or is invalid (forum addresses and distribution lists are not considered valid auto-forward addresses), or VALACC if the user doesn’t have access to auto-forward to the specified address. The auto-forwardee can be cleared by passing an empty string as newfwde.

Per-Forum Information

The primary purpose of the qscfg is to record per-forum information for each user. The information stored per forum is the access level, the highest message read in the forum, and whether or not the forum is included in the user’s “quickscan” of forums. This per-forum information is stored in the variable-length accmsg field of the qscfg structure.

The access level is an unsigned integer that governs what actions a user may perform in a forum. The access level codes are discussed in the Forum Information section, page 226. The last three access level codes are of particular interest when discussing the qscfg per-forum information.

First, the NOTSET code is only found in the qscfg record. It indicates that the user’s access has not been explicitly set by the Forum-Op of the forum. Thus the user has the default access for that forum. The OPAXES and SYAXES codes are unique in that they should never be found in the qscfg. Their significance is discussed in greater detail above; for now it is important to note that these two values should never be explicitly put into a user’s qscfg.

The highest message ID serves a dual role. In addition to being a starting point when reading new messages, it is used to indicate whether or not the forum should be included in the user’s quickscan. This is indicated by the sign of the high message ID: if the high message is positive, the forum should be included in the quickscan, if the high message is negative (or zero), the entry is just being used to track the highest message read, and the forum should not be included in the quickscan (this is referred to as a marker entry).

The number of forums is not limited by the size of the qscfg. This is done by not having a slot in the qscfg for every forum on the system. Instead, a forum is only added to the quickscan when the user explicitly adds it to their qscfg, reads messages in the forum, or the Forum-Op sets their access level to a non-default value.

While there is a relatively high limit on the number of forums on a system, there is a lower limit on the number of forums that can be stored in the qscfg record. This limit is defined in GME.H as:

#define MAXNQSF  2400              /* max # forums in a user's quickscan   */

The number of forums is limited by the way the per-forum information is stored in the qscfg. Because not every forum is present in the qscfg, the forum ID must be stored along with the high message ID and the access level, so 2400 is the most forum entries that will fit in a 16K qscfg record.

The 2400 forum limit is the maximum limit set by the software. However, Sysops can configure a lower limit in order to preserve memory. The actual limit is stored in the variable:

int _maxqsf;                       /* use MAXQSF, not this                 */
#define MAXQSF _maxqsf             /* max forums in a user's quickscan     */

Since this number is read from an .MCV file at startup, it may or may not have been initialized at the time your module’s init__ function is called. If you need to perform operations based on this number as part of your initialization, you can use the function:

int                                /*   returns max # forums allowed in qs */
maxqsf(void);                      /* init__ callable get-max-qscan-forums */

This will initialize MAXQSF if it has not already been initialized.

The per-forum information is stored in two parallel arrays, and the number of elements in the arrays is stored in the nforums field. The first array (which starts at accmsg[0]) is an array of structures containing the forum ID and the high message ID (the forum ID is the first field). The second array immediately follows the first. It stores the access level, and is an array of 4-bit integers stored as an array of characters. Thus element 0 is the low order 4 bits of character 0, element 1 is the high order 4 bits of character 0, element 2 is the low order 4 bits of character 1, etc.

The elements in the two arrays must be kept in sync (so that element 0 in the forum ID/high message array corresponds to element 0 in the access level array), and they must be stored in forum ID order.

Due to the complexity of this structure, a large suite of functions is provided to manipulate the per-forum information in a qscfg.

To get a pointer to an online user’s qscfg, use:

struct qscfg *
uqsptr(                            /* get online user's quickscan          */
int unum);                         /*   user number to get                 */
struct qscfg *
myqsptr(void);                     /* get current user's quickscan         */
struct qscfg *                     /*   returns NULL if not found          */
onsqsp(                            /* get online user's quickscan          */
char *uid);                        /*   given User-ID                      */

The last function can also be used to see if a User-IDs qscfg is “online” (has been initialized using inigmeu()). A macro is defined in GME.H for this purpose:

#define qsonsys(uid) (onsqsp(uid) != NULL)

To get the index of a particular forum in the qscfg, use:

int                                /*   index in qs arrays (NOIDX if err)  */
qsidx(                             /* get index of forum in quickscan      */
struct qscfg *qsc,                 /*   quickscan record                   */
unsigned fid);                     /*   forum ID to get                    */

Since this function returns NOIDX if there is no entry for the forum in the qscfg, a macro is available to determine whether a forum is in the qscfg:

#define inqs(qsc,fid) (qsidx((qsc),(fid)) != NOIDX)

To add a forum entry to the qscfg, use:

int                                /*   index in qs arrays (NOIDX if err)  */
add2qs(                            /* add slot for forum to quickscan      */
struct qscfg *qsc,                 /*   quickscan record                   */
unsigned fid);                     /*   forum ID to add                    */

This function adds a slot for the specified forum (with the high message set to 0 and the access level set to NOTSET) and returns the index at which it added it. If the forum was already in the qscfg, it just returns the index. If there is not enough room to add another forum, it returns NOIDX.

A somewhat more useful function is:

int                                /*   index of new entry (NOIDX if error)*/
absadqs(                           /* add forum to qs, del others for room */
struct qscfg *qsc,                 /*   quickscan record                   */
unsigned fid);                     /*   forum ID to add                    */

This function acts just like add2qs(), but if there is no room to add another entry, it will try to make room. First, it will try to find a deleted forum to remove from the qscfg. If there are no deleted forums to remove, it will search for marker entries for which the access level has not been explicitly set, and will delete the oldest one (the one for which the absolute value of the high message is lowest). Only if neither of these can be found will it return NOIDX.

An even more useful function, for use when configuring a user’s quickscan, is:

BOOL                               /*   returns FALSE if unable to add     */
sfinqs(                            /* set forum in quickscan               */
struct qscfg *qsc,                 /*   quickscan record                   */
unsigned fid,                      /*   forum to set                       */
BOOL turnon);                      /*   TRUE = make forum "in" quickscan   */

This function will switch forums in and out of the quickscan by adding an entry with a high message ID of 1 if necessary, or changing the sign of the high message if the forum is already present. It will only return FALSE if it cannot absadqs() the specified forum.

The indices returned by qsidx(), add2qs(), and absadqs() can be used to manipulate the qscfg using the following functions:

void
idelqs(                            /* delete an entry from the quickscan   */
struct qscfg *qsc,                 /*   pointer to quickscan               */
int idx);                          /*   index of entry to delete           */
void
isethi(                            /* set hi message in quickscan (w/index)*/
struct qscfg *qsc,                 /*   pointer to quickscan               */
int idx,                           /*   index of forum to set              */
long msgid);                       /*   message ID to set as high message  */
void
isetac(                            /* set forum acc in quickscan (w/index) */
struct qscfg *qsc,                 /*   pointer to quickscan               */
int idx,                           /*   index of forum to set              */
int acc);                          /*   access level to set                */
unsigned
igetfid(                           /* get forum ID in quickscan (w/index)  */
struct qscfg *qsc,                 /*   pointer to quickscan               */
int idx);                          /*   index of forum to get              */
long
igethi(                            /* get hi message in quickscan (w/index)*/
struct qscfg *qsc,                 /*   pointer to quickscan               */
int idx);                          /*   index of forum to get              */
int
igetac(                            /* get forum acc in quickscan (w/index) */
struct qscfg *qsc,                 /*   pointer to quickscan               */
int idx);                          /*   index of forum to get              */

In general, igetac() and isetac() should not be used to manipulate a user’s access level. Instead, use foracc() or gforac() or qforac(), and then setaxes() (see pages 231 and 237).

To read or manipulate a forum’s qscfg entry without first getting an index, the following functions are available:

void
delqs(                             /* delete an entry from the quickscan   */
struct qscfg *qsc,                 /*   pointer to quickscan               */
unsigned forum);                   /*   forum ID to remove from quickscan  */
BOOL                               /*   returns TRUE if able to set        */
sethi(                             /* set hi message in quickscan          */
struct qscfg *qsc,                 /*   pointer to quickscan               */
unsigned forum,                    /*   forum ID to set for                */
long msgid);                       /*   message ID to set as high message  */
BOOL                               /*   returns TRUE if able to set        */
setac(                             /* set forum acc in quickscan           */
struct qscfg *qsc,                 /*   pointer to quickscan               */
unsigned forum,                    /*   forum ID to set for                */
int acc);                          /*   access level to set                */
long
gethi(                             /* get hi message in quickscan          */
struct qscfg *qsc,                 /*   pointer to quickscan               */
unsigned forum);                   /*   forum ID to get for                */

Again, setac() generally should not be used.

Quickscan Configuration

Finally, the use for the qscfg from which its name is derived is to quickly scan forum messages. This lets a user read messages in multiple forums without manually selecting each forum. The quickscan is traditionally used to read new messages in forums of interest. Our implementation also allows the user to take advantage of the full power of the One-Time Search service (page 245). In addition to the per-forum information, which specifies what forums are included in the quickscan, the following qscfg fields are used to save the user’s quickscan: kwds, stmsg, and the NEWMSG, WATONL, TOMEONL and FRMEONL flags.

The quickscan as stored in the qscfg cannot be used directly to read messages. To read messages using the quickscan, you must first use the function:

struct otscan *                    /*   returns copy of pointer to dest    */
qsc2ots(                           /* copy quickscan to a one-time scan buf*/
struct qscfg *qsc,                 /*   quickscan to copy                  */
struct otscan *ots);               /*   one-time scan buffer               */

to copy the information in the qscfg into a buffer with the proper format to be used by the one-time search facility discussed in the One-Time Search section (described immediately below).

Note: This function puts forums into the scan buffer in sequence-ID order, not alphabetical order (the two do not necessarily correspond). However, C/S-mode users require that the forums be in alphabetical order, so if this function is used for C/S-mode users, the forums must be re-sorted into alphabetical order.

One-Time Search

To search for messages in multiple forums, using keywords and other criteria, a one-time search (a.k.a. one-time scan) system is provided. To perform a search, first set up a buffer containing the search criteria to be used. Then initialize a work area, associate the search criteria buffer with the work area, and initialize the read context of the work area with the FSQSCN sequence. That work area can then be used to read messages selected by the search criteria.

The search criteria are stored in the following structure:

struct otscan {                    /* one-time scan setup structure        */
     char keywds[MAXSKWD];         /*   keywords                           */
     long stmsgid;                 /*   starting message ID (0 for none)   */
     char flags;                   /*   search flags                       */
     int nforums;                  /*   number of forums in list           */
     unsigned forlst[1];           /*   list of forums to scan             */
};
                                   /* one-time scan flags                  */
#define SCNEW  0x01                /*   include "new" messages only        */
#define SCATT  0x02                /*   include msgs w/attachments only    */
#define SCTOU  0x04                /*   include msgs to user only          */
#define SCFRU  0x08                /*   include msgs from user only        */
#define SCALL  0x10                /*   include all Forums in Forum list  */

The forlst field is an array of forum IDs, and nforums is the number of forums in this array. The order in which the forums are listed does not matter to the engine, but it is the order in which the forums will be searched. So the forums should be put in forum sequence ID order for terminal-mode users and in alphabetical order for C/S-mode users.

If the SCALL flag is set, all forums except those in forlst will be searched. In this case, the forums are always searched in alphabetical order.

To associate a search buffer with a work area, initialize the work area, then call:

void
setscan(                           /* set the scan context                 */
void *workb,                       /*   for this work space                */
struct otscan *newscn);            /*   to this scan buffer                */

To get a pointer to the search buffer associated with a work area, use:

struct otscan *
getscan(                           /* get the current scan context buffer  */
void *workb);                      /*   for this work space                */

This will return NULL if no search buffer is associated with the work area.

Configuring the one-time search setup is fairly straightforward. However, a few functions are provided to perform the more complex tasks.

To get the index of a forum in a search setup, you can use:

int                                /*   returns NOIDX if not found         */
scnfidx(                           /* get index of forum in search list    */
struct otscan *ots,                /*   in this scan                       */
unsigned forum);                   /*   forum ID to find                   */

To keep the search forums in forum sequence ID order when configuring searches for terminal-mode users, you can use:

void
addf2ots(                          /* add forum to scan list in seq order  */
struct otscan *ots,                /*   one-time scan structure to update  */
unsigned forum);                   /*   forum to add                       */

Since the number of forums that can be put in a one-time search setup is not fixed by the engine, this function does no limit checking — you must be sure not to add more forums than will fit in your buffer.

When initializing the read context for a search, the following two functions can be used to start with the first message in the first forum in the search (as determined by the stmsgid field and the SCNEW flag):

unsigned                           /*   returns EMLID if no forums         */
fstscnf(                           /* get first forum ID                   */
char *userid,                      /*   User-ID doing scan                 */
struct otscan *ots);               /*   in this search                     */
long
fstscnm(                           /* get first message ID                 */
char *userid,                      /*   User-ID doing scan                 */
struct otscan *ots,                /*   in this scan                       */
unsigned forum);                   /*   in this forum (in scan)            */

While reading messages using a one-time search, the engine may search through many messages and forums before finding a match (i.e., while cycling nextmsg() or prevmsg()). To keep the caller appraised of its activities, the engine will generate two callback events: EVTNEWF and EVTNEWM. They are generated when the engine starts to process a new forum and a new message, respectively. During an EVTNEWF event, gmexinf() returns the name of the new forum. During an EVTNEWM event, no extended information is provided. See page 191 for details on using callbacks.

It is important to note that the function nearmsg() does not support one-time searches. If you call nearmsg() with FSQSCN as the read context sequence, it will return GMEERR.

Distribution Lists

Distribution lists are an easy way to send the same message to a large group of people without having to type their addresses in every time you want to send a message to that group. Any type of address can be put in a list except for another list. A distribution list name has a unique format that distinguishes it from other types of addresses. It is either a ! or @ character followed by up to eight letters or numbers. Three types of distribution lists are supported by GME: mass mailing lists, personal lists, and Sysop-defined lists.

The mass mailing list is called !MASS. If a user writes a message to !MASS, a copy of the message will be sent to every User-ID on the system. This list is not configurable and there are no special functions or variables for dealing with it.

Personal Lists

Every User-ID on a system has a personal distribution list that can contain up to 40 addresses. When a user addresses a message to !QUICK, a copy of the message is sent to every address in their personal list.

These personal lists are stored in a Btrieve data file in the following structure:

#define MAXQIK 40                  /* max entries in a !QUICK list         */

struct qikdat {                    /* !QUICK list records structure        */
     char userid[UIDSIZ];          /*   key value for look-up              */
     int  idx[MAXQIK];             /*   array of entry indexes             */
     char list[1];                 /*   variable-length entry data         */
};

Since exported addresses, which can be up to 256 characters (MAXADR) in length, are allowed in distribution lists, and MAXQIK*MAXADR would make for a rather large structure, the addresses in the !QUICK list are stored in a compressed format rather than an array of fixed-length strings.

The list field of the qikdat structure is where the addresses are actually stored. They are appended to one another so that the terminating nul character of one address is immediately followed by the first character of the next one. The idx field of the qikdat structure is used to locate the individual addresses within the list field.

Important: the order of entries in the idx array does not necessarily correspond to their order in the list field, and entries in the idx array are not necessarily continuous. If an idx array entry contains NOIDX, there is no address associated with that slot.

Due to the complexity of this structure, a suite of functions is provided to manipulate the !QUICK list structure.

To read a user’s !QUICK list into a buffer you supply, use:

struct qikdat *                    /*   copy of pointer to buffer          */
getqik(                            /* get a !QUICK list from disk          */
struct qikdat *qikbuf,             /*   pointer to !QUICK buffer           */
char *userid);                     /*   user ID to use                     */

To create a new, empty list for a specified user, you can use:

struct qikdat *                    /*   copy of pointer to buffer          */
iniqik(                            /* initialize !QUICK record for cur user*/
struct qikdat *qikbuf,             /*   pointer to !QUICK buffer           */
char *userid);                     /*   user ID to use                     */

To insert an address into a !QUICK list at a given idx slot, you can use:

void
insqik(                            /* insert entry into !QUICK buffer      */
int pos,                           /*   position to insert at              */
char *entry,                       /*   new entry for position             */
struct qikdat *qikbuf);            /*   pointer to !QUICK buffer           */

If there was an address in that slot already, it will be replaced by the new address.

To delete an address from a !QUICK list, you can use:

void
delqik(                            /* delete an entry from !QUICK buffer   */
int pos,                           /*   position to delete                 */
struct qikdat *qikbuf);            /*   pointer to !QUICK buffer           */

When you are finished editing a !QUICK list, you can save it using:

void
savqik(                            /* save a !QUICK list to disk           */
struct qikdat *qikbuf);            /*   pointer to !QUICK buffer           */
Sysop Lists

Sysop-defined distribution lists have names beginning with an @ character. They are configurable (unlike !MASS) and available to the public (unlike individual !QUICK lists). Each list has its own key required for use and its own surcharge for use. Sysop lists are stored in text files with a filename of the list name (less the preceding @) and the extension .DIS, in the directory specified in the GALME.MSG CNF option DLSTPTH.

A suite of functions is provided to list, create, and edit Sysop lists.

To get information on a specific list, use the function:

int                                /*   returns standard GME status codes  */
getslst(                           /* get info on Sysop dist list          */
char *lstnam,                      /*   list name                          */
char *lstkey,                      /*   buffer for list key                */
int *surchg);                      /*   buffer for list surcharge          */

This function looks for a list with the name specified in the lstnam parameter and puts the basic information about that list (key required for use and surcharge) in the lstkey and surchg buffers. It returns GMEOK if it found the requested list, and GMENFND if not.

To get a list of available Sysop lists, you can use:

int                                /*   returns standard GME status codes  */
nxtslst(                           /* get name of next Sysop dist list     */
char *lstnam,                      /*   buffer for list name               */
char *lstkey,                      /*   buffer for list key                */
int *surchg);                      /*   buffer for list surcharge          */

This function finds the next list (in alphabetical order by name) after the name specified in the lstnam parameter, and returns the information about it (including the name of the list it found) in the lstnam, lstkey, and surchg buffers. It returns GMEOK if it found another list, and GMENFND if not. Note that this function does not check the current user’s access, so you should check lstkey when displaying lists of Sysop lists and not display a list if the user doesn’t have the key required to use the list.

Sysop list names may be up to 9 characters long and are composed of an @ followed by up to eight alpha-numeric characters. The maximum list name length is declared as:

#define DLNMSZ   10                /* Sysop dist list name size            */

Before creating a new Sysop list, you may want to call:

BOOL
valslnm(                           /* is this a valid Sysop dist list name?*/
char *name);                       /*   complete name (including @)        */

to see if the proposed name is a valid list name, and call:

BOOL
dlstxst(                           /* does dist list exist?                */
char *name);                       /*   complete list name (incl @ or !)   */

to see if the list already exists.

To create a Sysop list, you should use the function:

int                                /*   returns standard GME status codes  */
newslst(                           /* create a new Sysop distribution list */
void *workb,                       /*   GME work space                     */
char *lstnam,                      /*   name for new list                  */
char *lstkey,                      /*   key required to use list           */
int surchg);                       /*   surcharge to use list              */

This function will create an empty Sysop list with the specified name, key, and surcharge, and add the list to the list of known Sysop lists maintained by GME. The following status codes may be returned:

GMEOK The list has been created successfully.

GMEACC The current user does not have access to create Sysop lists. A user must have the key specified in the GALME.MSG CNF option EDSTKY and declared in GME.H as edstky in order to create or edit Sysop lists.

GMEERR The list name specified is invalid.

GMEDUP A list with the same name already exists.

GMEUSE The engine encountered a file sharing conflict when trying to open the list file.

GMEMEM There is not enough memory to add the new list to the in-memory list of Sysop lists kept by GME.

Note that newslst() requires a work area. This work area is automatically closed if an error occurs, but if newslst() returns GMEOK, the work area is left open so that it can then be used to add addresses to the new list.

To edit an existing list, you must first open it using:

int                                /*   returns standard GME status codes  */
edtslst(                           /* open a Sysop dist list for editing   */
void *workb,                       /*   work area to initialize            */
char *lstnam);                     /*   name of list                       */

This function opens the specified list file so that new addresses can be added. The following status codes may be returned:

GMEOK The list file was successfully opened.

GMEACC The current user does not have access to edit Sysop lists.

GMEERR Either the list name or the list file is invalid.

GMENFND No such Sysop list exists.

GMEUSE Someone else is currently editing the specified list.

Like newslst(), edtslst() automatically closes the work area if there is an error, but leaves it open if it successfully opens the list file.

To add addresses to a Sysop list, use:

int                                /*   returns standard GME status codes  */
addslst(                           /* add an address to a Sysop list       */
void *workb,                       /*   GME work space                     */
char *addr);                       /*   address to add to list             */

This function appends the specified address to the list. Note that the work area passed to this function must have been used to open the list file using newslst() or edtslst(). If the work area and list file were not opened correctly, addslst() will return GMEERR, otherwise it will return GMEOK.

To list the addresses in a Sysop list while editing, first call:

int                                /*   returns standard GME status codes  */
rstlstp(                           /* set Sysop list pointer to top of list*/
void *workb);                      /*   GME work space                     */

This will set the file pointer to the first address in the list. Then call:

BOOL
nxtsys(                            /* get next entry in Sysop list         */
void *workb,                       /*   work area to use                   */
char *addr);                       /*   buffer for address                 */

to get each successive address in the list into the addr buffer. This buffer must be at least MAXADR in size to accommodate the largest possible address. This function returns FALSE when there are no more addresses (and it doesn’t put anything into addr when it returns FALSE).

When you are through editing a list, just close the work area. This will close the list file and free up any other associated resources.

To delete a Sysop list, you can use:

int                                /*   returns standard GME status codes  */
delslst(                           /* delete a Sysop dist list             */
char *lstnam);                     /*   name of list                       */

This will delete the list file and remove it from the GME-internal list of Sysop lists. The following status codes may be returned:

GMEOK The list was successfully deleted

GMEACC The current user does not have access to edit Sysop lists.

GMEERR The specified list name is invalid.

GMENFND The specified list does not exist.

Finally, if you need to get the actual list file for some reason (e.g., so a user can download the file), you can use:

int                                /*   returns standard GME status codes  */
slstfil(                           /* get info about Sysop list            */
char *lstnam,                      /*   list name                          */
char *lstpath);                    /*   buffer for list path & filename    */

This function puts the path and filename that correspond to the specified list in the lstpath buffer (this buffer must be at least MAXPATH in length). The following status codes may be returned:

GMEOK Found the requested list file, the path and filename are in lstpath.

GMEACC The current user does not have access to edit Sysop lists.

GMENFND The specified list does not exist.

New Distribution List File

Applies to: WG2+

It is now possible to modify a sysop-defined distribution list by supplying an entirely new list file. It is not possible to simply copy in a new file since they are read at startup and the access and credit information is stored in memory.

After constructing a properly formatted list file, first copy or upload the file into the location (path and file name) given by the following function:

char * /* returns pointer to temporary buffer*/
udlnam(void); /* path & file name to upload new list */

Once the upload/copy operation is complete, call the following function to actually replace the old file:

int /* returns standard GME status codes */
setslst( /* import file to replace existing list */
char *lstnam, /* name for new list */
char *lstfil); /* file containing new list */

The lstnam argument is the name of the list being replaced (including preceding @), and the lstfil argument is the path and filename of the new list file (should be the return value from udlnam()).

Importers and Exporters

Messages addressed to (and sent by) users who are signed up on the local system are addressed by User-ID. The messaging engine exchanges messages with other mail systems using importers and exporters. These are special modules responsible for converting messages between the Major BBS's format and other mail systems' formats. Messages are transferred between importers/exporters and the engine through a standard interface.

Exporters

Messages sent from the local system to a remote system are handled by exporters. Each exporter is identified by a unique address prefix — two or three alphanumeric characters (e.g., IN, MHS) that indicate which exporter should be used to send a given message.

When a message is to be sent using an exporter, the address consists of the exporter prefix, followed immediately by a colon, followed by the rest of the address.

Exporters identify themselves to the engine using an exporter control block. In order to be recognized by the engine, an exporter must fill in an exporter control structure, and pass a pointer to it to the GME function:

void
register_exp(                      /* register an exporter                 */
struct exporter *exp);             /*   pointer to exporter control block  */

The engine checks for any conflicts with the prefixes of the already registered exporters (and catastro()s if there is a conflict), then adds the pointer to the list of registered exporters.

Outside processes can determine how many exporters have been registered by calling:

int
numexp(void);                      /* get number of registered exporters   */

To see if there are any exporters available to the current user, you can use:

BOOL
expavl(void);                      /* are any exporters available?         */

This function not only checks to see if any exporters have been registered, but also checks to see if the current user has access to use any of them.

The format of the exporter control block is as follows:

#define PFXSIZ 4                   /* max exporter prefix size             */
#define EXPNSZ 16                  /* max exporter name size               */
#define EXPDSZ 51                  /* max exporter description size        */

struct exporter {                  /* message exporter control block       */
     char prefix[PFXSIZ];          /*   address prefix for this exporter   */
     char name[EXPNSZ];            /*   name of exporter (e.g., "Internet")*/
     char desc[EXPDSZ];            /*   description of exporter            */
     char exmp[MAXADR];            /*   example address to this exporter   */
     char wrtkey[KEYSIZ];          /*   key required to use this exporter  */
     int wrtchg;                   /*   per-message surcharge              */
     char attkey[KEYSIZ];          /*   key required for file attachments  */
     int attchg;                   /*   attachment surcharge               */
     int apkchg;                   /*   attachment per-kbyte surcharge     */
     char rrrkey[KEYSIZ];          /*   key required to request return recp*/
     int rrrchg;                   /*   return receipt request surcharge   */
     char prikey[KEYSIZ];          /*   key required to send priority msg  */
     int prichg;                   /*   priority surcharge                 */
     int flags;                    /*   supported features flags           */
     char *(*helpmsg)(void);       /*   get help message for this exporter */
     BOOL (*valadr)(char *adr);    /*   is this a valid address vector     */
     char *(*attspc)(char *to,struct message *msg);
                                   /* path+filename for attachment vector  */
     int (*sndmsg)(char *to,struct message *msg,char *text,char *att);
};                                 /*   send message vector                */

This structure gives basic information about the exporter (prefix, name, description, example address), the access restrictions and credit charges that apply to the exporter, message features supported by the exporter (e.g., attachments, return receipts), and functions to be used when sending a message using the exporter.

The prefix field is the unique prefix used to identify the exporter (without the colon). Examples of exporter prefixes are MHS for the MHS exporter and IN or US for MG/I.

The name field is the short name by which the exporter (or the mail system to which the exporter interfaces) is known. Examples of exporter names are Novell MHS for the MHS exporter and Internet for MG/I.

The desc field is used to provide a longer description of the exporter. The name and description are typically used by the user interface in lists of exporters or help messages that refer to exporters.

The exmp field would also be found in help messages. This field should give an example of a typical address that would be handled by this exporter (including the prefix). The example address used by MG/I is IN:stryker@gcomm.com.

All of this information (and the keys and credit charges discussed below) can be accessed by outside processes using the following function:

struct expinfo *                   /*   returns pointer to static buffer   */
expinf(                            /* get info on an exporter              */
int idx);                          /*   given exporter index               */

This function returns a pointer to a temporary buffer with the following format:

struct expinfo {                   /* info about exporter for interface    */
     char prefix[PFXSIZ];          /*   address prefix for this exporter   */
     char name[EXPNSZ];            /*   name of exporter (e.g., "Internet")*/
     char desc[EXPDSZ];            /*   description of exporter            */
     char exmp[MAXADR];            /*   example address to this exporter   */
     char wrtkey[KEYSIZ];          /*   key required to use this exporter  */
     int wrtchg;                   /*   per-message surcharge              */
     char attkey[KEYSIZ];          /*   key required for file attachments  */
     int attchg;                   /*   attachment surcharge               */
     int apkchg;                   /*   attachment per-kbyte surcharge     */
     char rrrkey[KEYSIZ];          /*   key required to request return recp*/
     int rrrchg;                   /*   return receipt request surcharge   */
     char prikey[KEYSIZ];          /*   key required to send priority msg  */
     int prichg;                   /*   priority surcharge                 */
     int flags;                    /*   supported features flags           */
};

Note that this structure contains all the information about the exporter except for the function vectors.

The exporter index parameter (idx) to expinf() is the index of the desired exporter in the internal array of registered exporters. This can be gotten for a specific exporter by using the following function:

int                                /*   returns NOIDX if not found         */
expidx(                            /* index of exporter in handler array   */
char *to);                         /*   address containing prefix          */

Note that the to parameter to expidx() can be any string or address that begins with the desired exporter’s prefix (including the colon). If no exporters have been registered with the specified prefix, expidx() returns NOIDX.

One other thing to note about expinf() is that the list of exporters is stored in alphabetical order by prefix, so you can generate a list of exporters, in alphabetical order by prefix, by calling expinf() with indexes 0 through numexp()-1.

The helpmsg function vector is also used for help messages. It should return a pointer to a string that gives even more extensive information about the exporter. Outside processes can access this vector through the following GME function call:

char *                             /*   ptr to temp area (may be msgbuf)   */
exphlp(                            /* get help message for an exporter     */
int idx);                          /*   given exporter index               */

The pointer returned by the helpmsg vector (and thus by exphlp()) may point to vdatmp, prfbuf, or msgbuf — any general-purpose text buffer is acceptable (though not required) — so processes that use this function need to be aware of this possibility.

Which message features can be handled by the exporter are specified by the flags field. The following feature flags are currently defined:

                                   /* exporter flags                       */
#define EXPATT   0x0001            /*   support attachments?               */
#define EXPRRR   0x0002            /*   support return receipts?           */
#define EXPPRI   0x0004            /*   support priority msgs?             */

Thus an exporter that can handle attachments and return receipts, but not priority messages, would set flags=(EXPATT¦EXPRRR). These flags are used to limit the choices presented to a user when he writes a message to this exporter. In this case, the user might be given the option to attach a file or request a return receipt with his message, but would not be given the option to send a priority message.

A set of keys specified by the exporter control block are also used to determine what features a user may use when sending a message using the exporter.

The primary key is wrtkey. A user must have this key in order to send a message using the exporter (or even know the exporter exists).

The attkey, rrrkey, and prikey fields specify keys required to use each of the corresponding features (if the exporter supports that feature). Thus, a user who does not have the attkey for an exporter will not be given the option to attach a file to a message to be sent using that exporter.

The credit charge fields can be used to place a premium on the use of an exporter. These charges are surcharges, that is, they are added to regular message writing charges to compute the total charge to send a message.

For example, it normally costs 95 credits to send a plain e-mail message (no attachments, return receipts, etc.) to another user on the local system (using his User-ID as his to address). If an exporter specifies wrtchg=100, it will cost a total of 195 credits to send a plain e-mail message to an e-mail address on the remote system reached through that exporter.

The last three function vectors are used by the engine to perform various tasks when sending a message to the exporter.

*While it’s possible for a Major BBS server to verify the existence of a local address since that’s one and the same as a local User-ID, it is usually not possible to verify the existence of a remote address. There is no master User-ID list for the Internet, for example. The best that can be done is to verify the format of the address.

The first vector, valadr, is used to validate addresses. When a user enters an address to send an e-mail message to, the engine checks to see if it is a forum, a distribution list, or an existing User-ID. If it is none of these, it checks the address for an exporter prefix. If a valid prefix is specified, the engine passes the address less the prefix to the specified exporter’s valadr vector. This vector should examine the address and return TRUE if the address is in the correct format for the mail system accessed by the exporter. The valadr vector does not need to try to determine whether the address actually exists or not.*

If a valid prefix is not specified, or the valadr vector for the specified exporter returned FALSE and the Sysop has set the GALME.MSG CNF option STRXCHK to NO, all of the exporters to which the user has access are polled (the address less prefix is passed to each valadr vector).

If none of the exporters accept the address, it is rejected as invalid. If only one of the exporters accepts the address, the engine assumes the message should be sent using that exporter, and the prefix for that exporter is prepended to the address. If more than one of the exporters accepts the address, it is rejected as ambiguous. To increase the accuracy of this exporter auto-sensing, and to prevent misdirected mail as much as possible, an exporter’s valadr vector should be very critical of addresses passed to it and return FALSE whenever possible.

The valadr vector is used while the user is composing their message packet. The next two vectors are used as the message is being sent.

If the user has attached a file to the message, the engine calls the destination exporter’s attspc vector. The parameters passed to this vector are the address to which the message is to be sent (including the exporter prefix) and the completed message header structure (including the message ID, thread ID, etc.). The attspc vector must return a valid path and filename. The engine stores this string, then copies the attachment to this path and filename. After copying the attachment to the specified destination, the engine submits the rest of the message packet to the exporter.

The attspc vector must return a unique path and filename so that the new attachment will not overwrite any existing files, and the exporter must not process the attachment before it receives the associated message.

Two GME functions are provided to assist the attspc vector in providing a unique attachment name:

char *                             /*   returns pointer to filename        */
tmpanam(                           /* create temp attachment filename      */
char *dest);                       /*   buffer for name (NULL for internal)*/

This function will generate up to 4 billion unique filenames, using either an externally-supplied buffer (which must be at least FLNMSZ in length) or a static internal buffer (selected by passing NULL for the dest parameter).

If you need to determine whether a given filename was generated using tmpanam(), you can call the following function:

BOOL
istmp(                             /* is this a temporary attachment file? */
char *fname);                      /*   path+filename to check             */

It will work whether the fname parameter is just a filename or a path\filename combination.

The message is actually submitted to the exporter using the sndmsg vector. The parameters passed to this vector are the address to which the message is to be sent (without the prefix), the completed message header structure, the message body text, and the attachment path and filename (if any).

There are several important things to note about the sndmsg vector. First, the to parameter should be used as the destination address, not the to field of the message header (the to field of the message header is generally only significant for echoed forum messages).

There are no provisions for cycling this vector, so it should do whatever processing it needs to do expeditiously. The att parameter used is an exact copy of what the attspc vector returned to the engine. Finally, the sndmsg vector should return one of the standard GME status codes to indicate the result of the operation. At a minimum, GMEOK should be used to indicate success and GMEERR to indicate failure.

Formatted Text, Application-Defined Information and Exporters

Applies to: WG2+

To maintain backward compatibility with existing exporters, messages with formatted body text will be automatically converted to plain ASCII text before being submitted to the exporter’s sndmsg vector unless the exporter explicitly indicates to the GME that it can handle formatted text. To indicate this capability, simply set the following flag in the exporter flags field:

#define EXPFMT 0x0008 /* support formatted text? */

If this flag is set, the exporter will receive unaltered message body text and will be responsible for any necessary conversion.

Any application-defined information associated with a message is also available to exporters, whether the message is new or is being forwarded. Exporters can use gmeGetAppInfo() within their sndmsg() vectors to retrieve the information.

Auto-forwarding and Exporters

Applies to: WG2+

A couple of minor changes have been made to improve the exporter interface when messages are auto-forwarded.

First, it is now possible for the exporter to determine the User-ID to which an auto-forwarded message was originally addressed. This information is gotten by calling gmexinf() within the sndmsg() vector. If the message was auto-forwarded, it will return the User-ID to whom the message was originally written, and an empty string ("") if the message was not auto-forwarded.

Before, when a message was imported, then auto-forwarded back out to an exporter, the prefix on the from address was stripped off. This did not occur, however, when the message was manually forwarded to an exporter. Now, whenever a message with an exported from address is sent through an exporter, it will always have the prefix on the from address. This gives exporters all the information they need to route any replies to the message back through the Major BBS system, to the original sender.

Importers

An importer is simpler from the engine’s point of view, but a bit more complex to implement than an exporter.

There is one function used to import messages into GME:

int                                /*   returns standard GME status codes  */
impmsg(                            /* import a message                     */
void *workb,                       /*   GME work space (provided by caller)*/
struct message *msg,               /*   new message structure              */
char *text,                        /*   message body text                  */
char *filatt);                     /*   path+filename of att (if any)      */

This function is very similar in use to gsndmsg() – the caller must initialize a work area, form a message packet, then cycle the function until it returns a “done” status code. Like gsndmsg(), it closes the work area when finished.

The primary source of complexity when using impmsg() is forming the message packet. First, the importer must convert the to addresses of messages it receives to valid local addresses (User-IDs or forum names, but importing to a distribution list is not supported). E-mail addresses must be converted to existing User-IDs (and the User-ID put in the to field of the message header).

Messages being imported into forums must be given valid forum IDs, and the message to field must be filled in with the address of the user to whom the message is directed (it need not be a local User-ID) or ** ALL **. A constant defined in GME.H can be used for this “all users in forum” string:

#define ALLINF    "** ALL **"      /* "to all in forum" string             */

Since most importers will be associated with an exporter (and the engine has no way of knowing about this association), the importer should format the from field of the message header so that a reply to the message will go to the appropriate exporter. This formatting must include prepending the appropriate prefix to the address, and formatting the address so that it will be recognized by the exporter’s valadr vector.

Like gsndmsg(), it is up to the importer to correctly set all necessary message header flags. Be sure to set FILAPV when importing an e-mail message with file attachment.

In addition to the required header fields (forum, from, to, topic, flags) the importer has the option to explicitly set several other fields or let impmsg() do it:

If the crdate and crtime fields are not both zero, their contents are used as the message creation date and time. Otherwise they are set to the date and time that the message is imported. If your mail handler can transmit the global IDs of the messages it carries, you should set the gmid field of the message header to this global ID. If the gmid field is all zeros, impmsg() will give the message a new global ID based on the current system and message IDs. If your mail handler transmits thread IDs, set the thrid field of the message header. If the thrid field is zero, it will be set to a thread ID based on the topic of the message. Even more important than the thread ID is the reply-to ID. If your mail handler can transmit reply-to IDs, set the rplto field of the message header to the global reply-to ID. If this field is not zeros, impmsg() will try to find a message with the global ID specified in the rplto field of the message being imported. If this original message is found, impmsg() will set the thread ID of the new message to the thread ID of the original message (and add "Reply to #..." to the history field). This is how global threading is achieved (see page 196 for a detailed discussion of global threading). Finally, if your mail handler transmits attachment names, you can set the attname field of the message header. Otherwise, impmsg() will set this field to the filename used to associate the attachment with the message (this will have the form "00012345.67A" where 1234567 is the message ID). In general, you should setmem() to all-zeros any fields you do not want to explicitly set yourself. Only the msgid and nrpl fields will always be set by the engine.

Attachments are very easy to deal with. The caller need merely provide the current path and filename of the attachment in the filatt parameter, and the file will be copied to the correct path and filename by impmsg().

The following status codes may be returned by impmsg():

GMEAGAIN Cycle, then call impmsg() again.

GMEOK The message has been imported successfully.

GMEAFWD The message has been imported successfully and has been auto-forwarded. The original addressee is in the to field of the message header, and the address to which the message was forwarded can be gotten by calling gmexinf().

GMEERR The forum ID specified does not exist.

GMENFND The User-ID to which an e-mail message was being imported does not exist.

GMEDUP A message with the global ID specified by this message is already present on the system.

GMENOAT The file attached to the message could not be imported for some reason (file not found, couldn’t rename, I/O error, etc.).

Hookable Notifications

Applies to: WG2+

In order to facilitate synchronization between the GME and outside processes, a system of hookable notifications has been implemented. To set a hook, simply call the following function:

BOOL                    /*   returns TRUE if hook set           */
hook_gme(               /* set a GME function hook              */
int hooktype,           /*   type of hook to set                */
voidfunc hookfunc);     /*   hook function pointer              */

typedef void (*voidfunc)(void); /* generic function pointer     */

The hooktype argument specifies the event for which you wish to receive notification, and the hookfunc argument is a pointer to the function that is to be called when the event occurs. The hook_gme() function returns FALSE if the hook could not be set (insufficient memory).

The hook type may be one of the following:

                               /* hook_gme() hook type codes           */
#define GMEHOOK_NOT_NEWMSG  1  /*   notification of new messages       */
#define GMEHOOK_NOT_NEWMSGL 2  /*   low-level new message notification */
#define GMEHOOK_NOT_NEWFOR  3  /*   notification of forum creation     */
#define GMEHOOK_NOT_UPDMSG  4  /*   notification of message update     */
#define GMEHOOK_NOT_UPDFOR  5  /*   notification of forum update       */
#define GMEHOOK_NOT_DELMSG  6  /*   notification of message deleted    */
#define GMEHOOK_NOT_DELMSGL 7  /*   low-level msg deleted notification */
#define GMEHOOK_NOT_DELFOR  8  /*   notification of forum deleted      */
#define GMEHOOK_NOT_DELFORL 9  /*   low-level forum delete notification*/

Note that many of the notification types come in a normal and a low-level variety. In general, normal notification types give more information, but low-level notifications are more efficient because they are usually cycled (the GME function being called returns GMEAGAIN between calls to hooks). Typically, both the normal and low-level notifications will be called for a given event, but the order in which they are called (normal first or low-level first) is undefined.

The information passed to the hook function varies depending on the hook type (the voidfunc typedef is simply for convenience). It is important to note that all buffers passed to notification functions should be considered read-only and must not be modified in any way.

The following type of function must be used for a new message notification hook:

typedef void
(*gmehook_not_newmsg)(         /* new message hook                     */
int newtype,                   /*   how new message was generated code */
const struct message *msg,     /*   new message header                 */
const char *text);             /*   new message text                   */

The newtype argument describes the context in which the message was generated. It may have one of the following values:

                               /* new message type codes               */
#define NEWMSG_WRITE 0         /*   new message written                */
#define NEWMSG_REPLY 1         /*   reply written                      */
#define NEWMSG_IMPRT 2         /*   message imported                   */
#define NEWMSG_DISTR 3         /*   message written as part of dist.   */
#define NEWMSG_CCOPY 4         /*   message carbon copied              */
#define NEWMSG_COPY  5         /*   message copied                     */
#define NEWMSG_FORWD 6         /*   message forwarded                  */
#define NEWMSG_RTRCP 7         /*   return receipt generated           */

The msg and text arguments are the message header and body text as saved (i.e., the message header is fully filled-out). Application-defined information is available within this function using the gmeGetAppInfo() function. Also, gmexinf() will return the User-ID to which the message was originally addressed if the message was autoforwarded, otherwise it will return an empty string ("").

The following type of function must be used for a low-level new message notification hook:

typedef void
(*gmehook_not_newmsgl)(        /* low-level new message hook           */
const struct message *msg,     /*   new message header                 */
const char *text);             /*   new message text                   */

The msg and text arguments are the same as above with one exception: the text argument will be NULL if the message is a message pointer.

Application-defined information is also available within this hook, but auto-forward information is not.

It is also important to note that this hook will only be called when a message is written into the local message base. It will not be called when a message is sent to an exporter.

The following type of function must be used for a new forum notification hook:

typedef void
(*gmehook_not_newfor)(         /* forum has been created hook          */
const struct fordsk *newdef,   /*   new forum definition structure     */
const char *desc,              /*   descriptive text                   */
const char *echoes);           /*   pointer to array of echo addresses */

The arguments to this function are as-saved (i.e., all fields of the forum definition have been filled in). Note that the forum definition is in the on-disk structure, also that the echoes argument may be NULL if there are no echoes.

The following type of function must be used for a message-updated notification hook:

typedef void
(*gmehook_not_updmsg)(         /* message update hook                  */
int updtype,                   /*   how message was updated code       */
const struct message *msg,     /*   message header                     */
const char *text);             /*   message text                       */

The updtype argument describes the context in which the message was modified. Currently it is always zero. The msg and text arguments are the message as saved.

The following type of function must be used for a forum-updated notification hook:

typedef void
(*gmehook_not_updfor)(         /* forum has been updated hook          */
const struct fordef *newdef,   /*   forum definition structure         */
const char *desc,              /*   descriptive text                   */
const char *echoes);           /*   pointer to array of echo addresses */
                               /*(desc & echoes may be NULL if no chng)*/

Note that the forum definition uses the in-memory structure and that the desc and echoes arguments may be NULL if they were not modified.

The following type of function must be used for a message-deleted notification hook:

typedef void
(*gmehook_not_delmsg)(         /* message has been deleted hook        */
int deltype,                   /*   how new message was deleted code   */
const struct message *msg,     /*   new message header                 */
const char *text);             /*   new message text                   */

The deltype argument describes the context in which the message was deleted. It may have one of the following values:

                               /* message deletion type codes          */
#define DELMSG_NORM  0         /*   normal deletion of message         */
#define DELMSG_FORWD 1         /*   message forwarded                  */
#define DELMSG_CLNUP 2         /*   message deleted during cleanup     */

The msg and text arguments are the message as it existed on disk immediately before being deleted. A couple of things to note about this hook: it should be assumed that the message no longer exists when this hook is called, and this hook will not be called when a message pointer is deleted due to its parent having been deleted.

The following type of function must be used for a low-level message-deleted notification hook:

typedef void
(*gmehook_not_delmsgl)(        /* low-level message deleted hook       */
unsigned forum,                /*   forum ID message deleted from      */
long msgid);                   /*   message ID of deleted message      */

This hook will be called for all messages deleted from the local message base.

The following type of function must be used for a forum-deleted notification hook:

typedef void
(*gmehook_not_delfor)(         /* forum has been deleted hook          */
const struct fordsk *def,      /*   forum definition structure         */
const char *desc,              /*   descriptive text                   */
const char *echoes);           /*   pointer to array of echo addresses */

The arguments passed to this hook are the forum as it existed on disk immediately before being deleted (the message counters may not be up-to-date). The forum still exists in memory when this notification is called, so you can use getdefp() to access the most up to date information of the forum. Note that the echoes argument may be NULL if there are no echoes.

The following type of function must be used for a low-level forum-deleted notification hook:

typedef void
(*gmehook_not_delforl)(        /* low-level forum deleted hook         */
unsigned forum);               /*   forum ID of deleted forum          */

This hook is more efficient than the normal hook because it is cycled, but the forum no longer exists in memory when this hook is being called.

Applies to: WG2+

Header check (GME.H, GMEUTL.H): GME.H also defines GMEHOOK_NONE (0, "no hook set (internal use only)") and the update-type codes UPDMSG_APINF, UPDMSG_APRV, UPDMSG_EXMT, UPDMSG_MODFY and UPDMSG_REPLY, all currently 0, consistent with "Currently it is always zero." Internally the engine keeps the hooks in struct gmehook (GMEUTL.H: hooktype, hookfunc) and dispatches with notnwm(), notnwml(), notnwf(), notudm(), notmdf(), notdlm(), notdlml(), notdlf(), notdlfl() and nexthook(); these are engine internals, not API.

Conflict Checking

Because all information about a GME request is stored in the work area, and the work area is owned by the caller, not the engine, GME relies on a system of cooperative conflict checking to avoid problems. Modules that use GME to read or write messages (including importers) should register conflict checking functions. Before a message or forum is deleted or modified, GME polls all registered conflict checking functions to see if anyone is currently using that message or forum. If anyone is using it, GME rejects the modify or delete request.

The function to register a conflict checker is:

typedef BOOL (*cflfunc)(void *work,unsigned forum,long msgid);

BOOL                               /*   returns TRUE if able to add to list*/
setcfl(                            /* set cooperative conflict checker     */
cflfunc cflchk);                   /*   function to check                  */

The parameters passed to a conflict checker are: a work area pointer, a forum ID, and a message ID. The work area parameter is the work area being used for the delete or modify request that is having its conflict checked. This is provided so your conflict checker can recognize if your module is the one doing the delete or modify request. The message ID is the message to be deleted or modified. If the message ID is zero, then it is the forum that is being deleted or modified, and its ID is passed in the forum ID parameter.

As a simple example, consider the following conflict checker, for a module which deals with one message at a time:

void *mywrkbuf;                    /* my GME request work area             */
unsigned myforum;                  /* the forum I'm currently working with */
long mymsgid;                      /* the msg I'm currently working with   */

void EXPORT
init__mymod(void)
{
     ...
     mywrkbuf=alczer(GMEWRKSZ);
     setcfl(mychecker);
     ...
}
BOOL
mychecker(                         /* my conflict checker                  */
void *workb,
unsigned forum,
long msgid)
{
     if (workb != mywrkbuf) {
          if (msgid == 0L) {
               return(forum == myforum);
          }
          else {
               return(msgid == mymsgid);
          }
     }
     return(FALSE);
}

If you have a number of work areas that you use for reading messages, you may want to use this function:

BOOL                               /*   returns TRUE if a conflict         */
chkmycfl(                          /* check my current message for conflict*/
void *workb,                       /*   my work area being used to read    */
unsigned forum,                    /*   forum ID w/possible conflict       */
long msgid);                       /*   message ID w/possible conflict     */

It checks for conflict with the read context (see page 212) in the work area passed to it. This function can only be used to check work areas being used to read messages. If your module also writes messages, you will have to provide some other means for detecting conflicts with your write requests. To keep things somewhat simpler, it is only necessary to check for forum conflicts with write requests.

An example use of chkmycfl() is as follows:

#define NUMWORKS 10                /* how many GME requests I can do @ once*/
void *myworks[NUMWORKS];           /* my array of work area pointers       */

void EXPORT
init__mymod(void)                  /* init my module that reads messages   */
{
     int i;
     ...
     for (i=0 ; i < NUMWORKS ; ++i) {
          myworks[i]=alczer(GMEWRKSZ);
     }
     setcfl(mychecker);
     ...
}

BOOL
mychecker(                         /* my conflict checker                  */
void *workb,
unsigned forum,
long msgid)
{
     int i;

     for (i=0 ; i < NUMWORKS ; ++i) {
          if (myworks[i] != workb && gmerqopn(myworks[i])) {
               if (chkmycfl(myworks[i],forum,msgid)) {
                    return(TRUE);
               }
          }
     }
     return(FALSE);
}

To check for any conflicts with the current message in your read context before beginning a modify or delete request, use the following function:

BOOL                               /*   returns TRUE if a conflict         */
chkcfl(                            /* chk others for conflict w/my cur msg */
void *workb);                      /*   work area being used to read       */

To check for conflict with any arbitrary message or forum, you can use the following function:

BOOL                               /*   returns TRUE if a conflict         */
gencfl(                            /* generic conflict checker             */
void *workb,                       /*   work area in use                   */
unsigned forum,                    /*   forum ID to check                  */
long msgid);                       /*   msg ID to check (0L for forum only)*/

Note: You should always pass a valid (though not necessarily initialized) work area to this function.

GALTEXT Formatted Text Handler

Applies to: WG2+

Formatted text is now supported in e-mail and forum message body text. However, some interfaces cannot properly display such text. To facilitate the conversion of formatted text from one format to another, an extensible generic formatted text handling API has been developed.

The type of text formats GALTEXT is designed to handle are those that encode formatting using displayable ASCII (characters with values between 32 and 127). These formats can be stored as strings and transmitted over 7-bit connections with no loss of information. Currently, only Microsoft’s Rich Text Format (RTF) is supported, and the only conversion available is from RTF to plain ASCII. Additional formats can be added easily, and more conversion options may be added later.

All structures and functions used for this process are declared in galtext.h and exported in galtext.lib.

Registering Format Handlers

To provide a new format handler, you must provide a defined set of functions, fill in a certain structure, and register the new text handler with GALTEXT. The structure to fill in is as follows:

#define FMTDSCSZ 11            /* format description size              */

struct fmthlr {                /* formatted text handling structure    */
     char fmtdesc[FMTDSCSZ];   /*   format description (e.g. "RTF")    */
     int flags;                /*   format handler flags               */
     txtdetf *detect;          /*   function for detecting format      */
     txtcvtf *toasc;           /*   function for converting to ASCII   */
     txtinsf *insasc;          /*   function to insert ASCII           */
     txtcvtf *stpfmt;          /*   simple format stripping function   */
};

The fmtdesc is a brief name for the format (e.g., "RTF" or "HTML"). No flags are defined at this time; the field is provided for future expansion.

The first function vector, detect, is used to detect formatted text. This function must be of the following type:

typedef BOOL                   /*   is this text in your format?       */
        (txtdetf)(             /* format detection function            */
        const char *srcstr);   /*   string to examine                  */

The srcstr argument is a buffer containing possibly formatted text in the form of a NUL-terminated string. This function must examine (without changing) the contents of buffer and determine whether it is the format managed by this handler. Typically, formatted text begins with a characteristic signature. For example, all RTF begins with "{\rtf", and HTML optionally begins with "<HTML>".

This function should return TRUE if the contents of the buffer are the format managed by this handler.

The second function vector, toasc, is used to convert formatted text to plain ASCII while maintaining as much of the formatting as possible (e.g., tabs, margins, etc.). It should be the following type:

typedef BOOL                   /*   could handle conversion?           */
        (txtcvtf)(             /* text converter function type         */
        const char *srcbuf,    /*   source buffer                      */
        char *dstbuf,          /*   destination buffer                 */
        unsigned dstsiz);      /*   destination buffer size            */

The first argument is a string containing formatted text. The second argument is the buffer into which the converted ASCII should be placed, and the third argument is the size of the destination buffer. This function should return FALSE if the source text is not the correct format or if the conversion fails for some reason (the destination buffer may be altered in this case). This function should not return false due to a destination buffer overflow.

Note that this function first should examine the source to determine whether it is the correct format (e.g., by calling its detect vector) before attempting a conversion. When a conversion is requested, the conversion vectors are polled until one of them performs the conversion.

The third function vector, insasc, is used to insert ASCII text into a buffer containing formatted text. It should be of the following type:

typedef BOOL                   /*   was able to insert?                */
        (txtinsf)(             /* text inserter function type          */
        BOOL endflg,           /*   insert at end (vs. at beginning)   */
        const char *srcbuf,    /*   buffer containing ASCII text       */
        char *dstbuf,          /*   buffer containing formatted text   */
        unsigned dstsiz);      /*   destination buffer size            */

The first argument will be FALSE if the new text is to be inserted at the beginning of the formatted text, and TRUE if it is to be inserted at the end. The second argument is a string containing the ASCII text to be inserted. The third argument is a buffer containing the formatted text into which the new text is to be inserted, and the last argument is the size of the destination buffer.

This function should return FALSE if the formatted text is not the correct format or if the insertion fails for some reason. If the combination of the new text and the preexisting formatted text is too long to fit in the destination buffer, the new text should be truncated as necessary in order to fit without losing any of the existing text.

The last function vector, stpfmt, is very similar in function to the convert-to-ASCII vector. It is used to convert formatted text to plain ASCII. However, it should do the simplest conversion possible, maintaining all text content, but not attempting to retain any formatting information other than end-of-paragraph markers (for which carriage returns, '\r', should be used).

Note that it is the same type of function as the toasc vector. It takes the same arguments and should also determine whether the formatted text is the supported format before doing any conversion.

Once the text handler structure has been filled in, the format handler is registered using the following function:

void
register_fmthlr(        /* register formatted text handler      */
struct fmthlr *fmthlr); /*   formatted text handling struct     */

The one argument is a pointer to the filled-in format handler structure.

Note that there is currently no standard way to replace an existing format handler and that no attempt is made to detect collisions between format handlers (handlers with the same name or for the same format).

Using the Formatted Text Handler

The purpose of GALTEXT is to provide processes with a single mechanism for dealing with formatted text, regardless what format is used. The four function vectors of the format handler structure are genericized into the following functions.

The following function is used to detect formatted text:

BOOL                    /*   is this text formatted?            */
isfmtted(               /* check for formatted text             */
const char *srcstr);    /*   string to examine                  */

It polls the detect vectors of all registered format handlers and returns TRUE if any of them return TRUE. If isfmtted() returns FALSE, the text should be assumed to be plain ASCII.

The following function is used to determine the name of the format used:

const char *            /*   returns name of format             */
fmtname(                /* get name of format used in this text */
const char *fmtstr);    /*   string containing formatted text   */

This function returns the fmtdesc field of the format handler that claims the given text, otherwise it returns an empty string ("").

The following functions are the generic equivalents of the toasc, insasc, and stpfmt vectors of the formatted text handling structure. See the above discussions of these vectors for descriptions of the arguments and nature of operation.

BOOL                    /*   was able to convert?               */
cvt2asc(                /* convert formatted text to ASCII      */
const char *fmtsrc,     /*   formatted source string            */
char *ascdst,           /*   ASCII destination buffer           */
unsigned dstsiz);       /*   destination buffer size            */
BOOL                    /*   was able to insert?                */
insasc(                 /* insert ASCII into formatted text     */
BOOL endflg,            /*   insert at end (vs. at beginning)   */
const char *srcbuf,     /*   buffer containing ASCII text       */
char *dstbuf,           /*   buffer containing formatted text   */
unsigned dstsiz);       /*   destination buffer size            */
BOOL                    /*   was able to strip?                 */
stripfmt(               /* strip formatting                     */
const char *fmtsrc,     /*   formatted source string            */
char *ascdst,           /*   ASCII destination buffer           */
unsigned dstsiz);       /*   destination buffer size            */

Applies to: WG2+

Header check (GALTEXT.H, new in WG2): the prototypes and the struct fmthlr agree with the text above. GALTEXT.H also declares RTFSTKSZ (10, RTF reader stack size), int nfmthlr(void) (number of registered format handlers) and struct fmthlr **fharr(void) (array of pointers to the handlers); the addendum does not describe these.

Changes to Internal GME Routines and Structures (WG1 to WG2)

Applies to: WG3.x

Header check (3.2): of the internals listed here only the entry points in GME.H remain public. gmework and gmehook are removed (callers pass an opaque VOID *pWork; GMEWRKSZ is 518 under GCDOS and 1536 otherwise, GME.H:38-42: use the macro, never a literal size), and cscflchk, hdlntfy, nextcc, sndexp, updmsg, uplinf, clsogme, evt and the notnwm/notudm... hooks are not declared in WGDEV/INC. iniogme is init__galme as in WG2. hdlfmtxt (GMEUTL.H) is likewise gone; the STATIC in the list below is the WG2 keyword macro (chapter 2).

Applies to: WG2+

The following were found by comparing the WG1 (WGSERV1\SRC) and WG2 (WGSERV2\SRC) headers. The WG1 text of this chapter does not name any of them (they are engine and C/S-agent internals, not part of the GME.H API), so no earlier passage needed correcting; they are recorded here for developers who have source-level dependencies on them.


Previous: Major BBS v10: 05 User Services  |  Contents  |  Next: Major BBS v10: 07 Operator Interface