/MEng/System/Runtime/DGramSocket

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

MEng.System.Runtime.DGramSocket is a derivative of the Socket class. This derivative creates a datagram style socket, as apposed to a stream socket. The operations available for stream and datagram sockets are different, so they have separate classes to enforce these differences. Datagram sockets are message oriented, i.e. one side sends a packet and it arrives at the other side as a coherent block of bytes, as apposed to stream sockets where the data arrives in an undifferentiated stream of bytes, with no indication as to how the bytes were sent.

 

Constructors:

Constructor();

There is just a default constructor available. You must set up the socket by binding it to a local end point before using it. Datagram sockets are not connected like a stream socket, so you only bind them.

 

Final, Non-Const Methods:

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

Binds the socket to a local end point, allowing 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.

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.

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

This method will read a datagram packet from the socket, waiting up to WaitMillis milliseconds for the packet to arrive before giving up. If the packet doesn't arrive in the time indicated, the return is zero, to indicate nothing read. If a packet does arrive, the return indicates the size of the packet.

If the passed memory buffer's maximum size is not sufficient to hold the packet, a SocketErrors.DGramBufToSmall exception will be thrown. Be careful though, because this method will allocate the buffer up to the ToRead size, so don't set the buffer max to some ridiculous value and set ToRead to that value, because it will allocate the buffer up to that size. Datagram packets are limited in size anyway, so set it to some reasonable size, such as 32K and that should hold any legal datagram packet. 

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.

If the socket is not yet bound, you will get a SocketErrors.NotBound exception. If the read fails for some reason, you will get one of the SocketErrors that can cause this type of read operation to fail.

SendTo
(
    [In] MEng.System.Runtime.IPEndPoint TarEP
    , [In] MEng.System.Runtime.MemBuf ToSend
    , [In] MEng.Card4 ToSend
) Returns MEng.Card4;

This method will send a datagram packet from this socket to the target end point. It sends ToSend bytes from the passed memory buffer. it returns the number of bytes actually sent. The socket must be bound locally before you call this or a SocketErrors.NotBound exception will be thrown. If the write fails, you will get a SocketErrors.WriteErr exception.

SendWOL([In] MEng.String MACAddr);

This method will send a 'Wake on LAN' message to the indicated MAC address. Some computers support the wake on LAN protocol and can be awakened remotely via this mechanism. The MAC address is a set of 6 binary bytes represented as two character pairs. It can be all smashed together, such as "112233445566" or it can be separated by either spaces or hyphens, such as "11:22:33:44:55:66" or "11-22-33-44-55-66". Any byte that is less than 0x10 should use a leading zero, such as "01-02-03-04-05-06".

Note that this will cause an implicit call to SetAllowBroadcasts(), below, since broadcasts must be enabled on a datagram socket to send this kind of broadcast. So this will be enabled if it was not already, and that might cause different behavior if you continue to use this socket and weren't expected broadcasts to be enabled.

SetAllowBroadcasts([In] MEng.Boolean ToSet);

This method enable or disable broadcasts on this datagram socket. By default they will be disabled. You must enable this option to send or receive datagram broadcasts on this socket.