Aztec® Programming Language
Version 1.1 Alpha 2

Copyright © 2010-2017, Aztec Development Group, All Rights Reserved

Download Aztec

Search        Contact Us

And I'm here to remind you...

Of the mess you left when you went away.

- Alanis Morissette

 

aztec.io.ClientSocket

public class ClientSocket from<Socket>

Base

Socket

ClientSocket

aztec.io.IClientSocket

public class abstract IClientSocket from<Base>

Base

IClientSocket

The ClientSocket class provides a socket based point-to-point communication object. It is created by a client application and used to Connect() to a server application on a specific port. It is also created by the server application when an incoming connection request is accepted. The ClientSocket is then created and attached to the remote application which performed the request.

 

The two applications then communicate back and forth using a ClientSocket object on each side. Each ClientSocket object automatically creates an internal SocketStream object and ties it to one end of the socket. The SocketStream object is then used to perform the binary I/O to and from the remote application.

 

Each SocketStream.Write() call results in a separate message being sent to the remote application, and each separate message received results in the SocketReceive handler being executed. The code in the SocketReceive handler can then read the data using one or more Read() calls.

 

♦ A socket message can be read using a single SocketStream.Read() call to read the data into a Stream (memory, file, etc), and then one or more separate StreamIO.Read() calls can be made against the stream to retrieve the data.
♦ Or a socket message can be read using multiple calls directly against the socket stream to retrieve the data.

The socket stream supports asynchronous communication, and can queue up multiple incoming messages to be processed, depending on how the logic on each side of the socket is being handled. Synchronous communication needs to be coded into the application.

 

♦ Each separate message received results in a separate call to the SocketReceive handler. As described above, that handler can read the data in a single socket message using one or more SocketStream.Read() method calls.
♦ When all data is read from a single message, the socket stream automatically positions the stream pointer to the start of the next message. A single SocketStream.Read() call can not span from one message into the next message. A SocketException will be fired in this case.

Note that there are currently several limitations of this client socket class which will be addressed in the near future during the port to Linux.

 

♦ This class currently does not support "blocking".
♦ It does not automatically handle byte-order differences between end points of the socket.
♦ It does not support multibyte character strings.

The IClientSocket class is an abstract interface class which contains a virtual event handler method for each of the events which the ClientSocket class supports.

ClientSocket Methods

ClientSocket() Constructor for the ClientSocket class
Stream() Returns reference to the internal SocketStream object
Connect() Connects this client socket to a socket in a remote application using an IP address
Close() Method to close the client socket and send notification to remote client connection
AddSocketReceiveHandler() Registers an event handler for processing an incoming message using a method reference
AddSocketReceiveHandler() Registers an event handler for processing an incoming message using an IClientSocket reference
AddSocketCloseHandler() Registers an event handler for processing a remote socket close event using a method reference
AddSocketCloseHandler() Registers an event handler for processing a remote socket close event using an IClientSocket reference
OnSocketReceive() Virtual method to handle SocketReceiveEvent - can be overridden
OnSocketClose() Virtual method to handle SocketCloseEvent - can be overridden

IClientSocket Methods

OnSocketReceive() Virtual method to handle SocketReceiveEvent
OnSocketClose() Virtual method to handle SocketCloseEvent

Derived Classes

See Also

 


ClientSocket()

public method ClientSocket()

Parameters

None

Return Value

None

Description

Constructor for the ClientSocket class.

 

ClientSocket Class


Stream()

public method<SocketStream> Stream()

Parameters

None

Return Value

Socket stream used for communication

Description

This method returns the SocketStream object which this class maintains for communication with the remote application. Writing to the stream sends a message to the remote application, and reading from the stream reads part or all of an incoming message from the remote application. A read operation should normally be performed within the context of handling a SocketReceiveEvent.

 

