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

NAME

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

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);

# 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!");

METHODS

sendto(addr, message [, flags])

sendto is used with connectionless sockets, to send a message to a given address. The addr parameter should be an IO::Socket::TIPC::Sockaddr object.

my $addr = IO::Socket::TIPC::Sockaddr->new("{4242, 100}");
$sock->sendto($addr, "Hello there!\n");

You may have noticed that sendto and Perl's builtin send do more or less the same thing with the order of arguments changed. The main reason to use sendto is because you can pass it a IO::Socket::TIPC::Sockaddr object directly, where send requires you to call its ->raw() method to get at the raw binary "struct sockaddr_tipc" data. So, sendto is just a matter of convenience.

Ironically, this sendto method calls perl's send builtin, which in turn calls the C sendto function.

recvfrom(buffer, length [, flags])

recvfrom is used with connectionless sockets, to receive a message from a peer. It returns a IO::Socket::TIPC::Sockaddr object, containing the address of the message's sender. NOTE! You must pass a *REFERENCE* to the buffer, since it will be written to.

my $buffer;
my $sender = $sock->recvfrom(\$buffer, 30);
$sock->sendto($sender, "I got your message.");

You may have noticed that recvfrom and Perl's builtin recv do more or less the same thing with the order of arguments changed. The main reason to use recvfrom is because it will return a IO::Socket::TIPC::Sockaddr object, where recv just returns a binary blob containing the C "struct sockaddr_tipc" data.

Ironically, this recvfrom method calls perl's recv builtin, which in turn calls the C recvfrom function.

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>

ACKNOWLEDGEMENTS

Thanks to Ericcson and Wind River, of course, for open-sourcing their (very useful!) network code, and performing the enormous maintenance task of getting it into the stock Linux kernel. Respect.

More specifically, thanks to the TIPC maintainers, for doing all the work bringing TIPC to linux, and making all of this possible. And thanks especially to Allan Stephens for patiently testing all of my pathetic, bug-ridden alpha releases. :)

Hrm, who else... thanks Larry Wall, thanks Linus Torvalds, etc etc, these ACKNOWLEDGEMENTS sections do tend to drone on and on, don't they.

COPYRIGHT AND LICENSE

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