Function List
Here are all TurboIRC supported functions . Functions take some parameters , calculate a result and return it . The parameters can be integers or strings , and the return values also are strings or integers , or even nothing ( void )
To clear the functions , I sorted them by category . The first word is the return type of the string , and it is int , string ,or void . Then the function name , and then any optional parameters .
All function names are case-sensitive !
1.IRC Functions
These functions handle IRC things .
GetClientMode returns a string describing your client mode , for
example "ix" ( look NickModes ) .
Example : string Str = GetClientMode()
GetCurrentWindowName returns the name of the window that is active .
Example : string Str = GetCurrentWindowName()
GetChannelMode takes a channel name as a parameter and returns the Channel Modes .
Example : string Str = GetChannelMode("#MyChannel")
Example with two functions :
GetChannelTopic returns the topic of the specified channel .
GetChannelM/Q/O/VpCount , returns the number of members / owners / hosts / voices in a channel . Example with a script :
GetWindowType accepts a name and returns 1 if it is a server window , 2 if it is a channel window , 3 if it is a query window , and 0 if no such window was found
GetNickCount accepts a channel name and returns the nicks found . The same with GetChannelMpCount() .
GetNickLevel acceps a channel name and a nick name . It returns 1 : The nick is a member in the channel . 2 : The nick has voice in the channel . 3 : The nick is a channel operator . 4 : The nick is a channel owner . 0 : The nick was not found in the channel .
GetFormattedNick accepts a channel name and a number . The number is an index from 0 to GetNickCount() - 1 , to indicate which nick should be returned . The nick is returned with any prefix it might have .
GetNick , is the same with GetformattedNick , except that any preffixes are removed .
GetCurrentNick , accepts a channel name , and returns the nick that is currently selected , in a zero base ( first nick = 0 , second = 1 etc ) . This is the same with sending a LB_GETCURSEL message with SendMessage function to the nick list box . If it is no nick selected , it returns -1 . If the Toggle parameter is 1 , the hilight is removed from that nick . That allows a script to process multiple selections from the Nick List . If the Toggle is 0 , the nick is still hilighted .
IsOwner , IsHost and IsVoice , accept a channel and a nick and return 1 if the nick is owner/host/voice respectively in the channel , otherwise return 0 .
IsOp accepts a channel and a nick and returns 1 if the nick is owner or host in the channel . IsOp is provided for PIRCH-mIRC-other IRC users . All those IsXXXX functions are superseded by GetNickLevel .
2.TurboIRC Functions
These functions are TurboIRC special functions .
Mask takes a mask and removes the starting : , that the servers append to the mask .Rarely used because having a mask with : in a parameter , for example $0 , you may use "$0" + 1 to by pass the first : character . Mask is only useful when you need to use a mask within a line that starts with / or \ ( and there the "$0" + 1 is not converted ) .
GetMask allows you to convert a mask to the desired type . For example, if you have a mask Nick!Ident@port.domain , you may want to set * as the nick or ident or domain . The type can be an integer from 0 to 14 , as in the Preferences dialog box .
NickFromMask , IdentFromMask and IPFromMask take a mask in the form of nick!ident@domain , and return the nick , the ident and the domain , respectively . These functions are useful only if that mask is returned in a place other than $0 ( See Script Parameters ) , because if the mask is in $0 , you can access it with $nick , $ident , and $IP , respectively . Almost all server events that contain a user mask , they place it in $0 .
DefaultBanFromMask takes a mask and returns a string that represents your Ban Method . For example , if you have set your ban method to *!*@domain , the function will convert a mask from e.g. MyNick!identhere@domain.com to *!*@domain.com .
FindWindowFromTitle takes a window name and returns the relative position in the WOPTIONS structure . The WOPTIONS structure is an internal TurboIRC structure to hold window information . You need this value to call GetWOPTIONS function . The other FindWindowFromTitle version has you to give a server number . For the current server number , you can use the $servernumber . If you want to specify another server , it is your responsibility to know witch number has the other server . Warning : The number returned from FindWindowFromTitle is valid only while no new window has been created or an old window has been destroyed . If your script creates/destroys windows , be sure to recall FindWindowFromTitle to get the correct number of a window , to call GetWOPTIONS .
MessageBox shows a message to the user . The first parameter is the message , and the second is the caption of the message box . The third parameter can be 0 , so the MessageBox displays only an "OK" button , or 1 , so the MessageBox has an "OK" and a "CANCEL" button . If you specify 0 , MessageBox always returns 0 .If you specify 1 , MessageBox returns 0 if the user pressed the OK button , or 1 if pressed the CANCEL button . Message boxes have the MB_SYSTEMMODAL window style to ensure that the user will view them .
Random returns a random integer , in the range you specify . If you specify 1000 as the range , the return value will be from 0 to 999 .
LOWORD and HIWORD take an integer and return the low or the hi 16 bits , respectively .
SecondsToTime takes an integer describing seconds and converts it to a string describing the equal time .
UNIXTime takes an integer describing seconds and converts it to a string describing the date and time . UNIX - style times assume that the time starts from Jan 1, 1970 .
GetTickCount returns the milliseconds that have passed since Windows started . You can use this value to compare times if you don't care about the time , but the difference between scripts .
CreateTemporaryFile returns a file that is guaranteed to NOT exist . You can safely then use CreateFile() ( check File Functions later )
GetWOPTIONS takes the number of a window ( as returned from FindWindowFromTitle ) and a string parameter that describes which window parameter should be returned . GetWOPTIONS is an extended function that you will need only if you mess with Window Functions ( see later ) , and very extended scripts . GetWOPTIONS returns a string or an int , depending on the value you will ask . Possible Parameters are :
You can call GetWOPTIONS with any window number , within the range of 0 and $totalwindowsactive . If you call GetWOPTIONS with a number out of range , GetWOPTIONS will return nothing .
If you want to find a window that has a specific option , you can call GetWOPTIONS for all the windows you 'd like , until you find the number needed .
GetCCWOPTIONS takes the number of a dcc window ( as returned from the special event OnDCCMessage ) and a string parameter that describes which window parameter should be returned for the DCC box . GetCCWOPTIONS returns a string or an int , depending on the value you will ask . Possible Parameters are :
Please note that you cannot assume that the window number is the same anytime you call the GetCCWOPTIONS , but you can assume that the socket value is correct .
GetGOPTIONS returns information about general options , that are not listed in PREF.INI so you can get them with INI Functions . It returns a string or an integer , depending on what you are asking :
In case you want to modify the Popup Menus , you can check TurboIRC.RC , the resource script file included with your TurboIRC package , to see how the menus are placed .
GetSOPTIONS , is the same about GetWOPTIONS , but it returns not window-parameters , rather than server status parameters . GetSOPTIONS takes a number that must describe a Server Window in WOPTIONS structure . The $servernumber always holds the number of the current server . Possible parameters of the value are :
GetSOPTIONS allows you to see if there is currently a dialog active . This way you are able e.g. to permit a script to lock the process if TurboIRC is using a dialog to format the output . The parameters are
In case you want to modify any of the dialogs , your TurboIRC.RC file in the TurboIRC package shows you each dialog box and how it has the controls arranged .
The number that GetSOPTIONS return if you request "socket" , is guaranteed to be valid until the specified server is dead . TurboIRC uses this value to append to files that hold user information , to be stored in ..\DYN ; When a user sends you a command , OR you add or modify a user using /setuserlevel and other Default Aliases , the user information is stored separately for each server in a file in DYN directory under TurboIRC directory . The file name starts with SU and the next is the socket number , e.g. SU27.DAT . The 27 is the value of the socket that is guaranteed to be unique until the server connection is dropped .You can use the DYN directory to store files dynamically , within your scripts .
SetSOPTIONS allows you to modify some server options . It is the same as GetSOPTIONS , except it has an additional int/string parameter describing which option should be changed . Only the following options are available with SetSOPTIONS:
Here is a script example to set you automatically away after 5 minutes of non-inputting
text .
Use this script e.g. in the Timer30Seconds Special Event to auto /away .
IsMatching , is the function that the whole TurboIRC capture-mechanism on events and IRC translations is based on . IsMatching matchs a given text with a given pattern , and returns 1 if they match , or 0 if they don't . Both pattern and text can have wildcards in them . IsGlobal performs the matching globally ( see the example for details ) if it is 1 , and if CaseSensitive is 1 , the comparison is case-sensitive .
Examples:
GetParameter accepts a string that has space-delimited strings , and returns a string based on the integer argument ( zero-based ) . GetZParameter does the same , and returns the rest of the parameters supplied . For example
string MyS = GetParameter(0,"Hi there")
this returns "Hi" to MyS .
string MyS = GetParameter(3,"Hi there my lovely friend")
this returns "lovely" to MyS .
string MyS = GetZParameter(3,"Hi there my lovely friend")
this returns "lovely friend" to MyS .
AddCRLF appends the cr,lf characters to a string and returns the new string . The cr,lf characters are the special characters to break a line . This is useful when you want to write information to a txt file and you want to break the line . Note that AddCRLF adds the crlf only if the characters do not already exist . Do not assume that applying 2 times AddCRLF will result to a 2 line breaks .
RemoveCRLF removes the crlf from a string . The CRLF is removed only if exist , of course .
FileToBase64 reads a file ( specified in the first argument ) , and creates a new file ( the second parameter ) that represents the contents of the first file , encoded with the Base64 method . This function is useful if you want to send a mail and you want to attach the file . The function returns 1 on success and 0 on error . The function fails if the second file already exists .
Base64ToFile is the reverse of FileToBase64 . It creates a normal file based on the converts of a Base64-encoded file .
3.String Functions
These functions handle strings .
FindStringPos searches in the first string , to find the second string . If the string is found , it returns a number describing the 0-based position that the string was found . If not , it returns -1 .
FindExStringPos is the same , but the string to be found must be whole word only . If you use 1 in the IsComma parameter , the function will assume that values that are separated with "," are whole words in the string .
strcpy returns the string parameter . This is not generally in use because strings can be assigned values using the = operator .
strncpy takes the string parameters , and returns a string that may be
shorter than the original depending on the num parameter .
Example : string MyStr = strncpy("hello there",5)
This makes MyStr hold "hello" , because only 5 characters are copied .
strlen returns the string length , the total characters in the string .
atoi returns an integer expression of a given string . For example , if you pass a string "523" then the integer returned will be 523 . If atoi cannot convert the given string to an integer , it returns 0
strcat takes the first argument , appends the second to the first and
returns the result .
Example : string MyStr = strcat("Lost +","Found")
MyStr now contains "Lost + Found"
strncat is the same with strcat , but you have to
tell the function how many characters from the second string will be appended to the first
string .
Example : string MyStr = strncat("Lost + ","Found",1)
MyStr now contains "Lost + F"
strcmp compares two strings case-sensitive . If the strings are equal , it returns 0 .
strncmp is the same , but you must specify how many characters should
be compared .
Example : strcmp("Hey","Heyy") will not return 0 , but
strncmp("Hey","Heyy",3) will .
stricmp and strnicmp are the same functions with strcmp and strncmp , but they compare case-insensitive .
strlwr takes the parameter and returns the same string , converted to lower case letters . Other characters are not affected .
strupr does the conversion to upper case letters .
strrev takes a string and returns the reverse image .
Example : string MyStr = strrev("hi")
MyStr now contains "ih"
strstrip takes a string and removes attributes , e.g. Bold/Italic/Underline . This is useful when you want to get rid of IRC attributes in strings . The attributes that will be removed are specified in the second parameter , that can be a combination of :
Specify -1 to ensure that all attributes will be removed .
strrep replaces a string within another string . It takes a string as the first parameter . The second string is the value that should be replaced, and the third is the value that will be placed . The last integer should be 0 , to indicate that the function should not research the replaced string to perform another replacement . If you use 1 , strrep will do multiple replacements . WATCH out ! If your new string contains also the first string , strrep will crash your TurboIRC . For example , strrep("hi there", "hi","hii",1) will crash , because "hii" contains "hi" .
sprintf , is an extended function that takes a pattern and creates a string based on the arguments . All pattern commands begin with % and next is a value desribing a parameter . For example
string MyStr = sprintf("%i",5)
this creates a string "5" to store in MyStr . With sprintf , you can create strings that contain also integer expressions , as well as to format the values . For example :
MyStr = sprintf("Hello there this is number %i",5*4)
sprintf is very powerful command if you have some values to an INI file for example
instead of continuously creating "Name1" "Name2" etc strings , you can create a loop inside the script , that increases an integer variable , and then use sprintf to create the name . For example
This loop will be executed for 100 times , and the Text variable will be assigned Name1 , Name2 ... Name100 . If you are a C++ programmer , you know about sprintf and printf , and you can use it very well to enhance your TurboIRC scripts . Unfortunately , there are too many sprintf commands and patterns , that I cannot describe here ... only the %i might be useful to you . sprintf can also take more than 1 argument , for example
Text = sprintf("The result of %i * %i is %i !",3,4,12)
this creates : "The result of 3 * 4 is 12 !"
OR , more professional
4.Sound Functions
These functions handle sounds .
FindSoundFile takes a filename and searches to match 1st , in TurboIRC directory , 2nd , in the directory you install sounds ( default SOUND under TurboIRC directory ) , and in the Windows MEDIA directory . If the file is not found , it returns an empty string, otherwise it returns the path of the file found .
GetSoundType returns 1 if the file is WAV , 2 if the file is MID , and 3 if the file is MP3 . Otherwise it returns 0 . Remember that this version can only play WAV and MID files .
5.File Functions
These functions handle Binary and Text Files . If you need to handle INI files , see section 8
CreateFile creates a new file , or opens a file . The first parameter is the filename of the file to create . If you want to be sure that you will create a new file , use CreateTemporaryFile() to get a new file name . The Access parameter is one of the following :
The CreationDistribution parameter is one of the following :
If successful , CreateFile returns an integer that you will need to access the file in other File Functions . If it fails , it returns 0 .
In case that you are a Windows Programmer , FILE_SHARE_READ and FILE_SHARE_WRITE are also passed to CreateFile .
ReadFile , reads some bytes from a file ( max 4096 per once ) . It returns a string containing the bytes read . The first parameter is the file handle , as returned from CreateFile . After a successful read , the file pointer is updated ( See SetFilePointer )
WriteFile , writes to the file handle ( as returned from CreateFile ) , some bytes . The function reads the bytes from the string supplied , and the bytes to be written is the second parameter . The function does not return a value . The file pointer is also updated .
SetFilePointer allows you to set the position from which the next WriteFile or ReadFile is start . The first parameter is the file handle . The second are the bytes to move , and the 3rd is one of the following :
Example : SetFilePointer(FileHandle,1,0) will set the pointer to the beginning of the file plus 1 .
SetFilePointer returns the current file pointer . You can use that to find the size of a opened file , like that :
int Size = SetFilePointer(FileHandle,0,2)
This places the pointer to the end of the file . BE SURE to restore the file pointer to its original value .
CloseFile , closes a handle opened by CreateFile()
DeleteFile , deletes a file . The file must be closed to delete it . For example DeleteFile("MYFILE.DAT") will fail if the file is opened .
ExistsFile , returns 1 if the file you supply exists in the disk , otherwise it returns 0
GetFileExtension , accepts a file and returns its extension . You may use that function to check which files that you get via DCC transfers should be executed with /shellexecute .
GetFileSize , accepts a file and returns its size . This function does not require the file to be opened like SetFilePointer .
FullToShort returns only the filename from a full path & filespec .
AppendText appends the second parameter ( a buffer ) to the file ( the first parameter ) . The file must be closed . AppendTextCRLF does the same , but it adds also a "crlf" ( line feed & carriage return after the line . AppendFile reads a file ( second parameter ) and appends it to the first file . All these functions return 1 on success .
CopyFile copies the first file to a second file . If the last parameter is 1 and the second function already exists , the function fails ( returns 0 ) , otherwise the function succeeds .
MoveFile renames the first file or directory to a second name . The function returns 1 on success.
6.Directory Functions
These functions handle directories .
CreateDirectory creates the directory you supply . The directory can be a relative to the directory path , such as ".\HEYYY" , or a full path . The function returns 1 on success and 0 on failure .
RemoveDirectory is the same , except that it removes the directory you supply .
GetCurrentDirectory returns a string containing your current directory . If you plan to change directories , you MUST reset the current directory when your script finishes .
SetCurrentDirectory sets the current directory . If you don't reset the directory when finished , you will encounter weird things .
7.Dialog Functions
These functions handle dialogs .
AskInput , shows the user a dialog and request an input . Title is the dialog title , and Prompt is the prompt to enter the text . Default is the initial string to be displayed . If the user clicks ok , the function returns the text typed . If clicks cancel , an empty string is returned .
GetSelection , is an extended function that allows you to prompt a user to select between selections . The Prompt is the prompt , and Sel1 , Sel2 are possible selections . You can use up to 5 selection strings . When the dialog box is created , the first selection is the default . Once the user presses OK , the function returns 1 , 2 , 3, 4 , or 5 describing which selection was selected . If the user presses Cancel , the function returns 0 .
Example :
GetColor , shows the user a color dialog box , prompting him/her to choose a color . The color value is returned as the result of Red , Green and Blue attributes (RGB ) . Use of GetColor is good only when you want to manage colors that TurboIRC supports via the ^G input ( See Input ) .
GetMIRCColor , shows the user the color dialog box , but on return , it converts the selected color to a mIRC color , returning 0 - 15 as the result of the color . If the color cannot be converted , it returns -1 . The user should select one of the custom colors provided to ensure that the color will be converted .
GetOpenFile and GetSaveFile shows you the Open...or Save As... dialog box , allowing you to choose a file for opening or saving . The title is the title of the dialog box . Flags are a combination of the following values :
#define OFN_READONLY 0x00000001
#define OFN_OVERWRITEPROMPT 0x00000002
#define OFN_HIDEREADONLY 0x00000004
#define OFN_NOCHANGEDIR 0x00000008
#define OFN_SHOWHELP 0x00000010
#define OFN_ENABLEHOOK 0x00000020
#define OFN_ENABLETEMPLATE 0x00000040
#define OFN_ENABLETEMPLATEHANDLE 0x00000080
#define OFN_NOVALIDATE 0x00000100
#define OFN_ALLOWMULTISELECT 0x00000200
#define OFN_EXTENSIONDIFFERENT 0x00000400
#define OFN_PATHMUSTEXIST 0x00000800
#define OFN_FILEMUSTEXIST 0x00001000
#define OFN_CREATEPROMPT 0x00002000
#define OFN_SHAREAWARE 0x00004000
#define OFN_NOREADONLYRETURN 0x00008000
#define OFN_NOTESTFILECREATE 0x00010000
#define OFN_NONETWORKBUTTON 0x00020000
#define OFN_NOLONGNAMES 0x00040000 // force no long names for 4.x modules
#if(WINVER >= 0x0400)
#define OFN_EXPLORER 0x00080000 // new look commdlg
#define OFN_NODEREFERENCELINKS 0x00100000
#define OFN_LONGNAMES 0x00200000 // force long names for 3.x modules
#endif /* WINVER >= 0x0400 */
The values are in HEX , so you must convert them to decimal before using .
The file the user selected is returned as a string . If the user press "cancel" , an empty string is returned .
8.Ini Files
These functions handle INI files . To handle a text of a binary file ,check File Functions above .
GetString takes a string from an ini file . The first parameter is the section you search in ( e.g. [params] )be , the key is the key that you will take its value . The default is the string that wil returned if the key is not found in the ini file . The . last parameter is the ini file to search in
GetInt is the same , but in converts strings to integers , if the conversion can be done . For example , if you have a key containing the string "43" , GetInt will return 43 , and GetString will return a string "43"
SetString sets a key value in the ini file . The ToAdd parameter is a string to set . If you want to set an integer value , convert the integer to a string value using sprintf ( see string functions above ) and store it with SetString .
Note that if you set a string to PREF.INI , you may force TurboIRC to reload the preferences using /reloadoptions .
IsInIni takes a section of an INI file and searches all key values to find the value given (case insensitive) . If a key is found , it is returned , otherwise the function returns an empty string .
IsMatchInIni takes a section of an INI file and tries to match all key values to match the given pattern . If a key is found , it is returned , otherwise the function returns an empty string . For the IsGlobal and Case parameters , see function IsMatching
9.Window Functions
These functions handle Windows . They enable you to direct create and communicate with existing windows . These functions require the knowledge of Windows API programming , but some useful parameters will be discussed here .
CreateWindow creates a window . This function calls directly the CreateWindowEx() WinAPI function . Some of the parameters are discussed below
ExStyle , is the extended style of the window . The most usual style is WS_EX_ACCEPTFILES ( equal to 16 ) , that causes a window to receive WM_DROPFILES ( equal to 563 ) messages when a user drags + drops a file to that window .
Class , is the string describing the window class . The class is what type the window would be . It can be any registered class name , like "button" , "edit" , "listbox" , "combobox" . TurboIRC has 3 more classes for you to use .
Title , is the window title
x,y,w,h are the x , y , weight and height of the window . You can use CW_USEDEFAULT for them ( = -2147483648 ) to order the window placement to be the default .
Style is the style of the window . If you create a frame window , the style might have WS_MAXIMIZEBOX , WS_MINIMIZEBOX , WS_BORDER etc ( all those values in HEX are in WINUSER.H file , included with your TurboIRC package ) .If you create a window other than frame , but to be in that frame window , the style should at least include WS_CHILD .
Parent , is the handle to the parent window . If you create a frame window , the parent can be either 0 , or a handle to a TurboIRC window ( get the handle by the use of GetWOPTIONS ) .If you create a child window , the parent should be the handle of the owner window .
ID , is the window ID . If it is a frame window , this is the menu handle as returned from Menu Functions ( see below ) , if you want the frame window to have a menu ( otherwise , set it to 0 ) If it is a child window , this ID can be any number to indentify the child window between the other child windows . Using GetDlgItem with that ID , will return the window handle of that window .
BgColor is the background color of the new frame window .
SetWindowHandler , is the mechanism for windows to catch and handle messages . For example, assume that you have created a frame window , and a push button inside , with the child ID = 101 . When you press this button , it sends a WM_COMMAND (=273) message to the frame window , and the first parameter of the message has the 101 in the low word . To fire a script when this message occurs , you use :
SetWindowHandler(handleofwindow,273,-1,-1,"AMYSCRIPT")
Please note that SetWindowHandler can be used only for messages that are received by the frame window , if a child window sends it to it . If the child window does not send a message to its parent , you won't be able to process it .
Whenever a WM_COMMAND is posted , the script will be fired , regardless of the value of the message parameters , wParam and lParam . If you used something else except a -1 , the script would be fired only if the message parameter match the argument .
Because you may have for example more than one control in your frame window , you need to check which control send the WM_COMMAND . Scripts that are message handlers have at
with a WM_COMMAND , the first parameter's low word contains the ID of the control . For example , if you had 2 buttons with 101 and 102 ID's , you could fire the same script for the two clicks . The script would start as follows :
Other messages , like WM_CHAR , send different data to their parameters . Please check the WinAPI documentation to learn all message parameters .
Useful message is also WM_CLOSE , posted when a user clicks the X to close the window . You script then might ask him before using the DestroyWindow .
Script Window Handlers should return an integer as a result . What this integer would be , depends on the message sent . For example , a WM_COMMAND message requires a 0 to be returned .
Up to 100 message handlers can be installed . When you install a message handler , BE SURE to delete it when you don't need it . Deleting a handler is done with SetWindowHandler , with the same parameters , and "" as the script to be executed . Your handler will then be removed .
All frame windows are automatically recognize the WM_CLOSE message and destroy themselves , unless you add a special handler for this message .
DestroyWindow , destroys the window that it takes as the parameter .
SendMessage , is used to directly send a message to the window .The message comes with 2 parameters , to describe the requested message and it returns an integer . The parameters depend on the message to send . For example , a WM_SETTEXT can be send to a control , to set the caption , and WM_GETTEXT can be send to a control to get the caption . If your message returns a string , as WM_GETTEXT , you should use LSendMessage , that copies the string to your variable . ( For those messages , however , there are the SetWindowText and GetWindowText to simplify your scripts ) .
The following example takes the server window's text , adds "Hey there" to the end and re-sets the server text
PostMessage ,does the same with SendMessage , but it does not wait for the window to process the message to return something . It returns immediately .
SetFocus , sets the keyboard focus to a window . The window , or the parent of that window must be activated first to get the focus ( See SetForegroundWindow )
SetForegroundWindow sets the foreground window from the handle you pass to it .
GetFocus returns the window that currently has the focus .
GetForegroundWindow gets the current foreground window .
GetDlgItem returns a handle to a child window of a frame window , based on the child ID . For example , if you create a frame window that has a button inside with the ID 101 ( as passed to the CreateWindow ) , then you can use GetDlgItem with the frame handle and the 101 to return the window handle of the button .
GetWindowText accepts a window handle and returns its text . The text is not returned if bigger than 4096 bytes . The same as sending a WM_GETTEXT to the control
SetWindowText acceps a window handle and a string , and sets the window's text to that string .The same as sending a WM_SETTEXT to the control .
10.User List Functions
These functions handle User Lists.
GetUserIdent and GetUserDomain return the Ident/Domain of a nick name . For these functions to return something , this user must have sent you at least one message , otherwise they return an empty string .
GetUserLevel , GetUserEnemyLevel and GetUserFriendLevel return the user Level,EnemyLevel,FriendLevel . Those values have no meaning in TurboIRC , but you can use them as definitions of a user . The user must have sent you at least one message for these functions to return something . The value returned is always 0 , except if you change it using /setuserlevel ( see Default Aliases ) . These are just a quick-help levels . For the most advanced handling and user-leveling , you can use GetUserData .
GetUserData returns a specific integer of that user . You can assign up to 100 integers to a user ( index 0 to 99 ) , with /setuserdata . These integer values can help you in scripts . If the index is > 99 , GetUserData returns 0 .
GetUserString returns a specific string of that user . You can assign up to 4096-total byte strings to a user ( index 0 to 4095 ) with /setuserstring . These string values can help you in scripts . If the index is > 4095 , GetUserString returns an empty string .
It is important to know that the user information is stored under a directory DYN under TurboIRC directory . Also , all information is updated when a user sends you a message that he/she changes nick .
11.Menu Functions
These functions handle Menus
GetMenu returns the menu handle of an existing window . Use the GetWOPTIONS to get a handle to a TurboIRC window . Do not use GetMenu to get a menu handle of a child window , since child windows do not have a menu . Do not assume that when GetMenu is applied to a child window , it will return the Identifier of that window ; Use GetDlgItem instead .
DrawMenuBar redraws a window's menu . You need to call this function if you modify an existing window menu .
GetSubMenu accepts a menu handle and a zero-based relative position to that menu , and returns the handle of the new menu . This function is used when you want to get the menu handle of a popup menu that is inside another menu .
CreateMenu returns an empty menu handle . This function is the first one you will call to create a menu of a new window .
CreatePopupMenu returns an empty popup menu handle . You can fill this menu with items with AppendMenu , and then include it to the main menu you get from CreateMenu .
DestroyMenu destroys a menu handle . If your menu is assigned to a window , you need not to call DestroyMenu - The menu is destroyed when you call DestroyWindow .
AppendMenu enables you to fill a menu with items . The first parameter is a handle to an existing menu . If Type is 0 , then you append a simple menu . If Type = 1 , you append a popup menu .The ID is the menu identifier value if it is a simple menu ( this ID will be sent with the WM_COMMAND message , see SetWindowHandler ) , and an existing popup menu handle if you append a popup menu . The last parameter is the string that will be shown .
DeleteMenu deletes the Pos value from the given menu . If Type is 0 ,Pos is the ID value to the menu . If Type is 1 , Pos is the zero-based relative position of the menu .
The following example creates a window that has a popup menu and this popup menu has a simple menu in it :
The first line gets the window handle of the server window . The second line creates an empty popup menu , that is filled with a simple menu named "Test" and ID = 101 in line 3 .
Line 4 Creates a menu , and fills it with the popup menu we created in line 3, in line 5 .
Line 6 creates a window , child of the server window , with the assigned menu .
In that case , we need not to call DrawMenuBar , because the window is assigned the menu AFTER the menu is created .
12.Clipboard Functions
These functions handle the Clipboard .
GetClipboard returns the contents of the clipboard . Only strings are returned . If a string is larger than 4096 bytes , it is truncated . Because the Windows Clipboard can be changed any time from another application and there is no guarantee that GetClipboard will success , it is recommended to use GetInternalClipboard
GetInternalClipboard returns the contents of the TurboIRC internal clipboard . This function is guaranteed to success and the contents of this internal clipboard can be changed only from TurboIRC , not from other applications
SetClipboard and SetInternalClipboard place the given string to the Windows or Internal Clipboard . It is recommended here to use SetInternalClipboard as well , guaranteed to success .
GetClipboardBitmap saves any bitmap stored in the clipboard to a file . The file must be new , or the function does nothing .
13.Registry Functions
These functions handle the Windows Registry . These allow you to create keys & subkeys and store values with more flexibility than handling INI files . The Registry Functions are advanced functions ; if you don't know what the registry is , simply don't try to use them .
Please note that under WindowsNT , you may not be able to use the registry functions due to security restrictions .
RegCreateKey creates a new key , or opens an existing key . If the ParentKey is 0 , TurboIRC will create the new key under HKEY_LOCAL_MACHINE/Software/TurboIRC . The name , is the name of the key . If the key already exists , the function opens it . If the key does not exist , the function creates it . The function returns a handle to the key
RegDeleteKey deletes a key . The key must not have sub keys . If ParentKey is null , the key that is deleted is HKEY_LOCAL_MACHINE/Software/TurboIRC/Name , that the Name is the Name parameter . Otherwise , the function deletes a key that has the parent the ParentKey .
RegCloseKey closes a key . You must call this to free key resources and memory .
RegSetKeyValue sets a key value . You can set multiple values for a key , this is about the same as a Section in INI files . Key , is the key to save information . Name , is the entry name to save . Type is 0 , if you are about to save an integer value ; in that case , the Value must be an integer . If Type is 1 , you save a string value .
For example , "RegSetKeyValue(ParentKey,"A String Is Here",1,"String Demo")
this creates an entry named "A String Is Here" under ParentKey , and stores to it "String Demo"
RegGetKeyValue returns a key value . The function returns either an integer or a string , depending of the type of the "Name" .
14.Drawing Functions
These functions enables you to draw text , lines , rectangles , ellipses and Image Files in your custom windows . in order to use these functions you must create a frame window and set a handler to WM_PAINT message ( = 15 ) . Your handler can then use the drawing functions . Windows posts a WM_PAINT message each time your window needs redrawing . TurboIRC handles WM_PAINT internally before firing your script to ensure that the message won't be re-sent again until needed .
GetDC returns the DeviceContext for the given window . This device context is used by other drawing functions as an identifier where to draw . After use , you must free the DC using ReleaseDC otherwise Windows may lock up .
GetWindowW and GetWindowH return the width and the height of a window available for drawing .
Rectangle makes a rectangle in the DC , with x,y,w,h the coordinates of the rectangle . Pen is a color value ( you can get it with the ColorTester or the GetColor function ) to draw the rectangle , and Brush is a color to fill the rectangle . Ellipse does the same , but it draws an ellipse ( that is bound by the rectangle x,y,w,h )
TextOut writes text to a certain x,y of the DC . Color is a value describing the text color and BgColor is the background color . If you specify -1 , then the text is drawn transparently , otherwise TurboIRC uses the given value to fill the background .
UpdateWindow forces a WM_PAINT message to be sent to the given window . You can use this function from your script to force redrawing of the window .
LoadImage allows you to load a picture from a file . TurboIRC can load images from BMP , JPG , JIF , RLE , DIB , TGA , PCX ( Thanks to K.Nishita 's library - look the Copyright Page ) . LoadImage returns a handle to use in DrawImage . Be sure to free the image you loaded with FreeImage after the use .
DrawImage draws an image from LoadImage to a DC . The starting position is x,y and if you specify w,h that are less than the actual image width and height , the image is "truncated" . If they are larger , the image is just shown .
FreeImage frees an image loaded by LoadImage .
15.Socket Functions
These functions allow you to transfer information with other servers or TurboIRC or other socket-capable machine throught the Internet . The integer values of identifies like SOCK_STREAM can be found in winsock2.h which is included in your TurboIRC help files . By default , when you create a socket , it acts synchronously ; that means that if you attempt to fire a connection with connect() , the function won't return until the connection attempt has succeeded ( or failed ) . This can cause TurboIRC to hand for a while . You can use WSAAsyncSelect to enable "asynchronous" level of a socket , but this requires a custom window to process messages from the sockets .
socket creates a new socket based on the given protocol . Windows Sockets 2.2+ support many types of protocols , however the most useful protocol is SOCK_STREAM , that allows you to communicate with other machines in the internet . socket() returns 0 if it cannot create the socket .
#define SOCK_STREAM 1 /* stream socket */
#define SOCK_DGRAM 2 /* datagram socket */
#define SOCK_RAW 3 /* raw-protocol interface */
#define SOCK_RDM 4 /* reliably-delivered message */
#define SOCK_SEQPACKET 5 /* sequenced packet stream */
These are the values fom each socket type .
connect establishes a connection . The first parameter is the socket returned from socket() . The target string is either a domain name , or an IP address that describes the remote machine . The port number is the port the connection will be made . connect returns -1 on error .
connect by default waits for the operation to be completed before returning . On a non-blocking socket ( asyncronous ) , the function returns -1 and you may wait for a FD_CONNECT message to be posted to your window ( that you used with WSAAsyncSelect) to proceed with connection . On success connect returns 0 .
bind is used when you want to "listen" for an incoming connection . It binds the socket to the specified port . The listening must be enabled with listen , and incoming connections are accepted with accept . The remote side must use connect to your IP address and use the same port you used in bind .On success bind returns 0 .
listen sets a socket in "listening" mode . You can use then accept to accept incoming connections.The socket must first be bound with bind . On success listen returns 0
accept accepts an incoming connection on a listening socket . accept returns a new socket that can be used then , for transferring data . If you call accept on a blocking socket , the function waits until there is a connection . To avoid this , use WSAAsyncSelect with FD_ACCEPT , so the first time accept is called , it will fail , and your window will receive a FD_ACCEPT message when there is an incoming connection to be accepted . On error , accept returns INVALID_SOCKET ( -1 )
send sends data to a socket . The socket must be either connected successfully with connect() , or it must be create after a successful accepted connection with accept() . It sends the passed buffer , with the length passed as the 3rd parameter . send returns the number of bytes sent , or 0 or SOCKET_ERROR if fails . Type type of the transfer can be zero , to indicate normal data . If you place 1 , it indicates OOB ( Out Of Band ) data . OOB data may be faster than normal data , but if you want to communicate with services as mail server , ftp , etc , you MUST use normal data . Use OOB only when you want to establish a connection with a machine that is KNOWN to support OOB .
recv receives data from a socket . The socket must be either connected successfully with connect() , or it must be create after a successful accepted connection with accept() . The function cannot receive more than 4096 bytes at once . When there are no bytes to receive , recv() waits for them on a blocking socket . Use WSAAsyncSelect with FD_READ , and your window will receive FD_READ when the socket is ACTUALLY carrying data to be read . recv returns the buffer read , or an empty buffer if fails . Note that on a non-blocking socket, you must check the error result with WSAGetLastError . If it is WSAEWOULDBLOCK , then there is not actually an error - just wait for a FD_READ message . For the type of the recv , check above send() .
closesocket closes the socket . After closesocket , the value no more represends a socket handle.
WSAGetLastError returns the last error value after a socket operation . Possible error values are:
#define WSABASEERR 10000
/*
* Windows Sockets definitions of regular Microsoft C error constants
*/
#define WSAEINTR (WSABASEERR+4)
#define WSAEBADF (WSABASEERR+9)
#define WSAEACCES (WSABASEERR+13)
#define WSAEFAULT (WSABASEERR+14)
#define WSAEINVAL (WSABASEERR+22)
#define WSAEMFILE (WSABASEERR+24)
/*
* Windows Sockets definitions of regular Berkeley error constants
*/
#define WSAEWOULDBLOCK (WSABASEERR+35)
#define WSAEINPROGRESS (WSABASEERR+36)
#define WSAEALREADY (WSABASEERR+37)
#define WSAENOTSOCK (WSABASEERR+38)
#define WSAEDESTADDRREQ (WSABASEERR+39)
#define WSAEMSGSIZE (WSABASEERR+40)
#define WSAEPROTOTYPE (WSABASEERR+41)
#define WSAENOPROTOOPT (WSABASEERR+42)
#define WSAEPROTONOSUPPORT (WSABASEERR+43)
#define WSAESOCKTNOSUPPORT (WSABASEERR+44)
#define WSAEOPNOTSUPP (WSABASEERR+45)
#define WSAEPFNOSUPPORT (WSABASEERR+46)
#define WSAEAFNOSUPPORT (WSABASEERR+47)
#define WSAEADDRINUSE (WSABASEERR+48)
#define WSAEADDRNOTAVAIL (WSABASEERR+49)
#define WSAENETDOWN (WSABASEERR+50)
#define WSAENETUNREACH (WSABASEERR+51)
#define WSAENETRESET (WSABASEERR+52)
#define WSAECONNABORTED (WSABASEERR+53)
#define WSAECONNRESET (WSABASEERR+54)
#define WSAENOBUFS (WSABASEERR+55)
#define WSAEISCONN (WSABASEERR+56)
#define WSAENOTCONN (WSABASEERR+57)
#define WSAESHUTDOWN (WSABASEERR+58)
#define WSAETOOMANYREFS (WSABASEERR+59)
#define WSAETIMEDOUT (WSABASEERR+60)
#define WSAECONNREFUSED (WSABASEERR+61)
#define WSAELOOP (WSABASEERR+62)
#define WSAENAMETOOLONG (WSABASEERR+63)
#define WSAEHOSTDOWN (WSABASEERR+64)
#define WSAEHOSTUNREACH (WSABASEERR+65)
#define WSAENOTEMPTY (WSABASEERR+66)
#define WSAEPROCLIM (WSABASEERR+67)
#define WSAEUSERS (WSABASEERR+68)
#define WSAEDQUOT (WSABASEERR+69)
#define WSAESTALE (WSABASEERR+70)
#define WSAEREMOTE (WSABASEERR+71)
You can check the WINSOCK.HLP for such error codes , included with your TurboIRC package.
WSAAsyncSelect is a very special function . It allows you to set a socket to non-blocking mode . That means , that your script won't "stuck" when you try to use recv() and there is no data to be read . You can order TurboIRC to send a message to a window indicating the data to be read .
The first parameter of the function is the socket . The second is the window handle to receive the message . This must be a window created with CreateWindow "frame" class . The next is the message that the window will receive when the socket is ready for something . This value must be greater than 0x8000 ( 32768 )
The last argument is the mask that will handle the message . You can combine any of the following values :
#define FD_READ 0x01
#define FD_WRITE 0x02
#define FD_OOB 0x04
#define FD_ACCEPT 0x08
#define FD_CONNECT 0x10
#define FD_CLOSE 0x20
Examples :
When you have created a socket , you can then use WSAAsyncSelect with FD_CONNECT . When you try to use connect() , the function will fail and WSAGetLastError will return WSAEWOULDBLOCK . In that case , when the connect() operation is actually completed ,your window will receive a message , the same message you specified in the 3rd parameter . You must have used SetWindowHandler to handle this message .
The message is posted with the low word of lParam ( the first parameter ) having the event that is done , e.g. FD_CONNECT . The high word of lParam has any possible error code , and the wParam has the socket value , for which the asynchonous operation was completed .
FD_CONNECT is used when the socket is about to connected .
FD_READ is used when the socket has data to be read . If you read less data with recv() then , TurboIRC will repost a FD_READ message .
FD_WRITE is used when the socket can send data . Use WSAAsyncSelect after the last send() has failed .
FD_ACCEPT is posted when a socket is ready to accept incoming connection .
FD_CLOSE is posted when a socket is closed .
To cancel a WSAAsyncSelect , call it with hwnd , message and event set to 0
For more information on WSAAsyncSelect , check the WINSOCK.HLP included .
gethostname returns the current machine's local host name
gethostip returns the current machine's local IP address as a string in xxx.xxx.xxx.xxx format
getsockaddr and getsockport return the local address & port of a socket
getpeeraddr and getpeerport return the address & port of the peer , into which the socket is connected .
setblocksocket cancels any WSAAsyncSelect and returns the socket to blocking-mode .
16.Math and Calculating Functions
These functions allow you to perform mathematic and other calculations . When a function returns a float number , TurboIRC formats it to a string . To limit the length of the string , you can use the round function to strip the digits and then to show it . If you just want to keep the integer value , do an atoi to the strings .
abs convers an integer to its absolute value , e.g abs(-1) gives 1
asc convers the first character of the given string to its numeric ASCII value , e.g. asc("a") will return 97 , the ascii value of 'a'
chr converts a given integer to the appropriate string , e.g. chr(97) will return "a"
sin/cos/tan/asin/acos/atan return sine,cosine,tangent and the arc values of those in a string .
fact returns the x! value , for example fact(4) will return 1*2*3*4 = 24
sqr returns a string describing a root square value of the given integer
pow returns the power of the first int to the second , e.g. pow(3,5) will return 243
log / ln return the 10th based and the natural logarithm of an integer
_log returns the logarithm on a given base , e.g. _log(10,2) will give the log of 10 with 2 as a base .
round strips a string from decimal points , e.g. round("3.14159",2) will return "3.14"
17.HTML Dialog Box Functions
Now we come to the super feature of TurboIRC , the ability to load dialog boxes that contain HTML , and to be able to transfer parameters through scripts using JavaScript . This feature has no match in any other known IRC Client . To use these HTML functions , it is necessary to know to create a HTML page ( for example , with Microsoft FrontPage ) , and optionally , to use Java Scripts .
Important : Please note that TurboIRC calls the internal Microsoft Library to display the HTML . It does not display HTML itself , so I am not responsible for any bugs that are found in the HTML Library . Please be sure that you have installed Internet Explorer 4.0 or better , to use the HTML library.
ShowHTMLFile is only useful when you just want to show the user a HTML file . If you need to use JavaScripts to pass to and get parameters from the HTML file , you must use the functions starting with HTML_ . ShowHTMLFile does not require you to use any of the functions that start with HTML_ , but once you have loaded the HTML Library with HTML_Load , you should continue using HTML_ functions .
Most cases a simple /run or /shellexecute would be better if you just want to show a HTML file .
HTML_Load is used to load the HTML Library to show the HTML dialog box . This function must be called before any other HTML Dialog Function is called . The library must be freed with HTML_Free after use . On successful loading , HTML_Load returns 1 otherwise it returns 0
HTML_SetArgs sets the dialog box initial argument . This value is placed in the "window" object's "dialogArguments" property . Using JavaScript , you can access this property like window.dialogArguments . You can format a buffer to pass multiple arguments using sprintf() . Important : If you don't have any arguments , you still need to call HTML_SetArgs , passing an empty string .
HTML_Show shows the passed HTML file in the dialog box . This file can be any HTM - compatible file , with Javascripts , Java applets , frames ,etc. If the dialog box could not be shown, HTML_Show returns 0 , otherwise it returns 1 . You must either give a FULL path of the filename ( do not give a file like test.htm , just give c:\myfiles\...\test.htm ) , or give an internet address of a HTM file , example http://myself.com/ifile.htm . The function does not return until the user has closed the HTML dialog box .
HTML_GetArgs returns the dialog box window.returnValue property . You can use JavaScript to set this property , in order for TurboIRC to return it . If there is no such property , HTML_GetArgs returns an empty string .
HTML_Free frees the HTML Library that loaded with HTML_Load . You must call HTML_Free after the use of the HTML Library to ensure that all HTML stuff is cleared .
18.External Call Functions
TurboIRC has the great feature to give you the oportunity to create your own-language script and to use it ! This will be done with Dynamic Link Libraries ( DLLs ) .
To use the feature , you must build a DLL with your preferred language , usually C++ . You need to make the function name that will do the thing exported , so TurboIRC can find and load it . TurboIRC loads exported-by-name functions .
Your function must be exported with the Win32 exporting way ( _stdcall ) as follows ( C Syntax is shown here ) :
extern "C" void _export _stdcall function_name(const char* Input,char* Output)
Extern_Call is the function used with direct call . Extern_Call accepts the module DLL name and the exported function to call . The module does not have to be a DLL file , it can be also an EXE file , or any other executable win32 module ( DRV , SCR etc ) . External_Call pass the InputBuffer to your function . If you wish to pass numbers or something more than a buffer , fill in the buffer with sprintf() . External_Call does not return until your DLL has finished processing. External_Call will then return a string , which will be the same with the Output parameter your function has to return a value . On error , External_Call returns an empty script .
Warning : you must ensure that your DLL function works correct before you attach it to TurboIRC . If your DLL crashes , TurboIRC might crash as well . This TurboIRC function is recommended only for experienced programmers and it should not be used when you can do something using regular scripts .
The TurboIRC.EXE includes a test exported function to use with Extern_Call . You can call it as follows : Extern_Call("TurboIRC.EXE","Test_Extern_Call","MessageTitle") . This displays a message box , that has a message with the "MessageTitle" as the title .
The other external call functions are used when you need to pass a certain handle to the function . For example , you may need your DLL to manipulate a socket connection you 've created with TurboIRC . Using sprintf to the input buffer and passing the handle will have no effect , because handles are only used within the same process - your DLL is an external process . In order to pass a handle ( which may be a file handle , socket handle , etc ) , you need to do the following :
DuplicateHandle 's Inherit mode can be 1 or 0 . 1 means that the new handle is inheritable , 0 means that it is not . If one doesn't work , try the other .
Check your Windows documentation . Don't expect that DuplicateHandle will convert ALL types of handles . TurboIRC calls DuplicateHandle in a way that all possible access will be given to the handle . DuplicateHandle returns 0 if the requested convertion could not be completed .The following calls the Test_Extern_Call with the built-in external call test function of TurboIRC .
Of course , you can get the TurboIRC.EXE handle w/o calling LoadLibrary , because TurboIRC is already running . You can get it with GetGOPTIONS("Instance")
19.Address Book Functions
With Address Book Functions , you can get information from TurboIRC address book to your scripts . Since the address book is saved to an INI file , you can still get the information using INI functions , however TurboIRC provides a simple way with ABGet() .
ABGet accepts a user name ( the same you entered in the "New" dialog of the editor or the name you used with /_ab ) , and returns a string describing :
Note that the string returned from ABGet might have multiple lines inside it .