This socket stream object is created internally when a valid connection is made with the remote application. When a server socket accepts an incoming connection, it creates a client socket and automatically connects the client socket to the remote app. The socket stream is created during this process and is attached to the client socket object. When the client socket is manually created by the user, the socket stream is automatically created and attached to the client socket object once a successul Connect() call is made.

 

In both cases, this method will return null until a valid connection is made.

 

ClientSocket Class


Connect()

public method<bool> Connect(string IPAddress, int PortNumber, int TimeOutValue = 5000)

Parameters

IPAddress

IP Address of remote computer

PortNumber

Port number on remote computer to connect to

TimeOutValue

Amount of time to wait before giving up (milliseconds)

Return Value

True if successful and false if can't connect

Description

This method attempts to connect to a "listening" socket in a remote application. That remote socket can be an Aztec ServerSocket object, or it can be any other standard socket object listening on the specified port. The IP address, the port number and a timeout value are specified.

 

The method returns true if it is able to successfully connect with the remote application and false if it cannot connect.

 

ClientSocket Class


Close()

public method Close()

Parameters

None

Return Value

None

Description

This method closes the client socket connection. If the socket was currently connected to a remote application, the remote application receives a notification that the socket was closed on this end. No I/O can be performed using this object until another successful Connect() operation is performed.

 

It is possible to set up event handlers for remote Close operations in the ClientSocket class.

 

ClientSocket Class


AddSocketReceiveHandler()

public method AddSocketReceiveHandler(SocketReceiveHandler Handler, Base ExtraObject = null)

Parameters

Handler

Method reference to be executed when the event occurs

ExtraObject

Optional object which will be sent along to each event handler when it is executed

Return Value

NONE

Description

This method registers a method reference to be executed when a message is received from the remote socket that it is connected to. An optional object can also be registered which will be sent to each event handler as it is executed.

 

The event handler should then read the data from the socket stream.

 

As is true with all Aztec event handling, this method can be called by any thread. When the event occurs, each registered event handler is scheduled to execute within the thread that registered it. So an event sent to one thread can be handled by event handlers executing in one or more other threads.

 

The SocketReceiveHandler data type represents a method reference specific to a handler for SocketReceiveEvent. SocketReceiveHandler is defined as follows:

 

        public type<method<SocketReceiveEvent,Base>> SocketReceiveHandler

 

Given this definition, the method handler must be defined with the following signature (name can be anything):

 

        public method SocketReceiveMethod(SocketReceiveEvent event, Base Extra) { }.

 

ClientSocket Class


AddSocketReceiveHandler()

public method AddSocketReceiveHandler(IClientSocket Interface, Base ExtraObject = null)

Parameters

Interface

Reference to an IClientSocket object

ExtraObject

Optional object which will be sent along to each event handler when it is executed

Return Value

NONE

Description

This method registers an IClientSocket interface object to be executed when a socket message is received from the remote application. An optional object can also be registered which will be sent to each event handler as it is executed.

 

As is true with all Aztec event handling, this method can be called by any thread. When the event occurs, each registered event handler is scheduled to execute within the thread that registered it. So an event sent to one thread can be handled by event handlers executing in one or more other threads.

 

When a socket message is received, the OnSocketReceive() method within the Interface object will be executed.

 

ClientSocket Class


AddSocketCloseHandler()

public method AddSocketCloseHandler(SocketCloseHandler Handler, Base ExtraObject = null)

Parameters

Handler

Method reference to be executed when the event occurs

ExtraObject

Optional object which will be sent along to each event handler when it is executed

Return Value

NONE

Description

This method registers a method reference to be executed when the socket connnection is closed by the remote application. An optional object can also be registered which will be sent to each event handler as it is executed.

 

As is true with all Aztec event handling, this method can be called by any thread. When the event occurs, each registered event handler is scheduled to execute within the thread that registered it. So an event sent to one thread can be handled by event handlers executing in one or more other threads.

 

