Versions Compared

Key

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

Audit Trail API

Applies to: WG3.x

Editor's note: this chapter is new in the WG3 layer. It is from section 8 ("Audit Trail API") of the Developer's Addendum for Worldgroup 3.12 (wg312dev; the earlier 3.10 edition, devad3, is the same text apart from "3.10" for "3.12", BC5 for BC50, InstallShield V5.0 for V5.1 and spelling). The addendum has no figures. Prose is unrewritten; "Header check" notes record where the printed text disagrees with the WG3.2 headers. It extends the one-line audit() call of chapter 8 (Operator Services) into a file API.

OVERVIEW

The Worldgroup Major BBS Audit Trail is used to track system events. A chronological list of these events can by listed by the system operator. Each event consists of a time stamp, a channel or other context description, a brief description of the event, and a detailed description of the event. Worldgroup The Major BBS keeps all of these event records in a single file with a specific format. The Audit Trail API provides a standard mechanism for reading from and writing to the Worldgroup Major BBS Audit Trail, and for creating other audit trails.

File Format

The files managed by this API are binary/text files. They are treated by the API as binary files with fixed-length records, and referenced by record number. Internally, the files are formatted as fixed-length ASCII text files, so that they can be read by generic data file utilities.

...

FieldOffsetLengthDescription
Time Stamp015The date and time at which the entry was added to the file. It consists of a sort format date string, followed by a space, followed by a sort format time string. For example, October 28, 1997 at 4:25:34 PM is represented by: "19971028 162534".
Short Desc.1632A short description of the event; usually all upper case and the same for each similar event.
Channel4916A description of the channel or other context in which the event occurred.
Detail66127A detailed description of the event; usually mixed case and may contain event-specific information.
EOL1942End of line marker ("\r\n").
Total:196

Online Context

Some audit trail functions require an online context to operate properly. The following global variables are required for the online context: usrnum, nterms, errcod, channel[]. These variables determine what is stored in the channel field of an audit trail record. This is determined as follows:

...

3. If usrnum is outside the range zero to nterms-1, the channel text is "U# XXXX" where XXXX is the hexadecimal value of usrnum.

Example

Below is a code example that opens an audit trail file, adds a record, reads and displays the last ten records, and then closes the file.

...

     /* close and exit */
     audfClose(haud);
     return(0);
}

Result Codes

Most Audit Trail API functions return a code that describes the result of the operation. In general, a negative code indicates failure while a zero or positive code indicates success. The following is a list of all

...

IdentifierValueDescription
AUDERR_OK0The operation completed successfully.
AUDERR_NEW1When opening a file, the specified file was not found, so a new file was created.
AUDERR_DAMAGED2When opening a file, it was found to have been damaged, so you must recover the file before proceeding.
AUDERR_FIO-1An I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_MEMORY-2There was not enough memory to complete the requested operation.
AUDERR_NOTOPEN-3The file is not open, you must close and re-open it before you can use it.
AUDERR_MODE-4The requested operation was not valid for the mode used when opening the file (e.g., attempting to write to a read-only file).
AUDERR_NOTFOUND-5The requested record was not found (the record number was out of range).

Structures

The following is a list of structures defined by the Audit Trail API.

...

TextMeaning
Chan XXThe specified channel was being serviced when the event occurred. XX is the channel number in hexadecimal as seen in the channel grid.
U# XXXXThe specified user number was in effect when the event occurred. XXXX is the user number in hexadecimal as represented by the global usrnum. This channel type is used when usrnum is outside the range of defined channels.
ConsoleThe event was generated by the Worldgroup Major BBS console or by a background task. This channel type is used when usrnum is equal to AUDCHAN_CONSOLE (-1)
CleanupThe event was generated during cleanup. This channel type is used when usrnum is equal to AUDCHAN_CLEANUP (-2).
Event #The event was generated while shutting down to perform a scheduled event. # is the event number in decimal. This channel type is used when usrnum is equal to AUDCHAN_EVENT (-3).

