pnet

>Psychtoolbox>PsychHardware>iViewXToolbox>tcp_udp_ip

PNET - IO-function for TCP and UDP comunation in matlab.

This function can be called with different options/commands to operate on  
tcp/udp/ip connection in matlab. It supports data transfer with  
different data types and byte orders. The function is implemented as an  
MEX-file that needs to be   

General syntax

   pnet('command',....)          or         pnet command  ....  
  
   ppet(con,'command',....)      or         pnet con command ....  
  
   ...where 'command' is a string specifying what to do. "con" is an   
   connection handler holding a number that refers to an already open  
   connection/socket. In the cases where "con" is specified before  
   'command' is the commands associated to operate on that connection/  
   socket. Connection handler number (and some other numbers like size  
   values) can be specified as either a scalar value or a string  
   containing the scalar number.  

Commands for TCP connections

con=pnet(‘tcpconnect’,’hostname’,port)

Creates tcp/ip connection to the specified 'hostname' and port. On error  
it returns -1, on success it returns a conection handler as an integer  
number \>=0. This function call is used to act as a "tcp-client".  
This function is alway nonblocking unless their is some troubles with  
namelookup that can block interpretation for a while.  

sockcon=pnet(‘tcpsocket’,port)

Creates a local tcpsocket and bind port-number "port" to it. On fail  
it rerurns -1, on success it returns a connection handler. To fetch  
remote connection connecting to this socket use pnet(sockcon,'tcplisten')  

con=pnet(sockcon,’tcplisten’, [‘noblock’] )

If some remote tcp-connection has connected to the socket "sockcon" this  
functions returns a handler to that tcp connection. On non available  
remote connection or error it returns -1. Unless the option 'noblock' is  
specified or the readtimeout value (default to inf ) is reached it blocks  
until a remote connection is established.  

elements=pnet(con,’write’, data [,swapping])

Writes all elements of the matlab array "data" to connection "con".   
Supported datatypes are: char, double, single, int8 int16, int32,  
uint8, uint16  and uint32. Arrays of datatype char is written as single  
bytes, all other datatypes are written as it matlabsize. By default   
the bytes are swapped to network byte order unless the swapping option  
is specified. Swapping options:  
'native'  no swapping use the computers native byte order.  
'swap'    allways swap byte order.  
'network' uses network byte order (little endian) and it is default.  
'intel'   use intel [CPUs](CPUs) byte order (big endian).  
This operation blocks until writetimeout (is by default inf) is reached  
or all elements are transfered. Returns number of elements successfull  
written.       
This command can also be used with UDP packets, se the UDP section.  

pnet(con,’printf’, ‘format’,…..)

Prints a formated string to the connection "con". SPRINTF is used to  
process format string and following arguments. Se help on SPRINTF for more  
information. It block until writetimeout and returns number of characters  
succesfull written.  
This command can also be used with UDP packets, se the UDP section.  

data=pnet(con,’read’ [,size] [,datatype] [,swapping] [,’view’] [,’noblock’])

Reads an array of elements from a connection. Unless option 'noblock' is  
used the operation blocks until timeout is reached (by default inf), the  
specified "size" is reached or the connection is disconnected by peer.  
Specified "size" (by default 65536) can be a scalar or a vector of  
specifying dimentions length for the multidimentional array to read.  
If size is a scalar i.e. [10] it return 0 to 10 elements in a rowvector  
depening on available elements. If size is a vector i.e. [1 10] or [5 5 5]  
it returns an array if all elements is available, if not, an empty array  
is returned. The datatype option is a string containing the name of the  
datatype, if not specified its by default 'char'. Supported datatypes is  
the same as for the 'write' command.  The option named "swapping" is  
is the same for the 'read' command. The option 'view' gives an "preview"  
of whats available, all data is left in the read buffer. In combination  
with 'noblock' this is a powerfull command to check how much and whats  
available at the moment without blocking.  
This command can also be used with UDP packets, se the UDP section.  

str=pnet(con,’readline’ [,limitsize] [,’view’] [,’noblock’])

This commands works like 'read' but it reads a string of characters  
until the newline character (code=10) are reached.  
It returns the string without the newline character (or if exist just  
before, the carage return character code=13 ). If the character line  
is longer then the "limitsize" the line is splited at that length.  
The default value for limitsize is 65536.  
The function blocks unless a full line of characters are available or  
'noblock' is specified until readtimeout is reached. The 'view'  
option also leaves the returned characters in the read buffer.  
This command can also be used with UDP packets, se the UDP section.  

ret=pnet(con,’readtofile’,’filename’[,bytes][,’view’][,’noblock’][,’append’])

Reads data of specified number of "bytes" to a file 'filename'. It  
returns successful number of bytes moved from the connection to the file.  
If the option string 'append' is specified the data will be appended  
th the end of the file, otherwise the file will be overwritten.  
'view', 'noblock' and timeout behaves as earlier described for read  
operations.  
This command can also be used with UDP packets, se the UDP section.  

