EQWatcher Evolution > Scripting  > Internet Functions


Introduction

Internet functionality is limited by the user.  If the default options are kept, NO internet functionality is possible.  You cannot change these options using scripts.

Keeping this in mind.  Internet connections use what is called "sockets", which is basically a container for a single connection (think of it like putting a light bulb into a socket).  Each of these sockets is bound to a specific "port", a number used on your computer defining where the connection should go.  For incoming sockets, it will define the port to "listen" on (such as web sites listen on port 80 for HTTP), and for outgoing sockets it simply is an unused connection number.

Each socket used by EQWatcher Evolution must first be created using SockNew, and can be destroyed at any time using SockDestroy.  Each socket defined has a name, port number (this must be unused; for outgoing sockets, use 0 to use a random unused port), and an alias to execute for received data (Explained further down).  Each successfully created socket uses its own thread After this creation, there are two routes to take: incoming or outgoing.

For incoming sockets, use SockListen to define it as a listener.  The port listened on is the port used for SockNew.  For each connection, a new socket is created using the child name used in the SockListen command (a number is added to the end to create a unique socket name).  These children are then equivalent to an outbound socket.  Each time a child is made, the listener socket performs a few functions.  First it executes an alias (which is not executed "immediately" but actually placed in the queue of incoming notes.txt lines) if one has been defined using SockOnChild, using the format "[Alias Name] "[Child Name]"".  Next it sends the first buffered send from the listener socket (since listener sockets have no destination to send SockSend to, you may call SockSend once with data to be sent initially to children automatically).

For outgoing sockets, you may use the SockConnect command to connect to a destination address and port.  As of version 1.15, this command attempts a connection in the background and the script continues.  The "On Connect" callback alias should be defined (see SMTP.EAS for a full example of a socket session).

All incoming data is processed by line.  Each line received executes an alias defined by SockNew (for listener sockets' children, the alias defined in the listener's SockNew is used).  All that is given in SockNew is the name, the final resulting command used is "[Alias Name] "[Receiving Socket Name]" [Data]".  This alias can then process the information as needed.  To check if incoming data is in the queue (for some odd reason), use the SockData command.

All outgoing data is sent using the SockSend command.  This data is buffered and sent ASAP.

Sockets can be disconnected using the SockDisconnect command.

The system of executing aliases on socket events is also known as using "callbacks".  The "On Receive" callback is set in SockNew.  The other callbacks currently used are "On Child", "On Connect", "On Disconnect".  "On Child" has been explained above.  "On Connect" and "On Disconnect" are executed as you would expect them to be, and the form used when executing the aliases is: "[Alias Name] "[Child Name]"".

 EQWatcher Evolution sockets also contain one string, and one integer for use however you wish.  To set them, use SockSetString and SockSetInt.  To retrieve the data, use SockGetString and SockGetInt.  To search all sockets for specific data, and retrieve the first socket name found with that data, you may use SockFromString and SockFromInt.

List of commands


SockConnect, SockConnected, SockData, SockDestroy, SockDisconnect, SockFromInt, SockFromString, SockGetInt, SockGetString, SockListen, SockNew, SockOnChild, SockOnConnect, SockOnDisconnect, SockSend, SockSetInt, SockSetString



The "SockConnect" Command

This command attempts to connect to a specific destination.  Set the "On Connect" callback alias for notification when the socket successfully connects.  If the connection fails, no callback will be used and the socket may sit unused for the rest of the life of the script.  To prevent this, use an inactivity timer to destroy the socket (see SMTP.EAS for full example).

Syntax:

SockConnect([Name],[Address],[Port])


Name: The name of the socket to use.

Address: The address to connect to.  This may be an IP (1.2.3.4), or domain name (www.destination.com).

Port: The port to connect to at the destination address.


Return Value:

This command returns a boolean value (true or false) indicating whether the connection is going to try to connect.


