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

NAME

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

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.

Sockaddrs can be broken down into 3 address-types, "name", "nameseq" and "id". 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>"

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 where TIPC should start, as it searches for a peer to connect to, and how far to search. 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".

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.

get/set routines

The C structure has roughly the following format: struct sockaddr_tipc { unsigned short family; unsigned char addrtype; signed char scope; union { struct { __u32 ref; __u32 node; } id; struct { __u32 type; __u32 lower; __u32 upper; } nameseq; struct { struct { __u32 type; __u32 instance; } name; __u32 domain; } name; } addr; };

Each of these fields has methods to get and set it. The only exception is "family", which only has a "get" method (Otherwise this module would break). An exhaustive list of these methods follows:

global stuff
get_family()
get_addrtype()		set_addrtype(val)
get_scope()			set_scope(val)
TIPC_ADDR_ID stuff
get_ref()			set_ref(val)
get_id()			set_id(val)
get_zone()			set_zone(val)
get_cluster()		set_cluster(val)
get_node()			set_node(val)
TIPC_ADDR_NAME stuff
get_ntype()			set_ntype(val)
get_instance()		set_instance(val)
get_domain()        set_domain(val)
TIPC_ADDR_NAME stuff
get_stype()			set_stype(val)
get_lower()			set_lower(val)
get_upper()			set_upper(val)
Type helpers
get_type()			set_type(arg)

These functions call either get_ntype/set_ntype, or get_stype/set_stype, depending on the addrtype.

Finally, some wrappers to choose nameseq.type versus name.name.type. These are only here just in case they change the sockaddr_tipc structure so the two no longer share the same memory location via a union. Pretty unlikely...

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.