/ 
IO-Socket-TIPC-0.02
River stage zero No dependents
/ IO::Socket::TIPC

NAME

IO::Socket::TIPC - Perl sockets for TIPC

SYNOPSIS

use IO::Socket::TIPC;
my $sock = IO::Socket::TIPC->new(
	Type => 'stream',
	Peer => '{1000,100}'
);

DESCRIPTION

TIPC stands for Transparent Inter-Process Communication. See http://tipc.sf.net/ for details.

This perl module subclasses IO::Socket, in order to use TIPC sockets in the customary (and convenient) Perl fashion.

EXPORT

None by default.

Exportable constants

":tipc" tag (defines from tipc.h):
AF_TIPC
PF_TIPC
SOL_TIPC
TIPC_ADDR_ID
TIPC_ADDR_MCAST
TIPC_ADDR_NAME
TIPC_ADDR_NAMESEQ
TIPC_CFG_SRV
TIPC_CLUSTER_SCOPE
TIPC_CONN_SHUTDOWN
TIPC_CONN_TIMEOUT
TIPC_CRITICAL_IMPORTANCE
TIPC_DESTNAME
TIPC_DEST_DROPPABLE
TIPC_ERRINFO
TIPC_ERR_NO_NAME
TIPC_ERR_NO_NODE
TIPC_ERR_NO_PORT
TIPC_ERR_OVERLOAD
TIPC_HIGH_IMPORTANCE
TIPC_IMPORTANCE
TIPC_LOW_IMPORTANCE
TIPC_MAX_USER_MSG_SIZE
TIPC_MEDIUM_IMPORTANCE
TIPC_NODE_SCOPE
TIPC_OK
TIPC_PUBLISHED
TIPC_RESERVED_TYPES
TIPC_RETDATA
TIPC_SRC_DROPPABLE
TIPC_SUBSCR_TIMEOUT
TIPC_SUB_NO_BIND_EVTS
TIPC_SUB_NO_UNBIND_EVTS
TIPC_SUB_PORTS
TIPC_SUB_SERVICE
TIPC_SUB_SINGLE_EVT
TIPC_TOP_SRV
TIPC_WAIT_FOREVER
TIPC_WITHDRAWN
TIPC_ZONE_SCOPE

":socktypes" tag (exports from Socket.pm):
SOCK_STREAM
SOCK_DGRAM
SOCK_SEQPACKET
SOCK_RDM

To get all of the above constants, say:

use IO::Socket::TIPC ':all';

To get all of the tipc stuff, say:

use IO::Socket::TIPC ':tipc';

To get only the socket stuff, say:

use IO::Socket::TIPC ':socktypes';

To get only the constants you plan to use, say something like:

use IO::Socket::TIPC qw(SOCK_RDM TIPC_NODE_SCOPE);

Despite supporting all the above constants, please note that some effort was made so normal users won't actually need any of them. For instance, in place of the SOCK_* socktypes, you can just specify "stream", "dgram", "seqpacket" or "rdm". In place of the TIPC_*_SCOPE defines, given to Sockaddr's Scope parameter, you can simply say "zone", "cluster" or "node".

CONSTRUCTOR

new returns a TIPC socket object. This object inherits from IO::Socket, and thus inherits all the methods of that class.

This module was modeled specifically after IO::Socket::INET, and shares some things in common with that class. Specifically, the Listen parameter, the Peer* and Local* nomenclature, and the behind-the-scenes calls to socket(), bind(), listen(), connect(), and what have you.

Connection-based sockets (SOCK_STREAM and SOCK_SEQPACKET) come in "listen" and "connect" varieties. To create a listener socket, specify Listen => 1 in your parameter list. You can bind a name to the socket, by providing a parameter like LocalName => '{4242, 100}'. To create a connection socket, provide one or more Peer* parameters.

All Local* parameters are passed directly to IO::Socket::TIPC::Sockaddr->new(), minus the 'Local' prefix, and the resulting sockaddr is passed to bind(). Similarly, all Peer* parameters are passed directly to IO::Socket::TIPC::Sockaddr->new(), minus the 'Peer' prefix, and the result is passed to connect(). The keywords Local and Peer themselves become the first string parameter to new(); see the IO::Socket::TIPC::Sockaddr documentation for details.

Examples of connection-based socket use:

# Create a server listening on Name {4242, 100}.
$sock1 = IO::Socket::TIPC->new(
	SocketType => 'stream',
	Listen => 1,
	LocalAddrType => 'name',
	LocalType => 4242,
	LocalInstance => 100,
	LocalScope => 'zone',
);

# Connect to the above server
$sock2 = IO::Socket::TIPC->new(
	SocketType => 'stream',
	PeerAddrType => 'name',
	PeerType => 4242,
	PeerInstance => 100,
	PeerDomain => '<0.0.0>',
);

Or the short versions of the same thing:

# Create a server listening on Name {4242, 100}.
$sock1 = IO::Socket::TIPC->new(
	SocketType => 'seqpacket',
	Listen => 1,
	Local => '{4242, 100}',
	LocalScope => 'zone',
);

# Connect to the above server
$sock2 = IO::Socket::TIPC->new(
	SocketType => 'seqpacket',
	Peer => '{4242, 100}',
);

Connectionless sockets (SOCK_RDM and SOCK_DGRAM) have no concept of connecting or listening, but may still be bind()ed to a Name or Nameseq. You can use LocalName or LocalNameseq parameters to select a name or name-sequence to bind to. As above, these parameters internally become Name and Nameseq arguments to IO::Socket::TIPC::Sockaddr->new(), and the result is passed to bind().

Since connectionless sockets are not linked to a particular peer, you can use sendto to send a packet to some peer with a given Name in the network, and recvfrom to receive replies from a peer in the network who sends a packet to your Name. You can also use Nameseq to send multicast packets to *every* peer with a given name. Please see the TIPC project's Programmers_Guide.txt document for more details.

Examples of connectionless socket use:

# Create a server listening on Name {4242, 100}.
$sock1 = IO::Socket::TIPC->new(
	SocketType => 'rdm',
	Local => '{4242, 100}',
	LocalScope => 'zone',
);

# Create another server listening on Name {4242, 101}.
$sock2 = IO::Socket::TIPC->new(
	SocketType => 'rdm',
	Local => '{4242, 101}',
	LocalScope => 'zone',
);

$data = "TAG!  You're 'it'.";

# send a hello packet from sock2 to sock1
$addr1 = IO::Socket::TIPC::Sockaddr->new("{4242, 100}");
$sock2->sendto($addr1, $data, length($data));

# receive that first hello packet
$sender_addr = $sock1->recvfrom($rxdata, 256);

# send a (multicast) packet from sock1 to sock2's, everywhere
$maddr2 = IO::Socket::TIPC::Sockaddr->new("{4242, 101, 101}");
$sock1->sendto($maddr2, "My brain hurts!");

BUGS

Probably many. Please report any bugs you find to the author. A TODO file exists, which lists known unimplemented and broken stuff.

SEE ALSO

IO::Socket, IO::Socket::TIPC::Sockaddr, http://tipc.sf.net/, http://tipc.cslab.ericcson.net/, Programmers_Guide.txt.

AUTHOR

Mark Glines <mark-tipc@glines.org>

COPYRIGHT AND LICENSE

This module is licensed under a dual BSD/GPL license, the same terms as TIPC itself.