The "SockConnected" Command

This command checks if a socket is connected.

Syntax:

SockConnect([Name])


Name: The name of the socket to use.


Return Value:

This command returns a boolean value (true or false) indicating whether a connection is active.


The "SockData" Command

This command checks if a socket has un-buffered incoming data.

Syntax:

SockData([Name])


Name: The name of the socket to use.


Return Value:

This command returns an integer value indicating the number of bytes waiting to be buffered.


The "SockDestroy" Command

This command destroys this socket

Syntax:

SockDestroy([Name])


Name: The name of the socket to use.



The "SockDisconnect" Command

This command disconnects this socket

Syntax:

SockDisconnect([Name])


Name: The name of the socket to use.



The "SockFromInt" Command

This command finds a socket name based on integer data. 

Syntax:

SockFromInt([Data])


Data: The integer data to search for


Return Value:

The first socket name found with the specified data set as its integer data is returned.


The "SockFromString" Command

This command finds a socket name based on string data. 

Syntax:

SockFromString([Data])


Data: The string data to search for


Return Value:

The first socket name found with the specified data set as its string data is returned.


The "SockGetInt" Command

This command retrieves the integer data from a socket.

Syntax:

SockGetInt([Name])


Name: The name of the socket to use.


Return Value:

The integer data associated with the socket.


The "SockGetString" Command

This command retrieves the string data from a socket.

Syntax:

SockGetString([Name])


Name: The name of the socket to use.


Return Value:

The string data associated with the socket.


The "SockListen" Command

This command sets a socket as a listener on the port used in SockNew.

Syntax:

SockListen([Name],[Child Name])


Name: The name of the socket to use.

Child Name: The name to derive children names from.  A number is placed at the end of this name to create a unique name for each child.


Return Value:

This command returns a boolean value (true or false) indicating whether this operation was successful.


The "SockNew" Command

This command creates a new socket on a specific port.

Syntax:

SockNew([Name],[Port],[On Receive])


Name: The name of the socket to use.

Port: The port number to use, which must not already be in use.  For outgoing sockets, use port 0 to randomly select an unused port.

On Receive: The alias to execute when this socket receives data.  The command is executed as: "[On Receive] "[Name]" [Data]".


Return Value:

This command returns a boolean value (true or false) indicating whether this operation was successful.


The "SockOnChild" Command

This command sets the "On Child" callback for when a specific listener socket receives an incoming connection.

Syntax:

SockOnChild([Name],[On Child])


Name: The name of the socket to use.

On Child: The alias to execute when the listener socket receives an incoming connection.  The command is executed as: "[On Child] "[Child Name]"".



The "SockOnConnect" Command

This command sets the "On Connect" callback for a specific socket.

Syntax:

SockOnConnect([Name],[On Connect])


Name: The name of the socket to use.

On Connect: The alias to execute when this socket connects.  The command is executed as: "[On Connect] "[Name]"".



The "SockOnDisconnect" Command

This command sets the "On Disconnect" callback for a specific socket.

Syntax:

SockOnDisconnect([Name],[On Disconnect])


Name: The name of the socket to use.

On Disconnect: The alias to execute when this socket connects.  The command is executed as: "[On Disconnect] "[Name]"".



The "SockSend" Command

This command sends data through a socket.

Syntax:

SockSend([Name],[Data])


Name: The name of the socket to use.

Data: The string data to send through this socket.  The data is buffered and sent as possible.  If this is a listener socket, the data has no place to go and is not sent (since this is the case, the FIRST SockSend using a listener is sent to each child upon connection).



The "SockSetInt" Command

This command sets integer data associated with a socket

Syntax:

SockSetInt([Name],[Data])


Name: The name of the socket to use.

Data: The integer data to set



The "SockSetString" Command

This command sets string data associated with a socket

Syntax:

SockSetString([Name],[Data])


Name: The name of the socket to use.

Data: The string data to set