net/
mgnetsocket__define.pro
networking
includes main-level programThe 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
Class description for mgnetsocket
Properties
- remotehost get
- open get
true if the socket is open, false if not
- localport get
- localhost get
- type get
type of connection: 'LISTEN_TCP', 'UDP', 'IO_TCP', 'PEERED_UDP'
- remoteport get
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.
Routines
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::close
Close a socket.
mgnetsocket::setProperty
Set properties of the socket.
mgnetsocket::getProperty, localhost=localhost, localport=localport, open=open, remotehost=remotehost, remoteport=remoteport, type=type
Get properties of the socket.
mgnetsocket::cleanup
Free resources held by the socket object.
result = mgnetsocket::init( [sockId])
Create a socket object.
mgnetsocket__define
Defines instance variables.
Routine details
top source 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 source 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 source 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 source mgnetsocket::send
result = mgnetsocket::send(data)
Send data.
Return value
number of bytes send
Parameters
- data in required type=array
data to send
top source 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 source 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 source 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 source 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 source 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 source mgnetsocket::check
result = mgnetsocket::check()
Return the number of bytes waiting in the socket buffer.
Return value
long
top source 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 Jul 6 13:05:01 2011 |
Lines: | 796 |
Docformat: | rst rst |
Contact me if you have enhancement requests or bug fixes.