source: PlatformSupport/pnet/pnet.m

Last change on this file was 1915, checked in by murphpo, 11 years ago

initial commit of WARPLab7 code

File size: 11.3 KB
Line 
1% PNET    - IO-function for TCP and UDP comunation in matlab.
2%
3%
4%     This function can be called with different options/commands to operate on
5%     tcp/udp/ip connection in matlab. It supports data transfer with
6%     different data types and byte orders. The function is implemented as an
7%     MEX-file that needs to be
8%
9% General syntax
10% ==============
11%
12%        pnet('command',....)          or         pnet command  ....
13%   
14%        ppet(con,'command',....)      or         pnet con command ....
15
16%        ...where 'command' is a string specifying what to do. "con" is an
17%        connection handler holding a number that refers to an already open
18%        connection/socket. In the cases where "con" is specified before
19%        'command' is the commands associated to operate on that connection/
20%        socket. Connection handler number (and some other numbers like size
21%        values) can be specified as either a scalar value or a string
22%        containing the scalar number.
23
24% Commands for TCP connections
25% ============================
26
27%  con=pnet('tcpconnect','hostname',port)
28
29%     Creates tcp/ip connection to the specified 'hostname' and port. On error
30%     it returns -1, on success it returns a conection handler as an integer
31%     number >=0. This function call is used to act as a "tcp-client".
32%     This function is alway nonblocking unless their is some troubles with
33%     namelookup that can block interpretation for a while.
34
35%  sockcon=pnet('tcpsocket',port)
36
37%     Creates a local tcpsocket and bind port-number "port" to it. On fail
38%     it rerurns -1, on success it returns a connection handler. To fetch
39%     remote connection connecting to this socket use pnet(sockcon,'tcplisten')
40%     
41%  con=pnet(sockcon,'tcplisten', ['noblock'] )
42%     
43%     If some remote tcp-connection has connected to the socket "sockcon" this
44%     functions returns a handler to that tcp connection. On non available
45%     remote connection or error it returns -1. Unless the option 'noblock' is
46%     specified or the readtimeout value (default to inf ) is reached it blocks
47%     until a remote connection is established.
48%     
49%  elements=pnet(con,'write', data [,swapping])
50%     
51%     Writes all elements of the matlab array "data" to connection "con".
52%     Supported datatypes are: char, double, single, int8 int16, int32,
53%     uint8, uint16  and uint32. Arrays of datatype char is written as single
54%     bytes, all other datatypes are written as it matlabsize. By default
55%     the bytes are swapped to network byte order unless the swapping option
56%     is specified. Swapping options:
57%     'native'  no swapping use the computers native byte order.
58%     'swap'    allways swap byte order.
59%     'network' uses network byte order (little endian) and it is default.
60%     'intel'   use intel CPUs byte order (big endian).
61%     This operation blocks until writetimeout (is by default inf) is reached
62%     or all elements are transfered. Returns number of elements successfull
63%     written.     
64%     This command can also be used with UDP packets, se the UDP section.
65%
66%  pnet(con,'printf', 'format',.....)
67%     
68%     Prints a formated string to the connection "con". SPRINTF is used to
69%     process format string and following arguments. Se help on SPRINTF for more
70%     information. It block until writetimeout and returns number of characters
71%     succesfull written.
72%     This command can also be used with UDP packets, se the UDP section.
73%     
74%  data=pnet(con,'read' [,size] [,datatype] [,swapping] [,'view'] [,'noblock'])
75%     
76%     Reads an array of elements from a connection. Unless option 'noblock' is
77%     used the operation blocks until timeout is reached (by default inf), the
78%     specified "size" is reached or the connection is disconnected by peer.
79%     Specified "size" (by default 65536) can be a scalar or a vector of
80%     specifying dimentions length for the multidimentional array to read.
81%     If size is a scalar i.e. [10] it return 0 to 10 elements in a rowvector
82%     depening on available elements. If size is a vector i.e. [1 10] or [5 5 5]
83%     it returns an array if all elements is available, if not, an empty array
84%     is returned. The datatype option is a string containing the name of the
85%     datatype, if not specified its by default 'char'. Supported datatypes is
86%     the same as for the 'write' command.  The option named "swapping" is
87%     is the same for the 'read' command. The option 'view' gives an "preview"
88%     of whats available, all data is left in the read buffer. In combination
89%     with 'noblock' this is a powerfull command to check how much and whats
90%     available at the moment without blocking.
91%     This command can also be used with UDP packets, se the UDP section.
92%     
93%  str=pnet(con,'readline' [,limitsize] [,'view'] [,'noblock'])
94%     
95%     This commands works like 'read' but it reads a string of characters
96%     until the newline character (code=10) are reached.
97%     It returns the string without the newline character (or if exist just
98%     before, the carage return character code=13 ). If the character line
99%     is longer then the "limitsize" the line is splited at that length.
100%     The default value for limitsize is 65536.
101%     The function blocks unless a full line of characters are available or
102%     'noblock' is specified until readtimeout is reached. The 'view'
103%     option also leaves the returned characters in the read buffer.
104%     This command can also be used with UDP packets, se the UDP section.
105%     
106%  ret=pnet(con,'readtofile','filename'[,bytes][,'view'][,'noblock'][,'append'])
107%     
108%     Reads data of specified number of "bytes" to a file 'filename'. It
109%     returns successful number of bytes moved from the connection to the file.
110%     If the option string 'append' is specified the data will be appended
111%     th the end of the file, otherwise the file will be overwritten.
112%     'view', 'noblock' and timeout behaves as earlier described for read
113%     operations.
114%     This command can also be used with UDP packets, se the UDP section.
115%     
116%  ret=pnet(con,'writefromfile','filename'[[,start] ,len])
117%
118%     Read data from a file and write it on the connection. All of the
119%     file will be transmitted of not "start" and "len" specifies a segment.
120%     The function returns -1 on fail.
121%     This command can also be used with UDP packets, se the UDP section.
122%     
123%  stat=pnet(con,'status')
124%     
125%     This returns a number telling about the status of a connection/socket.
126%     It is a different number for each type of connection or socket se
127%     #define's in top of pnet.c. The most important status is when
128%     peer has disconnect the status value is 0 else it is >0.
129%     This command can also be used with UDP packets, se the UDP section.
130%
131%  stat=pnet(con,'setreadtimeout',sec)
132%     
133%     The value "sec" specifies how long read and listen commands blocks before
134%     it timeouts. The unit is seconds specified as a floting point which means
135%     that i.e. 0.1 can be specified for a maximum of 0.1 seconds blocking.
136%     Setting readtimeout to 0 is the same as adding the 'noblock' option to
137%     all followinging 'read' or 'listen' calls.
138%     This command can also be used with UDP packets, se the UDP section.
139%
140%  stat=pnet(con,'setwritetimeout',sec)
141%     
142%     The value "sec" specifies how long the 'write' commands blocks before
143%     it timeouts. The unit is seconds specified as a floting point which means
144%     that i.e. 0.1 can be specified for a maximum of 0.1 seconds blocking.
145%     This command can also be used with UDP packets, se the UDP section.
146%     
147%  [ip,port]=pnet(con,'gethost')
148%     
149%     This command call returns ipnumber and port number for the remote host
150%     that is (latest) associated with the connection/socket. After 'tcplisten'
151%     you can get the the clients ip and port numbers. After a 'tcpconnect'
152%     you can get the ip and port that you connected to.
153%     For UDP sockets this gives remote ip and and port for the latest operation
154%     of 'readpacket', 'writepacket' (if not connected) or 'udpconnect'.
155%
156%  pnet(con,'close')
157%
158%     Closes a tcpconnection, tcpsocket or udpsocket. This comand must be called
159%     after ending use of any socket or connection even, if its detected that the
160%     connection is broken from the remote host side.
161%     This command should also be used with UDP sockets, se the UDP section.
162%
163%  pnet('closeall')
164%
165%     Closes all pnet connections/sockets used in this matlab session.
166%
167% UDP packets
168% ===========
169
170%         With PNET it's possible send and receive UDP packets. Same read/write
171%         commands can be used as for with TCP connection with the difference
172%         that the operation is alway nonblocking and data is stored in the
173%         read/write buffer in memory. With  pnet(sock,'writepacket'...) can the
174%         created UDP packet in the write buffer be sent. And with
175%         pnet(sock,'readpacket') a new packet can be recived before reading its
176%         contents with read commands. The limitation is how big UDP packets
177%         your network can transmitt. But about 65500 bytes is maximum.
178%     
179%  sock=pnet('udpsocket',port);
180%     
181%     Creates a UDP socket and binds it to an UDP port. On this socket can you
182%     recive UDP packets destinated to this UDP port, and send UDP packets with
183%     this sockat as source adress. Retruns -1 on fail or a handler >=0 on
184%     success. In this sockets write buffer you can create a UDP packet that
185%     is later sent with the 'writepacket' command.
186%     
187%  pnet(sock,'udpconnect','hostname',port);
188%     
189%     With this command you can connect a destination host and port to the the
190%     UDP socket causing that the 'writepacket' commands should not have any
191%     'hostname' and port arguments supplied.
192%     
193%  pnet(sock,'writepacket' [,'hostname',port]);
194%     
195%     Sends contents of the sockets write buffer as a UDP packet. If the UDP
196%     socket is not connected 'hostname' and port must be supplied, if connected
197%     the arguments is ignored.
198%     
199%  size=pnet(sock,'readpacket'[,maxsize][,'noblock']);
200%     
201%     Reads next incoming UDP packet on UDP socket "sock".  Unless 'noblock'
202%     is supplied as option it block until readtimeout or next UDP packet is
203%     received. The optional argument "maxsize" limits the size of the packet.
204%     The packet is stored in the sockets read buffer and can then be readed
205%     from the buffer with same commands as for TCP connections. When reciving
206%     a new packet old non used data from the last packet is discarded.
207%
208%  General alternative syntax
209%  ==========================
210%
211%       pnet 1 write Hello_World
212%     
213%    is the same as   
214%     
215%       pnet(1,'write','Hello_World')
216%     
217%     Numbers like connection handlers and port-numbers can be specified
218%     as strings in most cases. This syntax should generaly work for all
219%     variants of calls and is usefull and easy to type when experimenting
220%     interactively with tcp connection and udp packets from the matlab
221%     prompt.
222%
223%
224%   SE ALSO: PNET_REMOTE, PNET_PUTVAR PNET_GETVAR, WEBGET_DEMO, POPMAIL_DEMO
225%            UDP_PLOTTER_DEMO, UDP_SEND_DEMO, WEBSERVER_DEMO
226%
227%
228%   GOOD LUCK and HAVE FUN!  :-)
229%
230%       Peter Rydesäter,
231%       Mitthögskolan(Mid Sweden University) campus Östersund, SWEDEN
232%
233
234error('You need to compile pnet.c to a mex-file for your platform. Read the header of pnet.c');
Note: See TracBrowser for help on using the repository browser.