...

add-ons that use the old format should continue to use the known offsets into a character buffer approach to extracting fields from old-style records rather than using this structure directly.

Functions

The following is an alphabetical list of all functions provided by the Audit Trail API.

audAddEntry()

Applies to: WG3.x

Header check: the function is audfAddEntry() (AUDAPI.h:92); the prototype printed below already shows that name.

...

AUDERR_OKThe operation completed successfully.
AUDERR_NEWThe file was not found, so a new file was created. (This code will not be returned under normal conditions.)
AUDERR_DAMAGEDThe file is damaged; you must recover the file before continuing. (This code will not be returned under normal conditions.)
AUDERR_FIOAn I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_MODEThe requested operation was not valid for the mode used when opening the file (e.g., attempting to write to a read-only file).

audAddLowLevel()

Applies to: WG3.x

Header check: the function is audfAddLowLevel() (AUDAPI.h:174).

...

AUDERR_OKThe operation completed successfully.
AUDERR_NEWThe file was not found, so a new file was created. (This code will not be returned under normal conditions.)
AUDERR_DAMAGEDThe file is damaged; you must recover the file before continuing. (This code will not be returned under normal conditions.)
AUDERR_FIOAn I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_MODEThe requested operation was not valid for the mode used when opening the file (e.g., attempting to write to a read-only file).

audAddfChannelStr ()

Applies to: WG3.x

Header check: the function is audfChannelStr() (AUDAPI.h:140); audAddfChannelStr appears nowhere in WGDEV/INC.

...

A pointer to the buf argument.

audfclose()

Applies to: WG3.x

Header check: C identifiers are case-sensitive: the function is audfClose() (AUDAPI.h:80).

...

The handle of the file to close. This handle must have been gotten from a successful call to audfOpen().

audfCvtEntryToOld()

struct audOldStyle *               /*   returns pointer to buffer          */
audfCvtEntryToOld(                 /* convert an entry to old-style        */
const struct audEntry *src,        /*   new-style audit trail entry        */
struct audOldStyle *buf,           /*   buffer to receive converted entry  */
size_t bufSiz);                    /*   size of destination buffer         */

...

A pointer to the buf argument.

audfCvtRawToEntry ()

struct audEntry *                  /*   returns pointer to buffer          */
audfCvtRawToEntry(                 /* convert raw file data to entry       */
const CHAR *src,                   /*   raw file data                      */
struct audEntry *buf,              /*   buffer to receive converted entry  */
size_t bufSiz);                    /*   size of destination buffer         */

...

A pointer to the buf argument.

audfFindEntryDOS()

INT                                /*   returns result code                */
audfFindEntryDOS(                  /* find an entry by DOS date and time   */
HAUDFILE haud,                     /*   audit trail file to use            */
USHORT dosDate,                    /*   DOS-style date to search for       */
USHORT dosTime,                    /*   DOS-style time to search for       */
ULONG *pRecNum,                    /*   buf for rec # (NULL if don't want) */
struct audEntry *buf,              /*   buf for entry (NULL if don't want) */
size_t bufSiz);                    /*   size of destination buffer         */

...

AUDERR_OKThe operation completed successfully.
AUDERR_FIOAn I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUNDThe file is empty.

audfFindEntryStr()

INT                                /*   returns result code                */
audfFindEntryStr(                  /* find an entry by string date & time  */
HAUDFILE haud,                     /*   audit trail file to use            */
const CHAR *strDate,               /*   YYYYMMDD date to search for        */
const CHAR *strTime,               /*   HHMMSS time to search for          */
ULONG *pRecNum,                    /*   buf for rec # (NULL if don't want) */
struct audEntry *buf,              /*   buf for entry (NULL if don't want) */
size_t bufSiz);                    /*   size of destination buffer         */

...

AUDERR_OKThe operation completed successfully.
AUDERR_FIOAn I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUNDThe file is empty.

