UDP (datagram) manager.
class UDPSocket( addrOrService, [service] ) \ from Socket
remote | Contains the origin address of the last datagram received with the method |
remoteService | Contains the origin port of the last datagram received with the method |
broadcast() | Activates broadcasting and multicasting abilities on this UDP socket. |
recv() | Reads incoming data. |
sendTo() | Sends a datagram to a given address. |
UDP (datagram) manager.
The UDPSocket class provides support for UDP transmissions (datagrams).
The constructor reserves the needed system resources and return an UDPSocket object that can be used to send and receive datagrams.
Contains the origin address of the last datagram received with the method
Contains the origin port of the last datagram received with the method
Activates broadcasting and multicasting abilities on this UDP socket.
UDPSocket.broadcast( )
Raises: |
|
This is provided as a method separated from the socket constructor as, on some systems, this call requires administrator privileges to be successful.
Reads incoming data.
UDPSocket.recv( bufOrSize, [size] )
bufOrSize | A pre-allocated buffer to fill, or a maximum size in bytes to be read. | ||
size | Maximum size in bytes to be read. | ||
Returns: | If bufOrSize is a size, returns a filled string buffer, otherwise it returns the amount of bytes actually read. | ||
Raises: |
|
This method works as the TCPSocket.recv method, with the only difference that the incoming datagram is always completely read, provided that the specified size is enough to store the data.
Also, the UDPSocket.remote and UDPSocket.remoteService properties of the receiving object are filled with the address and port of the host sending the packet.
When the bufOrSize parameter is a buffer to be filled (i.e. a MemBuf or a string created with strBuffer), the buffer may be repeatedly used, sparing memory and allocation time. If the size parameter is not provided, the maximum amount of bytes that can be stored in the buffer will be used as read size limit,
This size won't change between call, even if the actual length of the data stored in the buffer changes.
If the size parameter is provided, it is used to define the maximum possible size of data stored in the buffer. If it is not great enough to store the data, it is resized.
When a target buffer is specified in the bufOrSize parameter, the method returns number of bytes that has been actually read. The size may be zero if the opposite side closed the connection, or if the timeout has elapsed. The returned size will presumably be smaller than the maximum, and it will be at maximum the size of a TCP packet that can travel on the current connection.
When a maximum size is specified in the bufOrSize parameter, the method returns a newly allocated buffer on success, and nil on failure.
In case of system error, a NetError is raised.
Sends a datagram to a given address.
UDPSocket.sendTo( host, service, buffer, [size], [start] )
host | Remote host where to send the datagram. | ||
service | Remote service or port number where to send the datagram. | ||
buffer | The buffer to be sent. | ||
size | Amount of bytes from the buffer to be sent. | ||
start | Begin position in the buffer. | ||
Raises: |
|
This method works as the TCPSocket.send method, with the main difference that the outgoing datagram can be directed towards a specified host, and that a whole datagram is always completely filled before being sent, provided that the specified size does not exceed datagram size limits.
The host parameter may be an host name to be resolved or an address; if the UDPSocket.broadcast method has been successfully called, it may be also a multicast or broadcast address.
The service parameter is a string containing either a service name (i.e. "http") or a numeric port number (i.e. "80", as a string).
The buffer may be a byte-only string or a byte-wide MemBuf; it is possible to send also multibyte strings (i.e. strings containing international characters) or multi-byte memory buffers, but in that case the sent data may get corrupted as a transmission may deliver only part of a character or of a number stored in a memory buffer.
If a size parameter is not specified, the method will try to send the whole content of the buffer, otherwise it will send at maximum size bytes. If a start parameter is specified, then the data sent will be taken starting from that position in the buffer (counting in bytes from the start).
This is useful when sending big buffers in several steps, so that it is not necessary to create substrings for each send, sparing both CPU and memory.
The returned value may be 0 in case of timeout, otherwise it will be a number between 1 and the requested size. Programs should never assume that a succesful sendTo has sent all the data.
In case of error, a NetError is raised.