net/
mgnetsocket__define.pro
networking
The MGnetSocket class implements client and server-side internet sockets using the TCP/IP or UDP/IP protocols.
This class was originally developed to provide UDP/IP support in IDL. While it provides a few methods that may be convienient, if you need TCP/IP client sockets you may want to consider the built in support in IDL.
This class depends on the idl_net DLM which provides the interface to the OS
sockets library. This DLM is based *heavily* on Randall Frank's idl_sock.c
code distributed with his idl_tools DLM.
Note on byteswapping: Make sure you swap in the correct place. If you are
reading into the buffer, and you are extracting other than byte type you
need to swap on the call to ReadBuffer. If you are simply receiving data via
::receive or extracting byte data from ::readBuffer then you can swap on
either the call to ::receive or ::readBuffer.
Examples
Try the main-level program at the end of this file:
IDL> .run mgnetsocket__define
Author information
- History
Original written by Randall Frank in idl_sock.c in his idl_tools DLM Modified by Rick Towler, 20 July 2007 Modified by Michael Galloy
Other file information
- Todo:
Should add in a network endianess property so that swapping is automagic. This would require Receive to be modified such that Rx'ing to buffer would not swap even if the local and remote endianess were different. Further, if receiving to buffer, data should not be returned to the caller so there is no confusion. If this endianess property is undefined (the default) no swapping is performed.
Class description for mgnetsocket
Properties
Properties in mgnetsocket
- localhost get
- localport get
- open get
true if the socket is open, false if not
- remotehost get
- remoteport get
- type get
type of connection: 'LISTEN_TCP', 'UDP', 'IO_TCP', 'PEERED_UDP'
Routines
Routines from mgnetsocket__define.pro
result = mgnetsocket::connect(destHost, destPort, buffer=buffer, localPort=localPort, nodelay=nodelay, udp=udp, tcp=tcp)Connect to a TCP socket listener on a specified host and port or opens a UDP socket and sets its default destination host and port.
result = mgnetsocket::createPort( [locPort] [, /tcp] [, /udp])Creates a socket listening on the specified port.
result = mgnetsocket::accept(buffer=buffer, nodelay=nodelay [, timeout=long])Accepts a requested TCP/IP connection and returns an MGnetSocket on which I/O can be performed.
result = mgnetsocket::send(data)Send data.
result = mgnetsocket::sendTo(data, destHost, destPort)Send data to a specified host and port.
result = mgnetsocket::receive( [/byteswap] [, data=array] [, /tobuffer])Receive data.
result = mgnetsocket::readBuffer( [nbytes] [, /byteswap] [, nels=long] [, /peek] [, skipbytes=long] [, type=string])Return data stored in the local (object's) buffer.
result = mgnetsocket::name2Host( [name])Return a host ID as ULONG given a string hostname.
result = mgnetsocket::host2Name( [hostId])Return a hostname as string given a ULONG host ID.
result = mgnetsocket::check()Return the number of bytes waiting in the socket buffer.
mgnetsocket::closeClose a socket.
mgnetsocket::setPropertySet properties of the socket.
mgnetsocket::getProperty, localhost=localhost, localport=localport, open=open, remotehost=remotehost, remoteport=remoteport, type=typeGet properties of the socket.
mgnetsocket::cleanupFree resources held by the socket object.
result = mgnetsocket::init( [sockId])Create a socket object.
mgnetsocket__defineDefines instance variables.
Routine details
top mgnetsocket::connect
result = mgnetsocket::connect(destHost, destPort, buffer=buffer, localPort=localPort, nodelay=nodelay, udp=udp, tcp=tcp)
Connect to a TCP socket listener on a specified host and port or opens a UDP socket and sets its default destination host and port.
Parameters
- destHost
- destPort
Keywords
- buffer
- localPort
- nodelay
- udp
- tcp
top mgnetsocket::createPort
result = mgnetsocket::createPort( [locPort] [, /tcp] [, /udp])
Creates a socket listening on the specified port. Socket can be either TCP or UDP based. Specify a local port of 0 to allow the OS to select an open port for you.
Return value
Parameters
- locPort in optional type=long
port to create; the OS will select an open port if this parameter is undefined or set to 0
Keywords
- tcp in optional type=boolean
set to create a TCP port
- udp in optional type=boolean
set to create a UDP port
top mgnetsocket::accept
result = mgnetsocket::accept(buffer=buffer, nodelay=nodelay [, timeout=long])
Accepts a requested TCP/IP connection and returns an MGnetSocket on which I/O can be performed.
Return value
MGnetSocket object
Keywords
- buffer
- nodelay
- timeout in optional type=long default=0L
timeout
top mgnetsocket::send
result = mgnetsocket::send(data)
Send data.
Return value
number of bytes send
Parameters
- data in required type=array
data to send
top mgnetsocket::sendTo
result = mgnetsocket::sendTo(data, destHost, destPort)
Send data to a specified host and port.
Return value
number of bytes sent
Parameters
- data in required type=array
data to send
- destHost in required type=string or ulong
host to sent data to specified as a hostname or host identifier
- destPort in required type=long
host port
top mgnetsocket::receive
result = mgnetsocket::receive( [/byteswap] [, data=array] [, /tobuffer])
Receive data.
Return value
number of bytes received as a long; errors will return a negative value
Keywords
- byteswap in optional type=boolean
set to swap the byte order of the returned data
- data out optional type=array
set to a named variable to return the received data
- tobuffer in optional type=boolean
set to put data in buffer to be read later by readBuffer method
top mgnetsocket::readBuffer
result = mgnetsocket::readBuffer( [nbytes] [, /byteswap] [, nels=long] [, /peek] [, skipbytes=long] [, type=string])
Return data stored in the local (object's) buffer. This method can be used to return specific data types, even mixed types, from the buffer by specifying the type.
Returns NaN if the buffer is empty.
Return value
array of the type specified by the TYPE keyword
Parameters
- nbytes out optional type=long
number of bytes read
Keywords
- byteswap in optional type=boolean
set to swap endianness of data
- nels in out optional type=long
the number of elements read; if not specified, as many elements as possible are read
- peek in optional type=boolean
set the peek keyword to "take a peek" at data but not remove it from the buffer
- skipbytes in optional type=long
bytes to skip at the beginning of the buffer
- type in optional type=string
type of data: 'integer', 'double', 'float', 'long', 'string', 'uint', 'ulong', 'l64', or 'ul64'; if not specified or not one of the above types, data is returned as bytes
top mgnetsocket::name2Host
result = mgnetsocket::name2Host( [name])
Return a host ID as ULONG given a string hostname.
Return value
long
Parameters
- name in optional type=string
hostname
top mgnetsocket::host2Name
result = mgnetsocket::host2Name( [hostId])
Return a hostname as string given a ULONG host ID.
Return value
string
Parameters
- hostId in optional type=ulong
host identifier
top mgnetsocket::check
result = mgnetsocket::check()
Return the number of bytes waiting in the socket buffer.
Return value
long
top mgnetsocket::getProperty
mgnetsocket::getProperty, localhost=localhost, localport=localport, open=open, remotehost=remotehost, remoteport=remoteport, type=type
Get properties of the socket.
Keywords
- localhost
- localport
- open
true if the socket is open, false if not
- remotehost
- remoteport
- type
type of connection: 'LISTEN_TCP', 'UDP', 'IO_TCP', 'PEERED_UDP'
File attributes
| Modification date: | Wed May 14 15:07:14 2014 |
| Lines: | 399 |
| Docformat: | rst rst |
Contact me if you have enhancement requests or bug fixes.