ret=pnet(con,’writefromfile’,’filename’[[,start] ,len])

Read data from a file and write it on the connection. All of the  
file will be transmitted of not "start" and "len" specifies a segment.  
The function returns -1 on fail.  
This command can also be used with UDP packets, se the UDP section.  

stat=pnet(con,’status’)

This returns a number telling about the status of a connection/socket.  
It is a different number for each type of connection or socket se  
\#define's in top of pnet.c. The most important status is when  
peer has disconnect the status value is 0 else it is \>0.  
This command can also be used with UDP packets, se the UDP section.  

stat=pnet(con,’setreadtimeout’,sec)

The value "sec" specifies how long read and listen commands blocks before  
it timeouts. The unit is seconds specified as a floting point which means  
that i.e. 0.1 can be specified for a maximum of 0.1 seconds blocking.  
Setting readtimeout to 0 is the same as adding the 'noblock' option to  
all followinging 'read' or 'listen' calls.   
This command can also be used with UDP packets, se the UDP section.  

stat=pnet(con,’setwritetimeout’,sec)

The value "sec" specifies how long the 'write' commands blocks before  
it timeouts. The unit is seconds specified as a floting point which means  
that i.e. 0.1 can be specified for a maximum of 0.1 seconds blocking.  
This command can also be used with UDP packets, se the UDP section.  

[ip,port]=pnet(con,’gethost’)

This command call returns ipnumber and port number for the remote host  
that is (latest) associated with the connection/socket. After 'tcplisten'  
you can get the the clients ip and port numbers. After a 'tcpconnect'  
you can get the ip and port that you connected to.   
For UDP sockets this gives remote ip and and port for the latest operation  
of 'readpacket', 'writepacket' (if not connected) or 'udpconnect'.  

pnet(con,’close’)

Closes a tcpconnection, tcpsocket or udpsocket. This comand must be called  
after ending use of any socket or connection even, if its detected that the  
connection is broken from the remote host side.   
This command should also be used with UDP sockets, se the UDP section.  

pnet(‘closeall’)

Closes all pnet connections/sockets used in this matlab session.  

UDP packets

    With PNET it's possible send and receive UDP packets. Same read/write  
    commands can be used as for with TCP connection with the difference  
    that the operation is alway nonblocking and data is stored in the   
    read/write buffer in memory. With  pnet(sock,'writepacket'...) can the  
    created UDP packet in the write buffer be sent. And with   
    pnet(sock,'readpacket') a new packet can be recived before reading its  
    contents with read commands. The limitation is how big UDP packets  
    your network can transmitt. But about 65500 bytes is maximum.  

sock=pnet(‘udpsocket’,port);

Creates a UDP socket and binds it to an UDP port. On this socket can you  
recive UDP packets destinated to this UDP port, and send UDP packets with  
this sockat as source adress. Retruns -1 on fail or a handler \>=0 on  
success. In this sockets write buffer you can create a UDP packet that  
is later sent with the 'writepacket' command.   

pnet(sock,’udpconnect’,’hostname’,port);

With this command you can connect a destination host and port to the the  
UDP socket causing that the 'writepacket' commands should not have any  
'hostname' and port arguments supplied.  

pnet(sock,’writepacket’ [,’hostname’,port]);

Sends contents of the sockets write buffer as a UDP packet. If the UDP  
socket is not connected 'hostname' and port must be supplied, if connected  
the arguments is ignored.  

size=pnet(sock,’readpacket’[,maxsize][,’noblock’]);

Reads next incoming UDP packet on UDP socket "sock".  Unless 'noblock'  
is supplied as option it block until readtimeout or next UDP packet is  
received. The optional argument "maxsize" limits the size of the packet.  
The packet is stored in the sockets read buffer and can then be readed  
from the buffer with same commands as for TCP connections. When reciving  
a new packet old non used data from the last packet is discarded.  

General alternative syntax
==========================

  pnet 1 write Hello\_World  

is the same as

  pnet(1,'write','Hello\_World')  
  
Numbers like connection handlers and port-numbers can be specified  
as strings in most cases. This syntax should generaly work for all  
variants of calls and is usefull and easy to type when experimenting  
interactively with tcp connection and udp packets from the matlab  
prompt.  

SE ALSO: PNET_REMOTE, PNET_PUTVAR PNET_GETVAR, WEBGET_DEMO, POPMAIL_DEMO
UDP_PLOTTER_DEMO, UDP_SEND_DEMO, WEBSERVER_DEMO

GOOD LUCK and HAVE FUN! :-)

  Peter Rydesaeter,   
  Mitthoegskolan(Mid Sweden University) campus Oestersund, SWEDEN  
Path   Retrieve current version from GitHub | View changelog
Psychtoolbox/PsychHardware/iViewXToolbox/tcp_udp_ip/pnet.m