Hex namespace - common hub functions

The Hex namespace contains functions that will allow you to obtain information about the hub. And other tasks like sending data to all users and so forth.

• Hex.Broadcast(sData)
• Hex.OpchatMessage(sData)
• Hex.UserCount()
• Hex.GetTopic()
• Hex.SetTopic(sTopic)
• Hex.GetMOTD()
• Hex.SetMOTD(sMotd)
• Hex.Uptime()
• Hex._GetVersion()
• Hex.GetScriptsFolder()
• Hex.Bot()
• Hex.HelpString(iSection, sLanguage)
• Hex.User(iUserId)
• Hex.Right(iUserId)
• Hex.UserCommand()
• Hex.Trigger()
• Hex.Profile(iProfileId)
• Hex.Timer()
• Hex.GetUserID(sNickname)
• Hex.SetAboutString(sAbout)
• Hex.DownloadFile(sUrl, bEncode, sCallback)
• Hex.Execute(sFile, sParameters, sCallback)
• Hex.SendScriptMessage(sReceiver, iMessageCode, sData)
• Hex.GetDefaultLanguage()

Hex.Broadcast(sData)

Sends sData to all clients that is connected to the hub.
This function does not return a value.
Your are prohibited from sending "$ConnectToMe" and "$RevConnectTome"

Parameters:

• sData = The data to broadcast

Hex.Broadcast("<LuaScript> Hello World!|")

Hex.OpchatMessage(sData)

Posts a message to OpChat.
This function does not return a value.

Parameters:

• sData = The message to show in opchat

Hex.OpchatMessage("Hi there operators!")

Hex.UserCount()

This function returns the number of connected users.

local iUsercount = Hex.UserCount()

Hex.GetTopic()

This function returns the current hub topic.

local sTopic = Hex.GetTopic()

Hex.SetTopic(sTopic)

This function sets the hub topic.
This function does not return a value.

Parameters:

• sTopic = A string with the new topic.

Hex.SetTopic("This hub is powered by Hex Script")

Hex.GetMOTD()

This function returns the current MOTD (message of the day).

local sMotd = Hex.GetMOTD()

Hex.SetMOTD(sMotd)

Sets the MOTD (message of the day).
This function does not return a value.

Parameters:

• sMotd = A string with the new MOTD.

Hex.SetMOTD("Welcome to my hub")

Hex.Uptime()

This function returns the hubs uptime in seconds.

local iUptime = Hex.Uptime()

Hex._GetVersion()

This function returns a string with the version of hexhub.

local sVersion = Hex._GetVersion()

Hex.GetScriptsFolder()

This function returns the path to the scripts directory.

local sFolder = Hex.GetScriptsFolder()

Hex.Bot()

This function returns a new object of type Bot
For more information read the Bot class section.

mybot = Hex.Bot()

Hex.HelpString(iSection, sLanguage)

This function returns a new object of type HelpString (shown in !help).
The HelpString class is initialized with two parameters.

• iSection: 0 = Hub information, 1 = Commands for messages, 2 = Operator commands, 3 = reserved, 4 = Profile management, 5 = DC++ commands, 6 = Extra
• sLanguage: a 2-letter language identifier (e.g. "EN", "RO", "DE", ect.).

For more information read the HelpString class section.

myhelpstring = Hex.HelpString(0, "EN")

Hex.User(iUserId)

This function returns a new object of type User.

To iterate through all users connected to the hub use a value of -1 when initializing the object (Hex.User(-1)).
The object returned will be set to the first user found. User:GetUserID will return -1 if no users were found

• iUserId = Identifier of the user you wish to associate with this object.

For more information read the User class section.

local usr = Hex.User(iUserId)

Hex.Right(iUserId)

This function returns a new object of type Right.

• iUserId = Identifier of the user you wish to associate with this object.

For more information read the Right class section.

local usrrights = Hex.Right(iUserId)

Hex.UserCommand()

This function returns a new object of type UserCommand.
For more information read the UserCommand class section.

usercommand = Hex.UserCommand()

Hex.Trigger()

This function returns a new object of type Trigger.
For more information read the Trigger class section.

mytrigger = Hex.Trigger()

Hex.Profile(iProfileId)

This function returns a new object of type Profile.

To iterate through all account profiles use a value of -1 when initializing the object (Hex.Profile(-1)).
The object returned will be set to the first profile found.

• iProfileId = a profile identifier returned by User:GetProfileID

For more information read the Profile class section.

local profile = Hex.Profile(User:GetProfileID())

Hex.Timer()

This function returns a new object of type Timer.
For more information read the Timer class section.

mytimer = Hex.Timer()

Hex.GetUserID(sNickname)

This function returns the identifier of a user. If the use was not found it returns -1.
For more information read the Hex.User(iUserId) section.

Parameters:

• sNickname = the nickname of the user to find a user identifier for

local iUserId = Hex.GetUserID("nickname")
if iUserId == -1 then
	-- not found
end

Hex.SetAboutString(sAbout)

This function sets the copyright text shown in !about trigger

Parameters:

• sAbout = your name and the year, max length = 50, forbidden chars = "\n"

Hex.SetAboutText("Surname Lastname, 2007-2008")