audfFormatEntry ()

struct audEntry *                  /*   returns pointer to destination     */
audfFormatEntry(                   /* create properly-formatted entry      */
struct audEntry *buf,              /*   buffer to receive entry            */
size_t bufSiz,                     /*   size of destination buffer         */
const CHAR *brief,                 /*   brief description                  */
const CHAR *chanStr,               /*   channel description string         */
const CHAR *detail,                /*   detailed description/format string */
va_list argList);                  /*   argument list                      */

...

A pointer to the buf argument.

audfNumRecs ()

ULONG
audfNumRecs(                       /* get number of records in file        */
HAUDFILE haud);                    /*   audit trail file to use            */

...

The number of records in the file.

audfOpen()

INT                                /*   returns result code                */
audfOpen(                          /* open an audit trail file             */
HAUDFILE *phaud,                   /*   buffer to receive opened handle    */
const CHAR *fileName,              /*   name of file to open               */
AUDMODE mode);                     /*   mode in which to open              */

...

AUDERR_OKThe operation completed successfully.
AUDERR_NEWThe specified file was not found, so a new file was created.
AUDERR_DAMAGEDThe file is damaged. You must recover the file before proceeding.
AUDERR_FIOAn I/O error occurred while performing an operation; check the global variable errno for the specific error. This response will be returned if you try to open a non-existent file in read-only mode.
AUDERR_MEMORYThere was not enough memory to open the file.

audfReadEntry()

INT                                /*   returns result code                */
audfReadEntry(                     /* read an entry by record number       */
HAUDFILE haud,                     /*   audit trail file to use            */
ULONG recNum,                      /*   record number to read              */
struct audEntry *buf,              /*   buffer to receive data             */
size_t bufSiz);                    /*   size of destination buffer         */

...

AUDERR_OKThe record was read successfully.
AUDERR_FIOAn I/O error occurred while reading the record. Check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUNDThe requested record was not found (the record number was out of range).

audfReadLowLevel()

INT                                /*   returns result code                */
audfReadLowLevel(                  /* low-level read an entry utility      */
HAUDFILE haud,                     /*   audit trail file to use            */
ULONG recNum,                      /*   record number to read              */
CHAR *buf,                         /*   buffer (must be AUDRECLEN+1 long)  */
size_t bufSiz);                    /*   size of buffer                     */

...

AUDERR_OKThe record was read successfully.
AUDERR_FIOAn I/O error occurred while reading the record. Check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUNDThe requested record was not found (the record number was out of range).

audfReadOldStyle()

INT                                /*   returns result code                */
audfReadOldStyle(                  /* read an old-style entry              */
HAUDFILE haud,                     /*   audit trail file to use            */
ULONG recNum,                      /*   record number to read              */
struct audOldStyle *buf,           /*   buffer to receive data             */
size_t bufSiz);                    /*   size of destination buffer         */

...

AUDERR_OKThe record was read successfully.
AUDERR_FIOAn I/O error occurred while reading the record. Check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUNDThe requested record was not found (the record number was out of range).

audfRecover()

INT                                /*   returns result code                */
audfRecover(                       /* recover a damaged audit trail file   */
HAUDFILE haud);                    /*   handle to file to recover          */

...

AUDERR_OKThe operation completed successfully.
AUDERR_NEWThe specified file was not found, so a new file was created. (This code will not be returned under normal conditions.)
AUDERR_DAMAGEDThe file is still damaged. (This code will not be returned under normal conditions.)
AUDERR_FIOAn I/O error occurred while recovering the file; check the global variable errno for the specific error.

audfVAddEntry()

INT                                /*   returns result code                */
audfVAddEntry(                     /* add entry with variable argument list*/
HAUDFILE haud,                     /*   audit trail file to use            */
const CHAR *brief,                 /*   brief description                  */
const CHAR *detail,                /*   detailed description/format string */
va_list argList);                  /*   argument list                      */

...