/ 
IO-Socket-TIPC-0.04
River stage zero No dependents
/ IO::Socket::TIPC::Sockaddr

NAME

IO::Socket::TIPC::Sockaddr - struct sockaddr_tipc object

SYNOPSIS

use IO::Socket::TIPC::Sockaddr;

DESCRIPTION

TIPC Sockaddrs are used with TIPC sockets, to specify local or remote endpoints for communication. They are used in the bind(), connect(), sendto() and recvfrom() calls.

CONSTRUCTOR

new ( "string", key=>value, key=>value... )
new ( key=>value, key=>value... )
new_from_data ( $binary_blob_of_struct_sockaddr_tipc )

Creates an "IO::Socket::TIPC::Sockaddr" object, which is really just a bunch of fluff to manage C "struct sockaddr_tipc" values in an intuitive fashion.

The new() constructor takes a series of Key => Value pairs as arguments. It needs an AddrType argument, but it can often guess this from the other values you've passed, because different address types take a different set of params. new() can also take a text string as its first (or only) argument, which should be a stringized form of the address you want. new can also guess the AddrType from context (in string form or from the other attributes), if you provide enough.

If you intend to use a TIPC sockaddr for a local port name or nameseq, you should provide the Scope parameter, to specify how far away connections can come in from. Please see the TIPC Programmers_Guide.txt for details. The default is TIPC_NODE_SCOPE. You can specify the Scope as one of the TIPC_*_SCOPE constants, or as a string, "node", "cluster" or "zone".

If you intend to use a "name"-type sockaddr, you might also want to provide the Domain parameter, to specify how TIPC should search for the peer. This param takes a TIPC address as its argument, which can be a string, like "<1.2.3>", or a number, like 0x01002003. Please see the TIPC Programmers_Guide.txt for details. The default is "<0.0.0>", which means, "gimme the closest node you can find, and search the whole network if you have to".

Sockaddrs can be broken down into 3 address-types, "name", "nameseq" and "id". Again, the Programmers_Guide.txt explains this stuff much better than I ever could, you should read it.

name

You can use "name" sockets in the following manner:

$name = IO::Socket::TIPC::Sockaddr->new(
	AddrType => 'name',
	Type => 4242,
	Instance => 1005);

Or

$name = IO::Socket::TIPC::Sockaddr->new(
	AddrType => 'name',
	Name => '{4242, 1005}');

Or, even

$name = IO::Socket::TIPC::Sockaddr->new('{4242, 1005}');

With all address types, the stringify() method will return something readable.

$string = $name->stringify();
# stringify returns "{4242, 1005}"

nameseq

You can use "nameseq" sockets in the following manner:

$nameseq = IO::Socket::TIPC::Sockaddr->new(
	AddrType => 'nameseq',
	Type     => 4242,
	Lower    => 100,
	Upper    => 1000);

Or, more simply,

$nameseq = IO::Socket::TIPC::Sockaddr->new(
	AddrType => 'nameseq',
	Name     => '{4242, 100, 1000}');

Or even just

$nameseq = IO::Socket::TIPC::Sockaddr->new('{4242, 100, 1000}');

If you don't specify an Upper, it defaults to the Lower. If you don't specify a Lower, it defaults to the Upper. You must specify at least one.

$nameseq = IO::Socket::TIPC::Sockaddr->new(
	AddrType => 'nameseq',
	Type => 4242,
	Lower => 100);

With all address types, the stringify() method will return something readable.

$string = $nameseq->stringify();
# stringify returns "{4242, 100, 100}"

id

You can use "id" sockets in the following manner:

$id = IO::Socket::TIPC::Sockaddr->new(
	AddrType => 'id',
	Zone     => 1,
	Cluster  => 2,
	Node     => 3,
	Ref      => 5000);

Or, more simply,

$id = IO::Socket::TIPC::Sockaddr->new(
	AddrType => 'id',
	Id       => "<1.2.3>",
	Ref      => 5000);

Or, more simply,

$id = IO::Socket::TIPC::Sockaddr->new(
	AddrType => 'id',
	Id       => "<1.2.3:5000>");

Or even just

$id = IO::Socket::TIPC::Sockaddr->new("<1.2.3:5000>");

With all address types, the stringify() method will return something readable.

$string = $id->stringify();
# stringify returns "<1.2.3:5000>"

METHODS

stringify()

stringify returns a string representing the sockaddr. These strings are the same as the ones used in the TIPC documentation, see Programmers_Guide.txt. Depending on the address type, it will return something that looks like one of:

"<1.2.3:4>"        # ID, addr = 1.2.3, ref = 4
"{4242, 100}"      # NAME, type = 4242, instance = 100
"{4242, 100, 101}" # NAMESEQ, type = 4242, range 100-101

Note that these strings are intended for use as shorthand, with someone familiar with TIPC. They do not include all the (potentially important) fields of the sockaddr structure. In particular, they are missing the Scope and Domain fields, which affect how far away binding/connecting may occur for names and nameseqs. If you need to store an address for reuse, you are better off reusing the Sockaddr object itself, rather than storing one of these strings.

raw()

raw returns a string containing the packed sockaddr_tipc structure. It is suitable for passing to bind(), connect(), sendto(), and so forth.

$sock->sendto($addr->raw(), "Hello!  My brain hurts.");

bits is an alias for raw.

HELPER ROUTINES

unpack_tipc_addr(int)

Unpacks a TIPC address (integer) into its constituent components. Returns a hash reference containing the components of the address.

my $href = unpack_tipc_addr(0x01002003);
printf("<%i.%i.%i>\n",
       @$href{'Zone', 'Cluster', 'Node'}); # prints <1.2.3>

pack_tipc_addr(zone, cluster, node)

Packs components of a TIPC address into a real address (integer). Takes the zone, cluster and node components as arguments, in that order. Returns the address.

my $addr = pack_tipc_addr(1, 2, 3);
printf("%x\n", $addr); # prints 0x01002003

parse_string(hashref, string)

Given a string that looks like "<1.2.3:4>", "<1.2.3>", "{1, 2}", or "{1, 2, 3}", chop it into its components. Puts the components into appropriately named keys in hashref, like Zone, Cluster, Node, Ref, Type, Instance, Upper, Lower. It also gives you the AddrType of the string you passed. Returns 1 on success, croaks on error.

my $href = {};
parse_string($href, "<1.2.3:4>");
printf("Address <%i.%i.%i:%i> is of type %s\n",
	 @$href{'Zone', 'Cluster', 'Node', 'Ref', 'AddrType'});
# prints "Address <1.2.3:4> is of type id\n"

This is a function which new() uses internally, to turn whatever garbage it's been given into some values it can actually use. You don't have to call it directly, unless you want to use the same parser for some other reason, like input checking.

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, Socket, IO::Socket::TIPC, 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.