ProBoard BBS Documentation

The Choice of Professionals

User Tools

Site Tools

Trace:
proboard_interface_functions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
proboard_interface_functions [2023/06/20 07:24] – created adminproboard_interface_functions [2023/06/20 08:52] (current) – admin
Line 6: Line 6:
 Several types have been defined in the file PB_SDK.H Several types have been defined in the file PB_SDK.H
  
-     bool    : a boolean value that can have the values TRUE or FALSE +  bool    : a boolean value that can have the values TRUE or FALSE 
-     byte    : an unsigned character (8 bits) +  byte    : an unsigned character (8 bits) 
-     word    : an unsigned short integer (16 bits) +  word    : an unsigned short integer (16 bits) 
-     dword   : an unsigned long integer (32 bits) +  dword   : an unsigned long integer (32 bits) 
-     KEY     : used for key scan codes (for sysopkey handlers and the +  KEY     : used for key scan codes (for sysopkey handlers and the 
-               ScanKey() function).+            ScanKey() function). 
 +                
 +====== void AddTime( int min ); ====== 
 +Adds 'min' minutes to the user's time left. If 'min' is negative, the 
 +number of minutes will be subtracted from the time left. 
 + 
 +Examples:     
 +  AddTime( 10 );      /* Adds 10 minutes     */ 
 +  AddTime( -5 );      /* Subtracts 5 minutes */ 
 + 
 +====== int TimeLeft( void ); ====== 
 +Returns the time left in minutes for the current user. 
 + 
 +====== int TimeOnline( void ); ====== 
 +Returns the time in minutes that the current user is online. 
 + 
 + 
 +====== void SuspendTimer( void ); ====== 
 +Suspends the online-timer for the current user. No time will be 
 +subtracted until RestartTimer() is called. 
 + 
 + 
 +====== void RestartTimer( void ); ====== 
 +Restarts the timer after a call to SuspendTimer(). 
 + 
 + 
 +====== void AdjustTime( void ); ====== 
 +Call this function if you changed the user's level. This recalculates all 
 +limits (time,download,...). 
 + 
 + 
 +====== void MsgEd( void ); ====== 
 +Fires up the internal message editor or the fullscreen editor, depending 
 +on the settings of the user. The message will be stored in the file 
 +MSGTMP in the current directory. If a message is aborted, the file MSGTMP 
 +will be deleted by the message editor.  If you create a MSGTMP file 
 +before invoking the message editor, this file will be used as a 'quote' 
 +message. 
 + 
 + 
 +====== int PostMessage( char *from, char *to, char *subject, int area, bool pvt ); ====== 
 +Posts a message to a user. 
 + 
 +  from    = Name of the sender 
 +  to      = Name of the user you're sending the message to 
 +  subject = Subject of the message 
 +  area    = Message area number where the message has to be posted in 
 +  pvt     = Private status (TRUE=private, FALSE=public) 
 + 
 +No checking is performed on any of the parameters! 
 + 
 +  Return value: -1 on error 
 +                 0 if ok 
 + 
 + 
 +====== int PostNetmail( char *from, char *to, char *subject, int area, FIDO_NODE *address, bool attach, bool crash, bool kill ); ====== 
 +Posts a netmail message. 
 + 
 +     from    = Name of the sender 
 +     to      = Name of the user you're sending the message to 
 +     subject = Subject of the message 
 +     area    = Message area number where the message has to be posted in 
 +     address = Destination node number of this message. 
 +     attach  = TRUE for a file attach message 
 +     crash   = TRUE if this message is a crashmail message 
 +     kill    = TRUE if the message has to be deleted after it is sent 
 + 
 +FIDO_NODE is a structure with the following fields: 
 + 
 +     struct 
 +     { 
 +          unsigned zone;      /* Zone number  */ 
 +          unsigned net;       /* Net number   */ 
 +          unsigned node;      /* Node number  */ 
 +          unsigned point;     /* Point number */ 
 +     } 
 + 
 +No checking is performed on any of the parameters! 
 + 
 +  Return value: -1 on error 
 +                 0 if ok 
 + 
 + 
 +====== bool ReadMsgArea( int area, MSGAREA *ma ); ====== 
 +Reads data about a message area. 
 + 
 +     area  =  Message area number (1-200) 
 +     ma    =  Pointer to a MSGAREA structure to be filled 
 + 
 +Check the file PB_SDK.H for details about the MSGAREA structure 
 +definition. 
 + 
 +  Return value: 6 
 +                FALSE if not defined 
 +                TRUE  if read ok 
 + 
 + 
 +====== bool ReadMessage( MESSAGE *msg, long msgid, int areanum ); ====== 
 +Reads message id <msgid> from area numer <areanum> into the MESSAGE 
 +structure.  To access the text of the message, use the function 
 +CreateMessageText().  See the file PB_SDK.H for a description of the 
 +MESSAGE structure. 
 + 
 +  Return value: FALSE if the message does not exists 
 +                TRUE  if the message is read ok 
 + 
 + 
 +====== void WriteMSGTMP( char *text ); ====== 
 +Writes the string <text> to the file MSGTMP. The file is always recreated 
 +when using this function. To append text to MSGTMP, use the function 
 +AppendMSGTMP(). You have to insert your own CR/LF pairs in the text if 
 +you want to force a newline.  Lines can be longer than 80 characters. The 
 +message processing functions will do a word-wrap if necessary.  Do NOT 
 +insert a single CR or LF in the text. (\r or \n). 
 + 
 + 
 +====== void AppendMSGTMP( char *text ); ====== 
 +Same as WriteMSGTMP(), but adds text to an EXISTING file. 
 + 
 + 
 +====== void ShowMessage( MESSAGE *msg ); ====== 
 +Shows the message <msg> to the user, including header and message text. 
 + 
 +See the file PB_SDK.H for an description of the MESSAGE structure. 
 + 
 + 
 +====== void CreateMessageText( MESSAGE *msg ); ====== 
 +Reads the text that belongs to message <msg>, and stores it in a file 
 +called MSGTMP in the current directory. This file can then be accessed as 
 +an ordinary textfile. 
 + 
 + 
 +====== void CreateMessageTextString( MESSAGE *msg, char *text, int max); ====== 
 +Reads the text that belongs to message <msg>, and stores it in the string 
 +<text>. The text will be terminated by a '\0' character.  You have to 
 +specify a maximum number of characters that can be stored in <text>. 
 + 
 + 
 + 
 +====== bool FirstMessage( MESSAGE *msg, int area, int order, long first); ====== 
 +====== bool NextMessage(  MESSAGE *msg, int area, int order ); ====== 
 +These functions are used to read messages in forward or reverse order. To 
 +start scanning messages, you have to call the FirstMessage() function 
 +first, and the NextMessage() function to read more messages. 
 + 
 +     msg   = MESSAGE structure where the message has to be stored. 
 +     area  = area number to read messages in 
 +     order = 1 for forward order, -1 for reverse order 
 +     first = message to start reading from. This message does NOT need to 
 +             exist. The first non-deleted message following this message 
 +             will be read first. 
 + 
 +See the file PB_SDK.H for an description of the MESSAGE structure. 
 + 
 +  Return value:  FALSE  No more messages found. 
 +                 TRUE   Message was found and read ok. 
 + 
 +This is an example on how to use these functions: 
 + 
 +     result  =  FirstMessage( msg,  
 +                              5, 
 +                              +1, 
 +                              1 ); 
 +     while ( result == TRUE ) 
 +     { 
 +          /* Do something with the message */ 
 +          result  =  NextMessage( msg, 
 +                                  5, 
 +                                  +1 ); 
 +     } 
 + 
 + 
 +====== void DeleteMessage( MESSAGE *msg ); ====== 
 +Deletes message <msg>. 
 + 
 + 
 +====== void MarkMessage( long msgid ); ====== 
 +Marks message <msgid> for later retrieval. Up to 200 messages can be 
 +marked. 
 + 
 + 
 +====== void ReadMarkedMessages( void ); ====== 
 +Shows all marked messages to the user, with the option to wait after each 
 +message. If the user selected to wait after each message, the standard 
 +message options menu will be shown to the user. (Next,Prev,Stop,...). 
 + 
 +In fact, this function is identical to menu function "Read Messages", 
 +with the user selecting "Marked". 
 + 
 + 
 +====== void ListMarkedMessages( void ); ====== 
 +Is similar to ReadMarkedMessages(), but this function acts as a 
 +"QuickScan Messages" with the user selecting "Marked". 
 + 
 + 
 +====== void UnMarkAllMessages( void ); ====== 
 +Unmarks all messages that were previously marked. You have to call this 
 +function before marking any messages, because the list of marked messages 
 +is remembered until a user logs off. 
 + 
 + 
 +====== int NumMsgAreas( void ); ====== 
 +Returns the highest message area number that is not empty. 
 + 
 + 
 +====== long GetLastRead( int areanum, long user_recno ); ====== 
 +====== void SetLastRead( int areanum, long user_recno, long msgid ); ====== 
 +Reads / Sets the lastread pointer for a specific user and message area. 
 +If GetLastRead() returns -1, an error occurred. 
 + 
 +     <areanum> ..... The area number (1-10000) 
 +     <user_recno> .. The record number of the user (0 - ...) 
 +     <msgid> ....... The id of the message you want to set the lastread 
 +                     pointer to. 
 + 
 + 
 +====== int FuzzySearch( char *text, char *string, int degree ); ====== 
 +Performs a fuzzy search for <string> in <text>. <degree> is the 
 +percentage of the characters in <string> that have to match. 
 + 
 +  Return value: -1 if not found 
 +                >0 percentage of characters matched 
 + 
 + 
 +====== IO_... functions ====== 
 +All functions starting with IO_ are low-level functions to access the 
 +serial port directly. Do NOT use these functions for ordinary I/O 
 +operations. They are intended for writing file transfer protocols. See 
 +the file PB_SDK.H for the prototypes of these functions. 
 + 
 + 
 +====== char WaitKey( void ); ====== 
 +Waits for a character to be read from the modem or local keyboard. 
 + 
 +  Return value: the character read. 
 + 
 + 
 +====== char WaitKeys( char *keylist ); ====== 
 +Waits for any character specified in <keylist>. 
 + 
 +  Return value: the key from the list that was pressed (converted to 
 +                uppercase if the key is a letter). 
 + 
 +Example: 
 + 
 +     c  =  WaitKeys( "ABC\r\x1b" ); 
 +     /* Waits for A,B,C,<Enter> or <Esc> */ 
 + 
 + 
 +====== void Input( char *buf, int len, int readmode ); ====== 
 +Asks for a string from the user. The string is stored in <buf>, and the 
 +user will not be allowed to enter more than <len> characters. 
 + 
 +     <readmode> :  INPUT_ALL      : All characters are allowed 
 +                   INPUT_UPFIRST  : First character of each word is 
 +                                    converted to uppercase. 
 +                   INPUT_UPALL    : All characters are converted to 
 +                                    uppercase. 
 +                   INPUT_DIGITS   : Only digits are accepted. 
 +                   INPUT_NOFIELD  : OR together with any of the previous 
 +                                    modes if you don't want an input- 
 +                                    field background to be displayed. 
 + 
 + 
 +====== bool Ask( bool default ); ====== 
 +Asks for a Yes or No response from the user. Pressing 'Y' returns TRUE 
 +and outputs "Yes". Pressing 'N' returns FALSE and sends "No" to the user. 
 +Pressing <Enter> returns <default>, and sends "Yes" or "No", depending on 
 +<default>. 
 + 
 + 
 +====== char PeekChar( void ); ====== 
 +Checks if a character is available in the input buffer, and returns that 
 +character if there is. 
 + 
 +  Return value:     0 if no character available 
 +                 != 0 the character read (key pressed by user) 
 + 
 + 
 + 
 +====== void SetColor( char color ); ====== 
 +Changes the current output color. All text that is output after this 
 +function is called will be displayed in the specified color.  This 
 +function does nothing when the user does not have ANSI or AVATAR enabled. 
 + 
 +<color> can be one of the following: 
 + 
 +     BLACK, RED, GREEN, YELLOW, MAGENTA, BLUE, CYAN, WHITE 
 + 
 + 
 +====== void SetfullColor( unsigned char color ); ====== 
 +Changes the current foreground & background color. The color code is an 
 +IBM-type screen color code. This function does nothing when the user does 
 +not have ANSI or AVATAR enabled. 
 + 
 +Some examples: 
 + 
 +     0x1E : Bright yellow on dark blue background. 
 +     0x87 : Blinking white on a black background. 
 + 
 + 
 +====== void GotoXY( int x, int y ); ====== 
 +Moves the cursor to position (x,y). The upper left corner of the screen 
 +is (1,1). This function does nothing when the user does not have ANSI or 
 +AVATAR enabled. 
 + 
 + 
 +====== void ClrEol(); ====== 
 +Clears from the current cursor position to the end of the line. This 
 +function does nothing when the user does not have ANSI or AVATAR enabled. 
 + 
 + 
 +====== void EnableStop( void ); ====== 
 +====== void DisableStop( void ); ======  
 +====== bool Stopped( void ); ====== 
 +Enables stopping of output by pressing 'S'. When enabled, a user can 
 +press 'S' to stop incoming text. When this happens, any string output 
 +function will immediately return to the caller, en the function Stopped() 
 +will return TRUE to indicate that the user requested to stop output. 
 + 
 +     EnableStop()       Enables this feature and sets the "stopped" 
 +                        status to FALSE . 
 +     DisableStop()      Disables the stop feature. 
 +     Stopped()          Returns the "stopped" flag (TRUE or FALSE). 
 + 
 + 
 +Example: 
 + 
 +     EnableStop(); 
 +     for ( i = 0;  i < 100;  i++ ) 
 +     { 
 +          printf( "...something..." ); 
 +          if ( Stopped() ) 
 +          { 
 +               break; 
 +          } 
 +     } 
 + 
 + 
 +====== char ShowHotkeyFile( char *filename, char *hotkeys ); ====== 
 +Shows the file <filename> to the user, and watches for incoming keys that 
 +are specified in <hotkeys>. If one of these keys is detected, the 
 +function stops output, and returns the hotkey. The "stop" feature will be 
 +enabled when sending the file. 
 + 
 +  Return value:    0 : File sent completely and no hotkeys pressed. 
 +                   1 : 'S' pressed (output stopped) 
 +                   2 : File not found 
 +                 !=2 : Hotkey detected 
 + 
 + 
 +====== char ShowHotkeyANSIFile( char *filename, char *hotkeys ); ====== 
 +This function is identical to ShowKotkeyFile(), except for the fact that 
 +no extension and path can be specified. Depending on the setting of the 
 +user, <filename>.ANS/ASC in the textfiles directory will be sent. If no 
 +.ANS file is found, it will try to send the .ASC file. If that fails too, 
 +2 will be returned. 
 + 
 +  Return value:    0 : File sent completely and no hotkeys pressed. 
 +                   1 : 'S' pressed (output stopped) 
 +                   2 : File not found 
 +                 !=2 : Hotkey detected 
 + 
 + 
 + 
 +====== void InitLineCounter( void ); ======  
 +====== bool LineCounter( void ); ====== 
 +These functions are used to support page pausing ("More Y/N").  Calling 
 +InitLineCounter() initializes the line counter to 0.  Every time you call 
 +LineCounter(), the line counter is incremented by one. If the counter 
 +reaches the screen length, the user will be asked if he wants to continue 
 +reading. If he selects "No", the LineCounter() function will return 
 +FALSE. 
 + 
 +Example: 
 + 
 +     InitLineCounter(); 
 +     for ( ; ; ) 
 +     { 
 +          printf( "...something...\n" ); 
 +          if ( ! LineCounter() ) 
 +          { 
 +               break; 
 +          } 
 +     } 
 + 
 + 
 +====== bool ExternalInput( void ); ====== 
 +Returns TRUE when the last character that was read through any of the 
 +input routings originated from the remote keyboard (ie. the sysop did not 
 +type it). 
 + 
 + 
 +====== int ReadUser( USER_REC *rec, int recnr ); ====== 
 +Reads user record number <recnr> (0-...) from the user file and stores it 
 +in <rec>. 
 + 
 +  Return value: -1 if record does not exist. 
 +                 0 if record is read ok. 
 + 
 + 
 +====== void WriteUser( USER_REC *rec ); ====== 
 +Writes user record <rec> to the user file.  The record number is stored 
 +in the USER_REC structure.  If you want to write a user record to a 
 +different position in the user file, you have to change the 'record' 
 +field in the USER_REC structure. 
 + 
 + 
 +====== bool SetUser( long recnr ); ====== 
 +Sets the internal ProBoard user record to record number <recnr>.  This 
 +function should ONLY be called from _LOGIN.PEX !! 
 + 
 +  Return value:  TRUE on success 
 +                FALSE on error 
 + 
 + 
 +====== char PlayMusic( char *filename, char *hotkeys ); ====== 
 +Plays a .MUS file. The file has to be located in the ProBoard system 
 +directory. Do not include a path and extension in <filename>. The music 
 +can be stopped if the sysop presses one of the keys specified in 
 +<hotkeys>.            ^^^^^ 
 + 
 +  Return value:  0   Music file played till the end 
 +                 1   Music file not found 
 +                 >1  The hotkey pressed by the SYSOP 
 +                                               ^^^^^ 
 + 
 + 
 +====== void PostInfo( char *filename ); ====== 
 +Does exactly the same as the POSTINFO statement in a .Q-A file.  No path 
 +and extension is allowed in <filename>. The file where the information 
 +will be written to will have the extension .ASW and will be placed in the 
 +ProBoard system directory. 
 + 
 + 
 +====== int ReadFileArea( int areanum, FILEAREA *fa ); ====== 
 +Reads information about file area number <areanum> in the <fa> structure. 
 + 
 +Check the file PB_SDK.H for details about the FILEAREA structure. 
 + 
 +  Return value:  -1   File area does not exist 
 +                  0   Ok 
 + 
 + 
 +====== void MenuFunction( int function, char *data ); ====== 
 +Executes menu function <function> with <data>. For details, see the menu 
 +functions description in this file. 
 + 
 +There are named constants declared for each function in the file 
 +PB_SDK.H. It is recommended that you use these constants instead of 
 +numbers. 
 + 
 + 
 +====== void Log( int loglevel, char *fmt, ... ); ====== 
 +With this function you can write information to the ProBoard logfile. The 
 +log entry will be written if the user has a loglevel that is greater than 
 +<loglevel> . 
 + 
 +<loglevel> can be one of the following: 
 + 
 +     LOG_FRIEND, LOG_NORMAL, LOG_SUSPICIOUS, LOG_DANGEROUS 
 + 
 +If you want a log entry to be written regardless of the user's loglevel, 
 +use LOG_FRIEND. 
 + 
 +The Log() function works like the printf function: you can use format 
 +specifiers in the <fmt> string, and pass extra parameters. 
 + 
 +Example:    
 +  Log(LOG_NORMAL,"User's name = %s",CurUser->name); 
 + 
 + 
 +====== void HangUp(); ====== 
 +Hangs up the phone, logging off the user. It is exactly the same as 
 +pressing Alt-H. 
 + 
 + 
 +====== bool CheckAccess( int level, long flags ); ====== 
 +Checks if the current user can access something that requires <level> and 
 +<flags>. Returns TRUE if the user has access, FALSE if not. 
 + 
 + 
 + 
 +====== KEY ScanKey( void ); ====== 
 +Checks the LOCAL keyboard for a key, and returns the scan code for that 
 +key. If no key is available, 0 will be returned. 
 + 
 +For a list of defined values for scan codes, check the file PB_SDK.H. 
 + 
 + 
 + 
 +====== bool GetFlag( long flags, char flagchar ); ====== 
 +====== void SetFlag( long flags, char flagchar ); ====== 
 +====== void ClearFlag( long flags, char flagchar ); ====== 
 +====== 
 +Access flags are stored in a long integer (32 bits). You have 3 macros at 
 +your disposal to manipulate access flags: 
 + 
 +     GetFlag   : Returns TRUE if flag <flagchar> is set 
 +     SetFlag   : Turns flag <flagchar> on 
 +     ClearFlag : Turns flag <flagchar> off 
 + 
 +<flagchar> must be a value from 1 to 32. 1-26 correspond to A-Z, while 27-32 are the same as 1-6. 
 + 
 + 
 +====== int ErrorLevel( void ); ====== 
 +Returns the errorlevel of the last executed shell command (Through 
 +MenuFunction(MENU_SHELL,...)) 
 + 
 + 
 +====== bool GetIniVar( char *fname, char *varname, char *value, int max ); ====== 
 +====== bool SetIniVar( char *fname, char *varname, char *value ); ====== 
 +These functions can be used to read and write to .INI files. These files 
 +are similar to the files used by MS Windows. They can be used to store 
 +settings for your application (PEX). An example of a .INI file: 
 + 
 +     DataPath = C:\PB\PEX\MYPEX\DATA 
 +     ProgPath = C:\PB\PEX\MYPEX 
 +     MaxUsers = 10 
 + 
 +This is a standard ASCII file, with each line in the form: 
 + 
 +     <varname> = <value> 
 + 
 +The value of a specific variable can be read by calling the function 
 +GetIniVar(). Setting a variable (writing to the .INI file or createing it 
 +if it doesn't exist yet) can be done by calling SetIniVar(). 
 + 
 +The parameters for the functions are: 
 + 
 +     <fname>      Name of the .INI file. The extension of the file will 
 +                  always be changed to .INI by ProBoard. 
 +     <varname>    Name of the variable (case INsensitive) 
 +     <value>      For GetIniVar() : a pointer to a buffer where the 
 +                                    variable's contents will be stored. 
 +                  For SetIniVar() : a pointer to the value of the 
 +                                    variable. 
 +     <max>        Maximum number of characters that can be copied in 
 +                  <value> (including trailing '\0') 
 + 
 + 
 +  Return value:  FALSE if the file could not be opened or the variable does not exist. 
 + 
 + 
 +====== void exit( void ); ====== 
 +Exits the current pex-program, and unloads it from memory. 
 + 
 + 
 +====== void ExitTSR( void ); ====== 
 +Exits the current pex-program, and leaves it resident. This has some 
 +important implications: 
 + 
 +  * All global and static variables keep their values for subsequent executions. 
 +  * When the same pex-file is run again through menu function 60, the resident copy will be executed. This will result in faster loading. 
 +  * Any handlers that were installed will be called. 
 + 
 + 
 +====== void InstallHandler( int handler, function ); ====== 
 +This is probably the most advanced and complicated function in the 
 +ProBoard SDK. With this function you can set up a "handler" for a 
 +specific action. Right now, only two types of handlers are supported: a 
 +replacement for the sysopkey-handler and a handler to intercept loss of 
 +carrier. This way you can create your own sysopkeys, or change the 
 +behaviour of existing sysopkeys. You could create a handler that 
 +intercepts the Alt-J key, and write your own flavor. In future versions 
 +you will be able to set up handlers for low-level I/O operations. So you 
 +could replace all I/O routines by your own functions. This way you can 
 +support your own exotic hardware or something like that. Anything goes! 
 + 
 +     handler   : Handler type. At this time, only HANDLER_SYSOPKEY and 
 +                 HANDLER_HANGUP are supported. 
 +     function  : A pointer to the handler function you created. 
 + 
 +You can install as many handlers as you want.  When the PEX is removed 
 +from memory (when the PEX exits), all handlers that were installed will 
 +be removed by ProBoard. 
 + 
 +The handler function is a function that returns an integer. The 
 +parameters depend on the type of handler you are creating. 
 + 
 +For HANDLER_SYSOPKEY the handler function has to be declared like this: 
 + 
 +     int sysopkeyhandler( KEY k ) 
 +     { 
 +          ... 
 +     } 
 + 
 +A sysopkey handler intercepts any special key that is pressed by the 
 +sysop. (like F1,Alt-H,...). You can redefine any key, or add your own. 
 + 
 + 
 +For HANDLER_HANGUP, the handler functions has to be declared like this: 
 + 
 +     int hanguphandler( void ) 
 +     { 
 +          ... 
 +     } 
 + 
 +The hangup handler works a little different: it is called whenever 
 +ProBoard exits (carrier lost, sysop hung up,...). It can be used to 
 +perform some cleanup for your running PEX file (like closing files, 
 +writing data, etc..). You can install the handler at the start of your 
 +program and remove it before the program is finished. 
 + 
 +If a handler function decides to do anything, it has to return HANDLED. 
 +If the handler wants to leave it up to ProBoard, it must return 
 +NOT_HANDLED. 
 + 
 +This asks for an example I suppose: 
 + 
 +     int keyhandler( KEY k ) 
 +     { 
 +          if ( k == KEY_ALTJ ) 
 +          { 
 +               printf( "\7\rHang on %s! I'm shelling to DOS...", 
 +                       UserFirstName ); 
 +               MenuFunction( MENU_SHELL, "*N*Q*X*!" ); 
 +               printf( "I'm back!!\n" ); 
 +               return HANDLED; 
 +          } 
 +          else 
 +          { 
 +               return NOT_HANDLED; 
 +          } 
 +     } 
 +     main( int   argc, 
 +           char *argv[] ) 
 +     { 
 +          InstallHandler( HANDLER_SYSOPKEY, keyhandler ); 
 +          ExitTSR();    /* IMPORTANT */ 
 +     } 
 + 
 +So what does it do?  It intercepts the sysopkey-function, and checks if 
 +the key pressed is Alt-J. If it is, it shells to DOS with swapping ON, 
 +and it writes its own messages to the screen.  When the sysop returns, 
 +the handler returns HANDLED to let ProBoard know that it does not have to 
 +process the key. You could use this example in an INIT.PEX file.  Is this 
 +powerful or what? 
 + 
 + 
 +====== void RemoveHandler( int handler, function ); ====== 
 +Removes handler number <handler> which has been installed by 
 +InstallHandler().  <function> is the pointer to the handler that should 
 +be removed. 
 + 
 + 
 +====== long MsgNum( int area, long id ) ====== 
 +Returns the message number for message 'id', in area 'area'.  For Hudson 
 +and *.MSG, this is identical to the message id (but DO NOT rely on 
 +that).  Returns a value < 1 if there is no message number for 'id'. 
 + 
 + 
 +====== long MsgId( int area, long n ) ====== 
 +Returns the message id for message number 'n', in area 'area'. For Hudson 
 +and *.MSG, this is identical to the message number (but DO NOT rely on 
 +that).  Returns a value < 1 if there is no message number 'n'. 
 + 
 + 
 +====== long HighMsg( int area ) ====== 
 +Returns the message id of the last message in the given area.  Note: if 
 +the lastread pointer is higher than what this function returns, DO NOT 
 +use FirstMessage()!  The FirstMessage() function does not support reading 
 +past the end of the area. (if you know what I mean :-) 
 + 
 + 
 +====== long NumMsgs( int area ) ====== 
 +Returns the total number of active messages in the given area. 
 + 
 + 
 +====== void LocalDisplay( bool showlocal ) ====== 
 +Enables/Disables local echo of text.  A parameter of TRUE means "enable 
 +local display".  FALSE means "disable local display". See _GRAPH.CPP for 
 +an example. 
 + 
 + 
 +====== void RemoteDisplay( bool showremote ) ====== 
 +Enables/Disables remote echo of text.  A parameter of TRUE means "enable 
 +remote display".  FALSE means "disable remote display".  See _GRAPH.CPP 
 +for an example. 
 + 
 + 
 +====== bool RIP() ====== 
 +  Returns  TRUE if RIP was detected and enabled.   
 +          FALSE if not... 
 + 
 + 
 +====== void ShowRIPscrip( char *name ) ====== 
 +This will send a RIP file located in the RIP directory.  No file 
 +extension should be given.  (.RIP is assumed)  The file will not be shown 
 +on the local screen. 
 + 
 + 
 +====== void ResetInactivity( void ) ====== 
 +Resets the internal inactivity timeout counter.  This function can be 
 +used when returning from a shell or after a time-consuming function has 
 +been called.  It will prevent the user from being logged off because of 
 +inactivity. 
 + 
 + 
 +====== bool AddTaggedFile( TAGGED_FILE *tag ) ====== 
 +Adds a file to the internal list of tagged files.   
 + 
 +  Returns  TRUE if the was successfully added. 
 +          FALSE if the file was already tagged. 
 + 
 + 
 +====== bool RemoveTaggedFile( TAGGED_FILE *tag ) ====== 
 +Removes a file from the internal list of tagged files.  Returns TRUE if 
 +the tagged file was found and deleted from the list, or FALSE if the 
 +tagged file was not in the list. 
 + 
 + 
 +====== void ClearTaggedFiles( void ) ====== 
 +Clears the internal list of tagged files (all tags are removed). 
 + 
 + 
 +====== bool IsTagged( TAGGED_FILE *tag ) ====== 
 +  Returns  TRUE if the given file is in the internal list of tagged files, 
 +          FALSE if not. 
 + 
 + 
 +====== int GetTaggedFiles( TAGGED_FILE *tagarray, int maxitems ) ====== 
 +Fills the given array <tagarray> with all the files in the internal list 
 +of tagged files (up to a maximum of <maxitems>).  This function returns 
 +the number of tagged files copied to the array <tagarray> (<= maxitems). 
 + 
 + 
 +====== bool PutTaggedFiles( TAGGED_FILE *tagarray, int nitems ) ====== 
 +Fills the internal list of tagged files with the files in the given array 
 +<tagarray>. <nitems> is the number of items in the array.   
 + 
 +  Returns  TRUE on success 
 +          FALSE on error 
 + 
 + 
 +====== Global ProBoard Variables ====== 
 +You have access to some important ProBoard system variables through 
 +global variables defined in PB_SDK.H. 
 + 
 + 
 +====== word PBVersion; ====== 
 +The version number of ProBoard. The high byte is the major version number 
 +(eg. 1). The low byte is the minor version number in hex (eg. 0x30). So 
 +if you're using ProBoard v1.30, PBVersion will be set to 0x0130 . 
 + 
 + 
 +====== word Beta; ====== 
 +The beta version number of ProBoard. If this number is 0xFFFF, it means 
 +that the release version is running. Beta numbers start from 1. 
 + 
 +For example, when running ProBoard 1.40 Beta/19, PBVersion will be set to 
 +0x0140, and Beta will be set to 19. 
 + 
 + 
 +====== long BaudRate ====== 
 +The current bps rate of the caller. 0 means local. 
 + 
 + 
 +====== USER_REC *CurUser; ====== 
 +Pointer to the current user record. You can change any of the field 
 +values in the record, but this will not result in any immediate action by 
 +ProBoard. For example, if you change the user's level, ProBoard will not 
 +know that you changed it, so you will have to tell it by calling 
 +AdjustTime(); 
 + 
 +Check the file PB_SDK.H for a description of the USER_REC structure. 
 + 
 + 
 +====== int UserRecNr; ====== 
 +The record number of the current user's record in the file USERS.BBS, 
 +starting from 0. This value cannot be changed. 
 + 
 + 
 +====== int NumLimits; ====== 
 +The number of user levels defined in ProCFG. You can access the 
 +limit-values through the global array 'Limits'.  This value cannot be 
 +changed. 
 + 
 + 
 +====== LIMIT *Limits; ====== 
 +Is an array of all user levels defined, with download and time limits. 
 +Check the file PB_SDK.H for information on the LIMIT structure. 
 + 
 +You are not allowed to change any values! (A good compiler should 
 +generate an error or warning if you try to do so) 
 + 
 + 
 +====== char *LoginDate; ====== 
 +====== char *LoginTime; ====== 
 +This is the login date & time of the current user. 
 + 
 +     LoginDate[0] : Day portion of login date 
 +     LoginDate[1] : Month portion of login date 
 +     LoginDate[2] : Year portion of login date (00-99) 
 +     LoginTime[0] : Hour portion of login time 
 +     LoginTime[1] : Minute portion of login time 
 +     LoginTime[2] : Second portion of login time 
 + 
 + 
 +====== bool NetEntered; ====== 
 +====== bool EchoEntered; ====== 
 +These READ-ONLY variables tell you if netmail and/or echomail has been 
 +entered during this session. 
 + 
 + 
 +====== int NumUsers; ====== 
 +This READ-ONLY variable is the number of users currently available in the 
 +file USERS.BBS. 
 + 
 + 
 +====== int NodeNumber; ====== 
 +This READ-ONLY variable is the current node number. 
 + 
 + 
 +====== char *CurMenu; ====== 
 +====== char *UserFirstname; ====== 
 +====== char *PrevUser; ====== 
 +====== char *StartupPath; ====== 
 +====== char *SysPath; ====== 
 +====== char *PageReason; ====== 
 +  CurMenu       : Current menu name 
 +  UserFirstName : First name of current user 
 +  PrevUser      : Name of previous user 
 +  StartupPath   : Name of the directory where ProBoard was started from 
 +                  (with trailing '\') 
 +  SysPath       : Name of the ProBoard system directory (with trailing '\') 
 +  PageReason    : Reason for paging the sysop (as entered by the user) 
 + 
 +These are READ-ONLY strings! (except PageReason) 
 + 
 + 
 +====== word *PageCount; ====== 
 +POINTER to the number of sysop pages done by the user.  This value can be 
 +changed by changing the unsigned integer pointed to by 'PageCount'. 
 + 
 + 
 +====== CONFIG *Config; ====== 
 +A pointer to the current ProBoard configuration structure. See the file 
 +PB_SDK.H for a description of the CONFIG structure. 
 + 
 + 
 +====== Special-purpose PEX-files ====== 
 +Several pex-files will be loaded automatically (if present). They perform 
 +certain actions like edit a message, set up handlers, etc. 
 + 
 +     INIT.PEX      : Will be loaded and executed before any I/O has been 
 +                     done.  Use this to set up any handlers (sysopkey 
 +                     handlers, ...) 
 +     INIT_1.PEX - 
 +     INIT_9.PEX    : Is the same as INIT.PEX, but will be loaded in the 
 +                     order of the numbers. So you can have up to 10 
 +                     initialization pex-files. 
 +     _LOGIN.PEX    : Is run instead of the normal login procedure.  See 
 +                     the section explaining this PEX for more information 
 +     LOGIN.PEX     : No longer supported! 
 +     BIRTHDAY.PEX  : Is run after showing NEWS.ANS/ASC if today is the 
 +                     user's birthday. 
 +     NEWUSER.PEX   : Is run before the file NEWUSER.A?? is shown. 
 +     NEWUSER1.PEX  : Is run before the file NEWUSER1.A?? is shown. 
 +     NEWUSER2.PEX  : Is run before the file NEWUSER2.ANS/ASC is shown. 
 +     WELCOME.PEX   : Is run before the file WELCOME.ANS/ASC is shown 
 +     WELCOMEx.PEX  : Is run before the file WELCOMEx.ANS/ASC is shown 
 +                     (x = 1 to 9) 
 +     SECxx.PEX     : Executed when a user with security level xx logs in. 
 +                     Is run before SECxx.ANS/ASC is shown. 
 +     EXPIRED.PEX   : Is run before EXPIRED.ANS/ASC is shown, and after a 
 +                     user's level is lowered because the subscription 
 +                     date was reached. ProBoard will send one parameter 
 +                     to this PEX: the original level, before it was 
 +                     changed by ProBoard. 
 +     GOODBYE.PEX   : Is run before GOODBYE.ANS is displayed. 
 +     GOODBYE2.PEX  : Is run after GOODBYE.ANS is displayed. 
 +     MSGED.PEX     : Is a replacement of the built-in message editor.  It 
 +                     will be executed with no parameters. The message 
 +                     that you create has to be written to a file called 
 +                     MSGTMP.  ProBoard will then read this file and 
 +                     create a message from it. To let ProBoard know that 
 +                     the user has aborted a message, delete MSGTMP. 
 +     FSED.PEX      : Is similar to MSGED.PEX, but will be executed if the 
 +                     user has selected the fullsrceen editor. It works 
 +                     the same way as MSGED.PEX, but ProBoard will create 
 +                     a MSGTMP file with the original message if a user is 
 +                     replying to a message. 
 + 
 + 
 +====== Using the _LOGIN PEX ====== 
 +By writing a _LOGIN.PEX, ProBoard allows you to replace the normal login 
 +procedure (not including the new user procedure) with your own.  It is 
 +the PEX's responsibility to check for validity of the name entered and to 
 +do password checking! 
 + 
 +Once you determined the record number of the user, you have to call the 
 +function SetUser() with the record number as parameter, and exit the PEX 
 +immediately. 
 + 
 +If the user is not in the user database yet, you should exit without 
 +calling SetUser(), and set the name that was entered by the user in a 
 +memory region supplied by ProBoard to your PEX as the only parameter. 
 +This parameter is a 'dword' in decimal form, so you have to convert it to 
 +a pointer using the following procedure: 
 + 
 +     /*----------------------------*/ 
 +     char  *pName; 
 +     dword  dwName = 0; 
 +     char  *s; 
 +     for ( s  =  argv[ 1 ];  *s;  s++ ) 
 +     { 
 +          dwName  =  l_mul( dwName, 10L )  +  (dword) ( *s - '0' ); 
 +     } 
 +     pName  =  (char *) dwName; 
 +     /*----------------------------*/ 
 + 
proboard_interface_functions.1687217050.txt.gz · Last modified: 2023/06/20 07:24 by admin

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki