BBS in a Box 3/BBS in a box - Trilogy III.iso/Files/Tele/Hermes/Hermes Toolbox 1.0.1 ƒ/HermesToolboxIntf.p

Text File | 1993-10-28 | 47.0 KB | 721 lines | [TEXT/PJMM]

{-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-}
{This unit is the interface file for the Hermes Toolbox library by Chris Owen}
{The Hermes Toolbox extends the number of procedures and functions that}
{are available when writing externals.  This library is constantly being }
{updated and the most recent version can always be found on Mulligan's Valley}
{at 203-772-4485 or by contacting the author at [e-mail]}
{-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-}

{Last modified for Hermes II version 1.0 on 9/27/93}
{Version 1.0}

unit HermesToolboxIntf;

interface

    uses
        HermHeaders, MiscIntf;

    type

{For GetQDGlobals, CenterDialog and DoRegistrationDialog}
        QDGlobalRecPtr = ^QDGlobalRec;
        QDGlobalRec = record
                randSeed: Longint;
                screenBits: BitMap;
                arrow: Cursor;
                dkGray: Pattern;
                ltGray: Pattern;
                gray: Pattern;
                black: Pattern;
                white: Pattern;
                thePort: GrafPtr;
            end;


{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}
{----------------------------- Hermes Display Functions ------------------------------}
{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}


    procedure DoCR (numLines: integer; HermSetup: UserXIPtr);
{-----------------------------------------------------------------------------------}
{This procedure will move the cursor down the number of line specified in numLines.  This is}
{just like bCR but you don't have to repeat it so many times and clog up your code.}
{-----------------------------------------------------------------------------------}

    procedure Write (theString: str255; HermSetup: UserXIPtr);
{-----------------------------------------------------------------------------------}
{This procedure will simply output theString to the screen.  It uses the built in command in}
{Hermes but I think this is an easier format to call it from.  It uses the current text color.}
{Write will not begin on a new line but start where the last write left off.}
{-----------------------------------------------------------------------------------}

    procedure Writeln (theString: str255; HermSetup: UserXIPtr);
{-----------------------------------------------------------------------------------}
{This procedure will simply output theString to the screen.  It uses the built in command in}
{Hermes but I think this is an easier format to call it from.  It uses the current text color.}
{Writeln will  begin on a new line.}
{-----------------------------------------------------------------------------------}

    procedure WriteANSI (theString: str255; where: point; color: integer; HermSetup: UserXIPtr);
{-----------------------------------------------------------------------------------}
{WriteANSI will output theString begining at where and in the color specified by color.}
{-----------------------------------------------------------------------------------}

    function ListTextRsrc (textID: integer; HermSetup: UserXIPtr): boolean;
{-----------------------------------------------------------------------------------}
{This function willl output to the screen a TEXT resource of number textID.  If the resouce}
{can not be found this returns false.  You must exit the current stage immeadiately after}
{this procedure in order for it to display the text.}
{-----------------------------------------------------------------------------------}

    function ListTextFile (filePath: str255; insertPath: boolean; HermSetup: UserXIPtr): boolean;
{-----------------------------------------------------------------------------------}
{This function is mostly to make life a little easier.  Given the path to a file filepath it will}
{output the contents to the screen.  If insertPath is true Hermes will add the path you pass}
{to the path to the Hermes Files folder (ie. you can just pass 'Externals:A textfile'),}
{otherwise it will use filePath as is. If the file isn't found this function will return false. You}
{must exit the current stage immeadiately after this procedure in order for it to display the}
{text.}
{-----------------------------------------------------------------------------------}

    procedure Pause (HermSetup: UserXIPtr);
{-----------------------------------------------------------------------------------}
{This procedure will pause the screen until the user hits a key.  It using the built in pause}
{string in Hermes, so whatever the sysop has customized that to will be used.  This}
{procedure must be just before exiting a stage of your external.  Set the stage to where}
{you want to go after the pause, call this and exit the current stage}
{-----------------------------------------------------------------------------------}

    procedure ClearScreen (HermSetup: UserXIPtr);
{-----------------------------------------------------------------------------------}
{This procedure will clear the users screen.}
{-----------------------------------------------------------------------------------}

    procedure Beep (HermSetup: UserXIPtr);
{-----------------------------------------------------------------------------------}
{This procedure will cause the remote users computer to beep (or flash the menu bar if they}
{have the sound set to 0)}
{-----------------------------------------------------------------------------------}

{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}
{----------------------------- File Manipulation Functions -----------------------------}
{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}


    function FileExists (filePath: str255; var OSResult: OSErr): boolean;
{-----------------------------------------------------------------------------------}
{Given filePath this function will return whether the specified file actually exists.  It also}
{returns the reason for any error in OSResult}
{-----------------------------------------------------------------------------------}

    function CreateFile (pathName: string; var theVRefNum: Integer; var theDirID: Integer): OSErr;
{-----------------------------------------------------------------------------------}
{This is a cool one. This function will create a new file with the path pathName.  The cool part}
{is that it will create all the folders along the way. If the path name ends with a : then only}
{the folders will be created.  If you need to start part way down the path you can pass a}
{VRefNum to theVRefNum and a file name or partial path name to thePath.  The function will}
{return the VRefNum and dirID of the file which is created.  If you are using a full path name}
{you MUST pass 0 (zero) for theVRefNum and theDirID.  This is the perfect way to create}
{preference files.  If they don't exist already you can create the whole subdirectory}
{necessary to create them.}
{-----------------------------------------------------------------------------------}

    procedure WriteFile (theString: str255; fileRefNum: integer; var OSResult: OSErr);
{-----------------------------------------------------------------------------------}
{WriteFile with write theString to the current location in the file specified by fileRefNum.}
{It will return any error in OSResult.  WriteFile does not add a return to the end of the string}
{-----------------------------------------------------------------------------------}

    procedure WritelnFile (theString: str255; fileRefNum: integer; var OSResult: OSErr);
{-----------------------------------------------------------------------------------}
{WritelnFile with write theString to the current location in the file specified by fileRefNum.}
{It will return any error in OSResult.  WriteFile will add a return at the end of the string so}
{that the next string will begin on a new line.}
{-----------------------------------------------------------------------------------}

    function TouchFolder (folderPath: str255): OSErr;
{-----------------------------------------------------------------------------------}
{This procedure will chage the last modified date of a folder to the current time and date.}
{This is often useful because it forces the Finder to update all the files in that folder.  Pass}
{it the path to the folder you want to change and it will return any error.}
{-----------------------------------------------------------------------------------}

    procedure FlushAllVolumes;
{-----------------------------------------------------------------------------------}
{This procdure will cause all mounted volumes to be immeadiately flushed.  All changes that}
{have been made to files will be written to disk.  This is important because the mac doesn't}
{write to disk until the buffer is full.  If you want to do something especially dangerous or}
{something like shutdown the machine it might be a good idea to call this first.  This will}
{cause a momentary pause in the action if there is lots to be written but no worse than the}
{many pauses that take place when writting something to disk.}
{-----------------------------------------------------------------------------------}

    function Readln (refNum: integer; endOfLine: char): str255;
{-----------------------------------------------------------------------------------}
{This function will let you read from a text file.  It is intended to return a single line so it is}
{limited to a returning a string.  refNum is the refNum of the already opened file you want to}
{read from.  endOfLine is the character which ends a line (normally a return). It will return}
{the line as a string and will return a empty string if there is an error. This might be useful}
{if you want to read the BBS list file that Hermes creates.}
{-----------------------------------------------------------------------------------}

    procedure ReadText (refNum: integer; data: Handle; endOfLine: char);
{-----------------------------------------------------------------------------------}
{This function is useful if you need to read something larger than a string.  Like Readln you}
{need to pass it a refNum for the open file and the endOfLine character which marks the end}
{of the data you want to read.  With this procedure you must also pass a valid handle to hold}
{the data which is read.  The handle you pass will be resized to the size of the data and will}
{be nil if there is an error.}
{-----------------------------------------------------------------------------------}

    function DiskSpaceAvail (volToTest: str255): longInt;
{-----------------------------------------------------------------------------------}
{Given a volume name volToTest this function will return the total amount of free disk space}
{on that volume.}
{-----------------------------------------------------------------------------------}

    function CopyFile (source, destination: str255; deleteOriginal: boolean): OSErr;
{-----------------------------------------------------------------------------------}
{CopyFile will copy both the data and resource fork of a file on the path source to the file}
{specified by the path destination.  If true, deleteOriginal will cause the source file to be}
{erased only if the copy was successful.  Any error will be returned in OSErr.}
{-----------------------------------------------------------------------------------}

    function GetVolRefNum (thePath: str255): integer;
{-----------------------------------------------------------------------------------}
{Given thePath this function will return the volume reference number of the directory pointed}
{to by that path.  Since pathnames are used so frequently in Hermes you will need this for}
{many of the mac toolbox calls}
{-----------------------------------------------------------------------------------}

    function GetPathName (volRefNum: longInt): Str255;
{-----------------------------------------------------------------------------------}
{Given a volume reference number this function will return a path name for that directory.}
{This is useful for converting the result of many of the mac toolbox calls to strings for }
{Hermes}
{-----------------------------------------------------------------------------------}

    function GetSystemPath: str255;
{-----------------------------------------------------------------------------------}
{This function returns a pathname to the current system folder.  Good for finding the }
{preference folder or things like Stuffit Engine.}
{-----------------------------------------------------------------------------------}

    function DirectoryList (pathtoDir: str255; numtypes: integer; typelist: SFTypelist; var numFiles: integer; HermSetup: UserXIPtr): OSErr;
{-----------------------------------------------------------------------------------}
{This function will write out a list of files in the directory pointed to by pathToDir.  If}
{numTypes is between 1 and 4 it will only list those files which are listed in typeList.  If}
{numTypes is between -1 and -4 it will only list those files in typeList but will also list all}
{folders. Folders are signified by a colon (:) after their name.  If numTypes is greater than}
{4 it will list all files without listing folders.  If it is less than -4 it will list all files and}
{folders in the directory. *Remember that SFTypeList arrays are 0-3 not 1-4* }
{-----------------------------------------------------------------------------------}

{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}
{--------------------------- Resource Manipulation Functions --------------------------}
{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}


    function GetHRMS: eInfoRec;
{-----------------------------------------------------------------------------------}
{This function will get the current externals restriction information that Hermes uses to}
{limit access to the external.  This is useful if you use a main menu command and want to}
{limit that commands use to users who would have access to the external from the }
{external menu.}
{-----------------------------------------------------------------------------------}

    procedure SetHRMS (HRMSInfo: eInfoRec);
{-----------------------------------------------------------------------------------}
{This procedure will save the restriction information that Hermes uses to limit access to an}
{external.  No errors are reported but this should be a generally safe procedure.}
{-----------------------------------------------------------------------------------}

    function GetRegistration (var bbsName: str255; var registrationNum: longInt; resourceName: resType): boolean;
{-----------------------------------------------------------------------------------}
{This function will let you get saved registration information.  It will retrieve the registration}
{information in bbsName and registration number.  You must pass the resourceName that you}
{previously used to save the information.  See SetRegistration for details.  It will return true}
{if it found the resource and false if it did not.  If it did not find the resource you can create a}
{new one by calling SetRegistration. }
{-----------------------------------------------------------------------------------}

    procedure SetRegistration (bbsName: str255; registrationNum: longInt; resourceName: resType);
{-----------------------------------------------------------------------------------}
{This procedure will let you save registration information in your external's resource fork.}
{Pass it the bbsName and registrationNum you want to save.  You also need to pass a}
{resource type name.  This is simply 4 letters (ie HRMS).  Each external you write should have}
{its own type though to avoid possible conflicts.  Use the same type you use here as in}
{GetRegistration.  You should define a constant in your headers that is something like }
{regResource = 'REGI' and use that each time.}
{-----------------------------------------------------------------------------------}

    function CheckRegistration (bbsName: str255; registrationNum: longInt; regNum1, regNum2: longint): boolean;
{-----------------------------------------------------------------------------------}
{This procedure will check a registration number for a given BBS name.  It returns true if the}
{registration number is valid and false if it is invalid.  This relies on regNum1 and regNum2 }
{regNum1 should be a 6 digit number and regNum2 should be a 3 digit number.  These numbers}
{should be changed for each external.  You must use the same numbers that you used when you}
{created the number with CreateRegistration though.}
{-----------------------------------------------------------------------------------}

    function CreateRegistration (bbsName: str255; regNum1, regNum2: longint): longint;
{-----------------------------------------------------------------------------------}
{This procedure will return a registration number for the bbsName you pass it.  It also relies}
{on regNum1 and regNum2 (see above).  You can use this is a small application or external}
{that creates registration numbers.  You should define these two numbers as constants and}
{use the same ones to create and then check registration numbers.}
{-----------------------------------------------------------------------------------}

{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}
{------------------------------ Sysop External Functions -----------------------------}
{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}


    function GetCheck (theDialog: dialogPtr; itemNum: integer): boolean;
{-----------------------------------------------------------------------------------}
{Given a dialog pointer theDialog and an item in that dialog, this function will return the }
{current state of the item.  This is for reading check boxes and radio buttons in sysop}
{externals.  Writing this as a function makes it generally easier to use. True is on and }
{false is off.}
{-----------------------------------------------------------------------------------}

    procedure SetCheck (theDialog: dialogPtr; itemNum: integer; on: boolean);
{-----------------------------------------------------------------------------------}
{Given a dialog pointer theDialog and an item in that dialog, this function will set the }
{current state of the item to the value of on (true is on and false is off).  This is for setting}
{check boxes and radio buttons in sysop externals.  Writing this as a function makes it }
{generally easier to use. True is on and false is off.}
{-----------------------------------------------------------------------------------}

    function GetEditText (theDialog: DialogPtr; itemNum: integer): str255;
{-----------------------------------------------------------------------------------}
{Given a dialog pointer theDialog and an item in that dialog, this function will return the }
{current value an edit text item.  This is for reading edit text fields in sysop externals.}
{Writing this as a function makes it generally easier to use}
{-----------------------------------------------------------------------------------}

    procedure SetEditText (theDialog: DialogPtr; itemNum: integer; ETString: str255);
{-----------------------------------------------------------------------------------}
{Given a dialog pointer theDialog and an item in that dialog, this function will set the }
{current value of the edit text item to ETString.  This is for setting edit text fields in }
{sysop externals.  Writing this as a function makes it generally easier to use. }
{-----------------------------------------------------------------------------------}

    procedure CenterDialog (theDialog: DialogPtr);
{-----------------------------------------------------------------------------------}
{This procedure takes a dialog (or window) pointer (which you would get from GetNewDialog)}
{and centers it on the screen.  You should make your dialog 'initially invisable' and call this}
{procedure BEFORE calling ShowWindow.  Otherwise the user will see the dialog move across}
{the screen.}
{-----------------------------------------------------------------------------------}

    function DoRegistrationDialog (var bbsName: str255; var registrationNum: longInt): boolean;
{-----------------------------------------------------------------------------------}
{This function will put up a small dialog that will allow the sysop to enter basic registration}
{information.  The dialog has two items, one for a BBS name and one for a registration}
{number.  The function stores these two values in bbsName and registrationNum.  The dialog}
{also has two buttons, one for OK and one for cancel.  The function will return true if the OK}
{buttun is hit and false if cancel is hit.  Note that this dialog is modal so it will stop other}
{action on the BBS, but this isn't really a problem since the sysop will  use it rarely. If you}
{use this function you MUST include all the resources included in the file with the same name}
{as this function.  Use ResEdit to copy them to your external's resource file.}
{-----------------------------------------------------------------------------------}

    procedure DoTimeDialog (var hour, minute: integer);
{-----------------------------------------------------------------------------------}
{This procedure puts up a dialog similar to that which Hermes uses to enter the time for node}
{start and end time.  It gives the sysop the opportunity to enter time in a manner similar to}
{that used by the Alarm Clock DA and General control panel.  It returns the hour and minute}
{that the sysop entered.  The hour is in 24 hour format so 0 is midnight and 23 is 11 pm.}
{Note that this dialog is modal so it will stop other action on the BBS, but this isn't really a}
{problem since the sysop will  use it rarely. If you use this function you MUST include all}
{the resources included in the file with the same name as this function.  Use ResEdit to copy}
{them to your external's resource file.  There is a text item in this dialog which can be used}
{to prompt the user.  You can either change it with ResEdit or call ParamText and set string}
{number 0 to what you want displayed in that item.}
{-----------------------------------------------------------------------------------}


{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}
{----------------------------- Process Manager Functions ----------------------------}
{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}


    function HermesToFront (var oldProcess: ProcessSerialNumber): OSErr;
{-----------------------------------------------------------------------------------}
{This function will make Hermes the front most application.  It returns the process serial}
{number of the application which had been in from in oldProcess.  This is a really rude and}
{not very mac-like thing to do but there are times when it is handy.}
{THIS REQUIRES SYSTEM 7.0 OR LATER - Use System7OrLater below to check.}
{-----------------------------------------------------------------------------------}

    function HermesToBack (theProcess: ProcessSerialNumber): OSErr;
{-----------------------------------------------------------------------------------}
{This function will return Hermes to the background after a call to HermesToFront.  You}
{should store the value of oldProcess returned by that function in order to return the old}
{process to the front.}
{THIS REQUIRES SYSTEM 7.0 OR LATER - Use System7OrLater below to check.}
{-----------------------------------------------------------------------------------}

    procedure ShutDownMac;
{-----------------------------------------------------------------------------------}
{This procedure will shut the macintosh down and turn off the power on most newer macs.}
{It gives no warning and does not save open documents so it should be used sparingly.}
{-----------------------------------------------------------------------------------}

    procedure RestartMac;
{-----------------------------------------------------------------------------------}
{This procedure will restart the macintosh.  It gives no warning and does not save open }
{documents so it should be used sparingly.}
{-----------------------------------------------------------------------------------}

{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}
{----------------------------------- User Functions ----------------------------------}
{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}

    function FindUserOnline (userNum: integer; var node: integer; HermSetup: UserXIPtr): boolean;
{-----------------------------------------------------------------------------------}
{This function will return true if the user specified  by userNum  is online.  If true then the}
{node that user is on will be returned in node.}
{-----------------------------------------------------------------------------------}

    function NewUserAccount (var newUser: UserRec; HermSetup: UserXIPtr): OSErr;
{-----------------------------------------------------------------------------------}
{This function will create a new user on the BBS.  You can pass a full user record or use}
{WriteUser to flesh it out later.  The new user's user number will be passed back in}
{newUser.userNum.}
{-----------------------------------------------------------------------------------}

    function DeleteUser (userNum: integer; sysopNote: str255; HermSetup: UserXIPtr): OSErr;
{-----------------------------------------------------------------------------------}
{This function will delete the user specified by userNum from the Hermes user list.  Deleted}
{users will have a '•' added to the end of their name.  Optionally you can add a string of up}
{to 40 characters in sysopNote and this function will change the current sysopNote to that}
{string.  This might be usefull to keep track of why the user was deleted.}
{-----------------------------------------------------------------------------------}

    function WriteUser (user: UserRec; HermSetup: UserXIPtr): OSErr;
{-----------------------------------------------------------------------------------}
{This function will save the user info contained in UserRec.  It will return any error in writing}
{the info to the HermShared file.  The user info will be written to the account number}
{contained in user.UserNum so if you want to swap user info you need to reset that number.}
{You can change anything in a users record by using the Hermes function 'FindUser' to get}
{a user record, make the necessary changes and then call this function.}
{-----------------------------------------------------------------------------------}

    function CheckSub (forumNum, subNum: integer; user: UserRec; HermSetup: UserXIPtr): boolean;
{-----------------------------------------------------------------------------------}
{This function will check whether user has access to the the message base specified by}
{forumNum and subNum.  It returns true if the user does have access.  This funciton will}
{take into consideration if the user has access the forum and if they have the proper security}
{level, restriction and age.}
{-----------------------------------------------------------------------------------}

{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}
{---------------------------------- Stuffit Functions ---------------------------------}
{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}

    function StuffitExists: boolean;
{-----------------------------------------------------------------------------------}
{This function will check for the existence of the Stuffit Engine.  The Stuffit Engine is}
{supposed to be kept in the Extensions folder inside the System Folder.  It returns true if the}
{Engine is found and false if not.  Most of the other Stuffit Functions call this one but you}
{should still check before using any of them so you can report back to the user.}
{-----------------------------------------------------------------------------------}

    function StuffFile (source, destination: str255; deleteOriginal: boolean): OSErr;
{-----------------------------------------------------------------------------------}
{This function will compress a single file using the Stuffit Engine which is part of the Stuffit}
{Deluxe package.  You should pass the path to the file to be compressed in source and where}
{you want the archive to be placed in destination.  If deleteOriginal is true then the file will}
{be deleted after it has been compressed.   This function does not add .sit to the end of the}
{file name so if you are putting the new archive in the same directory you will need to add}
{it yourself in the destination name.  The fuction returns any OSErr that might take place}
{and returns -1 if the user cancels the operation by hitting the stop button in the Stuffit}
{Engine dialog.  Although this function calls StuffitExists you should before calling it in order}
{to report any errors to the user.}
{-----------------------------------------------------------------------------------}

{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}
{--------------------------------- Debugging Functions -------------------------------}
{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}

    function ParseError (theErr: OSErr; HermSetup: UserXIPtr): str255;
{-----------------------------------------------------------------------------------}
{This function will allow you to translate theErr into a string. It assumes that you have}
{already checked to make sure there actually is an error so you should not call it with error}
{0.}
{-----------------------------------------------------------------------------------}

    procedure ReportError (theErr: OSErr; user, log: boolean; HermSetup: UserXIPtr);
{-----------------------------------------------------------------------------------}
{This procedure will translate theErr into a string which can be reported to the user or sysop.}
{If user is true it will print the error string out to the current node.  If log is true it will}
{write the error string to the daily log.  This procedure DOES check the error so you can}
{call it each time you do something that might cause an error and it will not do anything}
{unless the error is other than 0.}
{-----------------------------------------------------------------------------------}

    procedure LogIt (outStr: str255; HermSetup: UserXIPtr);
{-----------------------------------------------------------------------------------}
{This is identical to the LogThis function in Hermes but works even if a user isn't online.  With}
{the built-in function if a users isn't on the current node when you log something to the daily}
{log, it isn't actually written until a user logs on (and then off) that node.  In the meantime}
{lots of people may have logged on to other nodes and your entry will be way out of order.}
{This writes directly to the 'Today Log' file.  You should still use the other procedure if a}
{user is online when you are writing to the log, but use this one when writing to the log}
{from the idle loop.}
{-----------------------------------------------------------------------------------}

    function OpenDebugFile (HermSetup: UserXIPtr): integer;
{-----------------------------------------------------------------------------------}
{This function is just intended to make setting up a debugging file a little easier.  Calling it}
{will open (or create) a file calle "Debug File" inside your Hermes Files folder.  It also stamps}
{the time and date when it was opened to the file.  It returns a integer which is the file}
{reference number or 0 if it wasn't able to open the file.  Save this number in your privates}
{so you can write to the file and later to close it.}
{-----------------------------------------------------------------------------------}

    procedure WriteDebugFile (theString: str255; debugRefNum: integer);
{-----------------------------------------------------------------------------------}
{Once again this is to simplify the logging of errors.  Pass it the refNum created by your}
{call to "Open DebugFile" along with the string you want recorded and it will write it to the}
{Debug file.  A return is automatically added to the end of the string.  There is no error}
{checking here but for just testing that is probably preferable.}
{-----------------------------------------------------------------------------------}

    procedure CloseDebugFile (debugRefNum: integer);
{-----------------------------------------------------------------------------------}
{This procedure will close the file created by "OpenDebugFile".  Pass it the refNum created}
{by that procedure.}
{-----------------------------------------------------------------------------------}

    procedure DebugString (theStr: str255; waitForReply: boolean);
{-----------------------------------------------------------------------------------}
{This procedure is great for debugging.  It requires that you have an freeware application}
{called "Debug Window".  Pass a debugging string in theStr and this will send an AppleEvent}
{to Debug Window that will log that string to the text window of "Debug Window".  This does}
{not add a return to the end of the string but Debug Window has an option to automatically add}
{them to each string that is sent.  The waitForReply variable determines whether it should}
{wait for Debug Window to reply.  If true it will wait (up to 5 seconds) for a reply.  The}
{advantage of waiting for a reply is that strings appear in the Debug Window one at a time}
{as they are sent out.  That way you can watch both the Hermes window and Debug Window}
{and see your debugging strings at the same time that event is taking place in Hermes.  If you}
{don't wait for a reply the stings will tend to bunch up and it won't always be apparent at}
{what stage they generated in Hermes.  The disadvantage to waiting for a reply is that it}
{slows Hermes down some.  Since you will only use this for debugging this is probably}
{acceptable but you have the option to no wait.  This procedure requires System 7 of course.}
{***Note*** As with all debugging procedures, don't forget to take these out before you}
{ship your external.  You can't tell its there but you don't want it there in your finished}
{external.}
{-----------------------------------------------------------------------------------}

    procedure DebugTimestamp (waitForReply: boolean);
{-----------------------------------------------------------------------------------}
{This procedure will cause Debug Window to stamp the time and date in the Debug Window.}
{See DebugString for details.}
{-----------------------------------------------------------------------------------}

    procedure DebugClearWindow (waitForReply: boolean);
{-----------------------------------------------------------------------------------}
{This procedure will clear the window in Debug Window.  See DebugString for details.}
{-----------------------------------------------------------------------------------}


{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}
{--------------------------------- String Functions ----------------------------------}
{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}

    function GetAString (stringGroup, stringNum: integer; addSpaceAtEnd: boolean): str255;
{-----------------------------------------------------------------------------------}
{Get a string from str# resource.  stringGroup is str# resource number and stringNum is}
{number of individual string in that resource.  addSpaceAtEnd will add a single space at end}
{of string if true.  This is useful when getting strings for prompts.}
{-----------------------------------------------------------------------------------}

    function SetAString (stringGroup, stringNum: integer; newStr: Str255): OSErr;
{-----------------------------------------------------------------------------------}
{Write a string to a str# resource.  stringGroup is str# resource number and stringNum is}
{number of individual string in that resource. newStr is the string to be saved. Function}
{returns OSErr}
{-----------------------------------------------------------------------------------}

    function SetSizeRight (theString: str255; size: integer): str255;
{-----------------------------------------------------------------------------------}
{Make a string a standard width.  theString is either truncated or spaces are added from}
{the left to make the returned string length of size.}
{-----------------------------------------------------------------------------------}

    function SetSizeLeft (theString: str255; size: integer): str255;
{-----------------------------------------------------------------------------------}
{Make a string a standard width.  theString is either truncated or spaces are added from}
{the right to make the returned string length of size.}
{-----------------------------------------------------------------------------------}

    function Uppercase (theString: str255): str255;
{-----------------------------------------------------------------------------------}
{Make string uppercase.  All characters in theString are raised to uppercase including}
{diacriticals.}
{-----------------------------------------------------------------------------------}

    function Lowercase (theString: str255): str255;
{-----------------------------------------------------------------------------------}
{Make string lowercase.  All characters in theString are lowered to lowercase including}
{diacriticals.}
{-----------------------------------------------------------------------------------}

    function CapitalizeWords (theString: str255): str255;
{-----------------------------------------------------------------------------------}
{The first character of each word in theString is made uppercase.}
{-----------------------------------------------------------------------------------}

    function NumberToString (num: LONGINT): Str255;
{-----------------------------------------------------------------------------------}
{The number num is converted to a string.  This will accept either longInts or integers}
{-----------------------------------------------------------------------------------}

    function RealToString (realNum: real; decimals: integer): str255;
{-----------------------------------------------------------------------------------}
{This function converts realNum to a string.  The number will be rounded to the number of}
{decimals specified by decimals.}
{-----------------------------------------------------------------------------------}

    function StringToNumber (theString: str255): longInt;
{-----------------------------------------------------------------------------------}
{theString is converted to a number.  Does not check for characters other than numbers}
{in theString}
{-----------------------------------------------------------------------------------}

    function TimeToDateString (time: longInt; style: integer): Str255;
{-----------------------------------------------------------------------------------}
{TimeToString will convert time (obtained by using GetTimeDate or TimeNow) to a string}
{using the International Utilities Toolbox.  There are three choices of style.  Using 1 will}
{return a string in the format 11/24/68. Using 2 will return a string in the format}
{Sunday, November 24, 1968. Using 3 will return Sun, Nov 24, 1968.  There are no}
{leading zeros for these formats.  If you need equal length strings use TimeToStr instead}
{-----------------------------------------------------------------------------------}

    function TimeToStr (time: longInt; includeTime: boolean; timeOnly: boolean): Str255;
{-----------------------------------------------------------------------------------}
{time (obtained by using GetTimeDate or TimeNow) is converted to a string with the format}
{ (MM/DD/YY HH:MM:SS) or (MM/DD/YY) or (HH:MM:SS) depending on the value of includeTime}
{and timeOnly.  The advantage of this function is that it adds leading zeros so the string returned}
{is always the same length.}
{-----------------------------------------------------------------------------------}

    function FindAndReplace (theString: Str255; oldString, newString: Str255): str255;
{-----------------------------------------------------------------------------------}
{This function takes theString and replaces the first occurance of oldString with newString}
{and returns the resulting string.}
{-----------------------------------------------------------------------------------}

    function FindAndReplaceAll (theString: Str255; oldString, newString: Str255): str255;
{-----------------------------------------------------------------------------------}
{This function takes theString and replaces the all occurances of oldString with newString}
{and returns the resulting string.}
{-----------------------------------------------------------------------------------}


{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}
{----------------------------------- Misc Functions ----------------------------------}
{•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••}

    function GetQDGlobals: QDGlobalRec;
{-----------------------------------------------------------------------------------}
{This function will return a QDGlobalRec which is defined above.  This record is identical to}
{the QuickDraw globals which are normally available in an application but not normally}
{available in an external.  Really good stuff can be found here like screenBits.bounds which}
{has the screen size.  This also allows you to use the random call below}
{-----------------------------------------------------------------------------------}

    function GetRandom (range: integer): integer;
{-----------------------------------------------------------------------------------}
{This function will return a random number between 1 and range.  When you first call this}
{function it may be a good idea to call it a few times before using its value.  A good way to}
{make it more random might be take the current seconds value and call this function that}
{many times to initialize it.  Without true access to the QDGlobals this function does not}
{properly seed the random call.  After the first time however this call be fine.}
{-----------------------------------------------------------------------------------}

    function RandomNumber (range: integer): integer;
{-----------------------------------------------------------------------------------}
{This function will also return a random number but does not rely on the Mac toolbox call. Its}
{your choice.  This may not be as true a random but doesn't suffer from the lack of QD globals}
{that GetRandom does.  If you need to be sure that the first few times you call random are}
{truely random I would use this function rather than the other one.}
{-----------------------------------------------------------------------------------}

    function TimeNow: longInt;
{-----------------------------------------------------------------------------------}
{This function returns the current time in seconds since 1/1/1904.  This is just written as}
{a function to make it easier to use.  You can use this with the TimeToDateString to get the}
{current date or time.}
{-----------------------------------------------------------------------------------}

    function Sys7OrLater: boolean;
{-----------------------------------------------------------------------------------}
{This function returns whether the current system is 7.0 or later.}
{-----------------------------------------------------------------------------------}

    function TrapAvailable (trapNum: integer; tType: TrapType): boolean;
{-----------------------------------------------------------------------------------}
{This function will return whether a trap is available just in case knowing that system 7 is}
{available isn't enough.}
{-----------------------------------------------------------------------------------}

    function PlaySound (sndNum: integer; sndName: str255; asynch: boolean; channel: SndChannelPtr): OSErr;
{-----------------------------------------------------------------------------------}
{This function will play a sound on the local machine.  sndNum is the resource number of a }
{'snd ' resource contained in your external.  If you pass a number of 0 the procedure will}
{use the sndName instead.  This may be a better way of making sure that you don't play}
{someone elses sound ;-] If asynch is false the sound will play before control is returned,}
{if true the sound will play asychronously.  If you want to play the sound asynchronously}
{you MUST keep track of a SndChannelPtr in your privates and pass it to this function. This}
{pointer should be intitialized as nil before passing it to PlaySound.  If you set asynch to}
{false you can just pass nil for channel.  I would recommend just passing false and nil unless}
{your sound is really long (which would lock up the BBS until finished).}
{-----------------------------------------------------------------------------------}

    function MovedFrom (thePoint: Point; changeAllowed: integer): boolean;
{-----------------------------------------------------------------------------------}
{This function returns whether the mouse has moved more than changeAllowed pixels from}
{thePoint.  Use GetMouse(thePoint) and then LocalToGlobal(thePoint) to get the mouse}
{postion and then this function to decided if it has moved.}
{-----------------------------------------------------------------------------------}

    function CheckCard (cardNum: str255; visa, master, amex, discover: boolean): boolean;
{-----------------------------------------------------------------------------------}
{Yea, yea this is getting strange but I needed it so why not make it avaliable.  This function}
{will take a string representing a credit card number and will determine if the number is in}
{the valid format.  Pass true in the remaining varialbes for each type of credit card that is}
{acceptable.  In other words if you pass false for a varialbe that card type will  not be }
{considered valid.  The cardNum string can have spaces although they are not necessary.}
{All spaces will be ignored when evaluating the number.  This function does three things.}
{First, it checks the first number of the card for the credit card type and sees if that type}
{is accepted.  Second, it makes sure that the number is of the proper number of digits for}
{each type.  Third , it does a checksum on the number to see if it is a possible credit card}
{number. This checksum is fairly involved and is not something you would want to do in}
{your head but it is a good way to check cards.  A number which passes these checks is}
{not necessarily valid (ie it may not be assigned to anyone, stolen etc) but this is a good way}
{to screen out fake numbers and mistakes.}
{-----------------------------------------------------------------------------------}

    function CheckExpiration (expirationDate: str255): boolean;
{-----------------------------------------------------------------------------------}
{This function will take an expiration date (in the form MM/YY) and return whether this date}
{has passed yet.  With this and CheckCard, assuming the information is given truthfully, you}
{can confirm the validity of a credit card immeadiately.}
{-----------------------------------------------------------------------------------}

    procedure SetMouse (newPoint: Point);
{-----------------------------------------------------------------------------------}
{This procedure will set the cursor to newPoint.  Why you would want to do this is beyond me}
{but I had a reason to do so (the user doesn't ever notice).  This is a really rude thing to do}
{and is a good way to have an program which flops (people hate the mouse moving on them)}
{-----------------------------------------------------------------------------------}

implementation

end.