idllib

Personal IDL library for M. Galloy

single page | use frames     summary     class     fields     routine details     file attributes

net/

mgnetsocket__define.pro

networking

includes main-level program

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

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::close

mgnetsocket::close

Close a socket.

top source mgnetsocket::setProperty

mgnetsocket::setProperty

Set properties of the socket.

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'

top source mgnetsocket::cleanup

mgnetsocket::cleanup

Free resources held by the socket object.

top source mgnetsocket::init

result = mgnetsocket::init( [sockId])

Create a socket object.

Return value

1 for success, 0 for failure

Parameters

sockId in optional type=long

socket identifier

top source mgnetsocket__define

mgnetsocket__define

Defines instance variables.

File attributes

Modification date: Wed Jul 6 13:05:01 2011
Lines: 796
Docformat: rst rst
Personal library of Michael Galloy
Contact me if you have enhancement requests or bug fixes.