/MEng/System/Runtime/StreamSocket

ClassPath:	MEng.System.Runtime.StreamSocket
Parent ClassPath:	MEng.System.Runtime.Socket
Copyable:	No
Final:	Yes

MEng.System.Runtime.StreamSocket is a derivative of the Socket class. This derivative creates a stream style socket, as apposed to a datagram socket. The operations available for stream and datagram sockets are different, so they have separate classes to enforce these differences.

 

Constructors:

Constructor();

There is just a default constructor available. You must set up the socket by binding it locally and connecting it to some remote end point before using it.

 

Final, Const Methods:

GetIsConnected() Returns MEng.Boolean;

Returns a boolean value that indicates whether this socket is connected or not. This may be because it has not been connected at all, or because the other side has closed.

Final, Non-Const Methods:

Close();

Closes the socket, which will cause a shutdown and unbind of the socket locally. After this the socket can be reconnected to a new remote address.

DefBindLocal([In] MEng.System.Runtime.Socket.SockProtos ProtoToUse);

Binds the socket to a local end point, allow it to chose the port and address. When creating a client side socket, this is usually fine, since it doesn't usually matter what port is used on the client side, and the local host address will be chosen automatically. One gotcha might be if the host is multi-homed (connected to multiple networks), in which case you might have to use BindLocal() to select a specific local address. If the socket is already bound, you will get a SocketErrors.AlreadyBound exception.

Normally though, you'll just do a Connect call and allow the system to do the default binding as part of the connection process. This is safer since the system then knows the target address and can better chose the correct network connection to use.

BindLocal
(
    [In] MEng.System.Runtime.Socket.SockProtos ProtoToUse
    , [In] MEng.Card4 PortNum
);

Binds the socket to a local end point with a specific port. It will choose the local address, which would only be a problem if the local host was multi-homed (connected to multiple networks) and a specific local address must be used. If the socket is already bound, you will get a SocketErrors.AlreadyBound exception.

It is not recommended that you do local binding unless you have a very clear reason for doing do. Instead, just allow the binding to be done for you by the system, during the Connect() call. The system will find the right local network adaptor for the target addressing.

Connect
(
    [In] MEng.System.Runtime.Socket.SockProtos ProtoToUse
    , [In] MEng.System.Runtime.IPEndPoint RemoteEP
);

This method will connect this socket to a remote end point, indicated by the passed end point, setting it up for the indicated protocol. If the connection cannot be made, you will get one of a number of possible exceptions (from Socket.SocketErrs) that can cause this failure. If the socket is already connected, a SocketErrors.AlreadyConn exception will be thrown.

If the socket is not bound, it will be bound for you. It is recommended that you let the system do the local bind for you, since it will be better at doing the right thing.

ReadBuffer
(
    [Out] MEng.System.Runtime.MemBuf ToFill
    , [InOut] MEng.Card4 WaitMillis
    , [In] MEng.Card4 ToRead
) Returns MEng.Card4;

This method will read up to ToRead bytes from the socket, into the ToFill buffer. It will wait for up to WaitMillis milliseconds for ToRead bytes to arrive. It will return as soon as it gets the requested number of bytes. Else, once the wait period is done, it will return with however many bytes it got, returning that count.

Note that the wait parameter is an in/out. The reason for this is that it will return the amount of time that it didn't use up. This is often used by applications that want to do successive read operations until some time is used up. So it can continue to pass the same value into, getting back what's left, which is passed in again next time, and so on.

The socket must be connected (which also implies that it is bound) or you will get a SocketErrors.NotConn exception. If the read fails, you will get one of a number of SocketErrors exceptions that can cause such a read failure.

ReadByte
(
    [Out] MEng.Card1 ToFill
    , [InOut] MEng.Card4 WaitMillis
) Returns MEng.Boolean;

This method will wait for up to WaitMillis milliseconds for a byte to arrive from the remote end point. It is a convenience method, since the same thing could be done with ReadBuffer. But for those applications which do a form of state machine to read input, it is often convenient to get input one byte at a time. If the byte arrived, the return is True, else it is False.

Note that the wait parameter is an in/out. The reason for this is that it will return the amount of time that it didn't use up. This is often used by applications that want to do successive read operations until some time is used up. So it can continue to pass the same value into, getting back what's left, which is passed in again next time, and so on.

The socket must be connected or you will get a SocketErrors.NotConn exception. If the read fails, you will get one of a number of SocketErrors exceptions that can cause such a read failure.

SetNagle([In] MEng.Boolean ToSet);

This method will enable or disable Nagle processing on this stream socket. See a TCP/IP reference for a description of the Nagle algorithm and whether you would need it or not. It is enabled by default on most platforms.

Shutdown();

This method will do a standard 'polite' shutdown of the socket, which will let the other side know that the shutdown is happening, will pull any waiting data out of the socket and discard it, and then close the socket gracefully.

If you are not connected, this method will just do nothing, so it is safe to call without worrying about whether you are actually connected or not. If the shutdown fails for some other reason, you will get the SocketErrors.ShutdownErr exception.

WriteBuffer
(
    [In] MEng.System.Runtime.MemBuf ToSend
    , [In] MEng.Card4 ToWrite
);

This method will send ToWrite bytes from the ToFill buffer. Failure to send all the bytes is considered an error and the SocketErrors.WriteErr exception will be thrown, so it doesn't need to return the bytes written.

The socket must be connected or you will get a SocketErrors.NotConn exception. If the read fails, you will get one of a number of SocketErrors exceptions that can cause such a read failure.