Hex.DownloadFile(sUrl, bEncode, sCallback)

This function starts a asynchronous http/ftp file download operation.
When a asynchronous operation has successfully been initiated there is no way to cancel it

WARNING: If hexhub is closed or the plugin is reinited or unloaded while there is outstanding asynchronous operations, then the plugin will refuse to unload before each and every asynchronous operation has completed. However when the plugin is stopped it will signal all its worker threads to abort execution, and then wait until they all have terminated. Asynchronous downloads may be slower to abort under certain circumstances, for example if the plugin is reading data from a webserver that stopped responding or is slow, the abort signal will not be checked before the read operation completed or timed out! For asynchronous execution of a application, then the plugin will forcefully terminate the execution of the application!

Parameters:

• sUrl = a URL specifying what and where to download (e.g. http://domain.com/path/file.zip).
• bEncode = determines whether or not HexScript should canonicalize sUrl.
• sCallback = a string specifying what function to call when the asynchronous operation has completed.

Return values:

• -4 this operation is not allowed by the hub owner.
• -3 failed to encode url or its invalid (if the DNS lookup failed, the url is considered invalid).
• -2 the thread pool is exhausted.
• -1 the queue for asynchronous operations is full, try again later.
• 0 general error such as out of memory, bad parameters, ect.
• 1 the asynchronous operation was successfully initiated.

Callback:

-- if iSuccess == 1 then success else error
-- The if the callback returns true the downloaded file will be deleted.
function FileDownloaded(iSuccess, sFilename)
	return true
end

Example:

if Hex.DownloadFile("http://domain.com/path/file.ext", true, "FileDownloaded") ~= 1 then
	print("Could not download file!")
end

function FileDownloaded(iSuccess, sFilename)
	if iSuccess == 1 then
		print("download completed: "..sFilename)
	else
		print("download failed!")
	end
	
	return true
end

Hex.Execute(sFile, sParameters, sCallback)

This function starts a asynchronous execute operation.
When a asynchronous operation has successfully been initiated there is no way to cancel it

WARNING: If hexhub is closed or the plugin is reinited or unloaded while there is outstanding asynchronous operations, then the plugin will refuse to unload before each and every asynchronous operation has completed. However when the plugin is stopped it will signal all its worker threads to abort execution, and then wait until they all have terminated. Asynchronous downloads may be slower to abort under certain circumstances, for example if the plugin is reading data from a webserver that stopped responding or is slow, the abort signal will not be checked before the read operation completed or timed out! For asynchronous execution of a application, then the plugin will forcefully terminate the execution of the application!

The asynchronous executer offers scripters to do more time consuming operations. You could download the lua binaries console interpreter and execute your time consuming script without having to worry about locking up HeXHub.

Parameters:

• sFile = a fully qualified path to the file to execute.
• sParameters = the command line parameters
• sCallback = a string specifying what function to call when the asynchronous operation has completed.

Return values:

• -4 this operation is not allowed by the hub owner
• -3 the file does not exist.
• -2 the thread pool is exhausted.
• -1 the queue for asynchronous operations is full, try again later
• 0 general error such as out of memory, bad parameters, ect.
• 1 the asynchronous operation was successfully initiated.

Callback:

-- iExitCode = the exit code of the program, or -1 on error executing
-- if the callback returns true the output dumpfile (console output) will be deleted.
function ExecuteCompleted(iExitCode, sFilename)
	return true
end

Example:

if Hex.Execute("C:\\file.exe", "", "OnExecuted") ~= 1 then
	print("Could not execute file!")
end

function OnExecuted(iExitCode, sFilename)
	if iExitCode ~= -1 then
		print("File was executed, output is in: "..sFilename)
	else
		print("Execute failed!")
	end
	
	-- read file with output from this program
	
	-- true == delete file
	return true
end

Hex.SendScriptMessage(sReceiver, iMessageCode, sData)

This function schedules a message to be sent to another script, but it offers no guarantee that the message is delivered.
If you need to get notification of delivery the receiver script can send you a message back.
The message is delivered by the same thread pool as used for asynchronous operations, if the thread pool is exhausted or max_async is exceeded the message is not sent.
The receiving script has to have The OnScriptMessage(iMessageCode, sSender, sData) callback

Parameters:

• sReceiver = The filename of the script that will receive the message; Hex.GetScriptsFolder() + "filename.lau".
• iMessageCode = a number of your choice to send to the receiver.
• sData = a message of your choice to send to the receiver.

Example sender script:

-- File: ScriptA.lua

mytimer = Hex.Timer()
mytimer:Start(1000, 1000, "MyTimerProc")

function MyTimerProc(iTimerId)
	Hex.SendScriptMessage(Hex.GetScriptsFolder().."ScriptB.lua", 1, "Hello script B")
end

Example receiving script:

-- File: ScriptB.lua
function OnScriptMessage(iMessageCode, sSender, sData)
	print("Message recived from: "..sSender.." with message code: "..iMessageCode.." Message: "..sData)
end

Hex.GetDefaultLanguage()

This function returns a 2-letter language code specifying the default language of the hub.

local slang = Hex.GetDefaultLanguage()

---