The SocketCloseHandler data type represents a method reference specific to a handler for SocketCloseEvent. SocketCloseHandler is defined as follows:

 

        public type<method<SocketCloseEvent,Base>> SocketCloseHandler

 

Given this definition, the method handler must be defined with the following signature (name can be anything):

 

        public method SocketCloseMethod(SocketCloseEvent event, Base Extra) { }.

 

ClientSocket Class


AddSocketCloseHandler()

public method AddSocketCloseHandler(IClientSocket Interface, Base ExtraObject = null)

Parameters

Interface

Reference to an IClientSocket object

ExtraObject

Optional object which will be sent along to each event handler when it is executed

Return Value

NONE

Description

This method registers an IClientSocket interface object to be executed when the socket connnection is closed by the remote application. An optional object can also be registered which will be sent to each event handler as it is executed.

 

As is true with all Aztec event handling, this method can be called by any thread. When the event occurs, each registered event handler is scheduled to execute within the thread that registered it. So an event sent to one thread can be handled by event handlers executing in one or more other threads.

 

When the connection is closed by the remote application, the OnSocketClose() method within the Interface object will be executed.

 

ClientSocket Class


OnSocketReceive()

public method virtual OnSocketReceive(SocketReceiveEvent MsgEvent, Base ExtraObject)

Parameters

MsgEvent

SocketReceiveEvent object associated with the event

ExtraObject

Optional object sent along from when it was registered

Return Value

NONE

Description

This method is the default event handler for SocketReceiveEvent within the client socket. It is invoked internally as a result receiving a message from the remote socket. This method in turn executes every registered handler with the same argument list which comes in. Both implementations of the ClientSocket.AddSocketReceiveHandler() method register the event handlers which get invoked by this method.

 

If this method is overridden by a class derived from ClientSocket, it must call this implementation of the method if it needs to execute handlers registered with the ClientSocket.AddSocketReceiveHandler() methods.

 

ClientSocketClass


OnSocketClose()

public method virtual OnSocketClose(SocketCloseEvent CloseEvent, Base ExtraObject)

Parameters

CloseEvent

SocketCloseEvent object associated with the event

ExtraObject

Optional object sent along from when it was registered

Return Value

NONE

Description

This method is the default event handler for SocketCloseEvent within the client socket. It is invoked internally if the remote application that it is connected to closes the socket on the remote side. This method in turn executes every registered handler with the same argument list which comes in. Both implementations of the ClientSocket.AddSocketCloseHandler() method register the event handlers which get invoked by this method.

 

If this method is overridden by a class derived from ClientSocket, it must call this implementation of the method if it needs to execute handlers registered with the ClientSocket.AddSocketCloseHandler() methods.

 

ClientSocketClass


OnSocketReceive()

public method virtual OnSocketReceive(SocketReceiveEvent MsgEvent, Base ExtraObject)

Parameters

MsgEvent

SocketReceiveEvent object associated with the event

ExtraObject

Optional object sent along from when it was registered

Return Value

NONE

Description

This virtual method is the event handler for a SocketReceiveEvent within the IClientSocket interface class. The method which overrides it is invoked for a SocketReceiveEvent within a ClientSocket object when the interface object is registered with the ClientSocket.AddSocketReceiveHandler() method.

 

IClientSocket Class


OnSocketClose()

public method virtual OnSocketClose(SocketCloseEvent MsgEvent, Base ExtraObject)

Parameters

CloseEvent

SocketCloseEvent object associated with the event

ExtraObject

Optional object sent along from when it was registered

Return Value

NONE

Description

This virtual method is the event handler for a SocketCloseEvent within the IClientSocket interface class. The method which overrides it is invoked for a SocketCloseEvent within a ClientSocket object when the interface object is registered with the ClientSocket.AddSocketCloseHandler() method.

 

IClientSocket Class

 

Copyright © 2010-2017

Aztec Development Group

All Rights Reserved

Download Aztec