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",BC5forBC50, 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-lineaudit()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.
...
| Field | Offset | Length | Description |
|---|---|---|---|
| Time Stamp | 0 | 15 | The 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. | 16 | 32 | A short description of the event; usually all upper case and the same for each similar event. |
| Channel | 49 | 16 | A description of the channel or other context in which the event occurred. |
| Detail | 66 | 127 | A detailed description of the event; usually mixed case and may contain event-specific information. |
| EOL | 194 | 2 | End 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
...
| Identifier | Value | Description |
|---|---|---|
| AUDERR_OK | 0 | The operation completed successfully. |
| AUDERR_NEW | 1 | When opening a file, the specified file was not found, so a new file was created. |
| AUDERR_DAMAGED | 2 | When opening a file, it was found to have been damaged, so you must recover the file before proceeding. |
| AUDERR_FIO | -1 | An I/O error occurred while performing an operation; check the global variable errno for the specific error. |
| AUDERR_MEMORY | -2 | There was not enough memory to complete the requested operation. |
| AUDERR_NOTOPEN | -3 | The file is not open, you must close and re-open it before you can use it. |
| AUDERR_MODE | -4 | The 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 | -5 | The 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.
...
| Text | Meaning |
|---|---|
| Chan XX | The specified channel was being serviced when the event occurred. XX is the channel number in hexadecimal as seen in the channel grid. |
| U# XXXX | The 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. |
| Console | The 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) |
| Cleanup | The 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_OK | The operation completed successfully. |
|---|---|
| AUDERR_NEW | The file was not found, so a new file was created. (This code will not be returned under normal conditions.) |
| AUDERR_DAMAGED | The file is damaged; you must recover the file before continuing. (This code will not be returned under normal conditions.) |
| AUDERR_FIO | An I/O error occurred while performing an operation; check the global variable errno for the specific error. |
| AUDERR_NOTOPEN | The file is not open, you must close and reopen it before you can use it. |
| AUDERR_MODE | The 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_OK | The operation completed successfully. |
|---|---|
| AUDERR_NEW | The file was not found, so a new file was created. (This code will not be returned under normal conditions.) |
| AUDERR_DAMAGED | The file is damaged; you must recover the file before continuing. (This code will not be returned under normal conditions.) |
| AUDERR_FIO | An I/O error occurred while performing an operation; check the global variable errno for the specific error. |
| AUDERR_NOTOPEN | The file is not open, you must close and reopen it before you can use it. |
| AUDERR_MODE | The 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);audAddfChannelStrappears nowhere inWGDEV/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_OK | The operation completed successfully. |
|---|---|
| AUDERR_FIO | An I/O error occurred while performing an operation; check the global variable errno for the specific error. |
| AUDERR_NOTOPEN | The file is not open, you must close and reopen it before you can use it. |
| AUDERR_NOTFOUND | The 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_OK | The operation completed successfully. |
|---|---|
| AUDERR_FIO | An I/O error occurred while performing an operation; check the global variable errno for the specific error. |
| AUDERR_NOTOPEN | The file is not open, you must close and reopen it before you can use it. |
| AUDERR_NOTFOUND | The 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_OK | The operation completed successfully. |
|---|---|
| AUDERR_NEW | The specified file was not found, so a new file was created. |
| AUDERR_DAMAGED | The file is damaged. You must recover the file before proceeding. |
| AUDERR_FIO | An 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_MEMORY | There 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_OK | The record was read successfully. |
|---|---|
| AUDERR_FIO | An I/O error occurred while reading the record. Check the global variable errno for the specific error. |
| AUDERR_NOTOPEN | The file is not open, you must close and reopen it before you can use it. |
| AUDERR_NOTFOUND | The 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_OK | The record was read successfully. |
|---|---|
| AUDERR_FIO | An I/O error occurred while reading the record. Check the global variable errno for the specific error. |
| AUDERR_NOTOPEN | The file is not open, you must close and reopen it before you can use it. |
| AUDERR_NOTFOUND | The 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_OK | The record was read successfully. |
|---|---|
| AUDERR_FIO | An I/O error occurred while reading the record. Check the global variable errno for the specific error. |
| AUDERR_NOTOPEN | The file is not open, you must close and reopen it before you can use it. |
| AUDERR_NOTFOUND | The 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_OK | The operation completed successfully. |
|---|---|
| AUDERR_NEW | The specified file was not found, so a new file was created. (This code will not be returned under normal conditions.) |
| AUDERR_DAMAGED | The file is still damaged. (This code will not be returned under normal conditions.) |
| AUDERR_FIO | An 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 */...